diff --git a/NEWS.md b/NEWS.md index 49fc0d6..047afae 100644 --- a/NEWS.md +++ b/NEWS.md @@ -20,6 +20,10 @@ correction factor. - `cumulative_interval()` no longer truncates results to integers (e.g. a median of 26.5). +- `constrained_accessibility(constraint = "doubly")` now always returns + origin-destination flows and ignores `active` and `detailed_results`. + Previously, `detailed_results = FALSE` returned the demand and supply + marginals instead (#67). ## Bug fixes @@ -44,11 +48,12 @@ `fill_missing_ids = TRUE` and `group_by` leave combinations missing. - `constraint = "total"` no longer adds an index to the user's `land_use_data`. - - `constraint = "total"` and `"singly"` now treat each `group_by` - combination and each decay value as an independent system. Previously, - `"total"` split the regional total across groups and both blended - several decay values into one result. Detailed results now keep the - `group_by` and `decay_function_arg` columns (#66, @soukhova). + - `constraint = "total"`, `"singly"` and `"doubly"` now treat each + `group_by` combination and each decay value as an independent system. + Previously, `"total"` split the regional total across groups, `"doubly"` + balanced all groups as a single system, and all three blended several + decay values into one result. Detailed results now keep the `group_by` + and `decay_function_arg` columns (#66, @soukhova). - `cost_to_closest()` no longer returns `Inf` due to integer overflow with large opportunity counts. - `cumulative_cutoff()`: cutoffs with floating point noise (e.g. from diff --git a/R/constrained_accessibility.R b/R/constrained_accessibility.R index 4a6c86b..2846de3 100644 --- a/R/constrained_accessibility.R +++ b/R/constrained_accessibility.R @@ -29,7 +29,10 @@ #' in the doubly-constrained case (`constraint = "doubly"`). #' @template group_by #' @template fill_missing_ids_combinations -#' @param detailed_results Logical. Whether to return detailed OD-level results. +#' @param detailed_results Logical. Whether to return detailed OD-level +#' results for `constraint = "total"`- and `constraint = "singly"` +#' accessibility. Currently ignored for `constraint = "doubly"` accessibility, +#' which always returns OD-level flows. #' #' #' @section Details: @@ -45,7 +48,9 @@ #' group's rows. #' #' As well, when `fill_missing_ids = TRUE`, ids that are absent from a particular -#' group's rows are still returned with accessibility equal to 0. +#' group's rows are still returned with accessibility equal to 0. This doesn't +#' apply to `constraint = "doubly"`, which ignores `fill_missing_ids` and +#' returns every origin-destination pair of the ids in each group. #' #' ## Total Constrained Accessibility #' @@ -166,12 +171,13 @@ #' ### Requirements: #' - Both `demand` and `supply` must be provided. #' - Unlike `total` and `singly`, `doubly` requires the sum of demand and supply -#' to match; otherwise, the model will not converge. -#' - `active` must be `NULL`. Since supply must match demand, their units are -#' the same and there is no distinction between 'active' and 'passive' notions. -#' - Should be used with `detailed_results = TRUE`. With -#' `detailed_results = FALSE`, it only returns the demand and supply -#' marginals, with a warning. +#' to match; otherwise, an error is raised. When `group_by` or multiple decay +#' values are used, the totals must match within each independently balanced +#' system. +#' - `active` is ignored. Since supply must match demand, their units are +#' the same and there is no distinction between 'active' and 'passive' notions. +#' - `detailed_results` is currently ignored for doubly-constrained +#' accessibility. OD-level flows are always returned. #' #' ### Interpretation: #' - Results include OD-level flows (`flow`) along with balancing factors (`A_i`, @@ -202,17 +208,13 @@ #' origin-destination pair, with the columns `from_id`, `to_id`, the #' allocation share (`kappa_singly` or `hatkappa_singly`), the allocated flow #' (`supply` or `demand`) and the balancing factor (`B_j` or `A_i`). -#' - `constraint = "doubly"`, `detailed_results = TRUE`: one row per -#' origin-destination pair, with the columns `from_id`, `to_id`, `flow`, the -#' balancing factors `A_i` and `B_j`, `kappa_doubly` and the final balancing -#' `error`. -#' - `constraint = "doubly"`, `detailed_results = FALSE`: the columns `id` -#' and `flow`, holding the demand of each origin followed by the supply of -#' each destination (so an id can appear twice). -#' -#' For `constraint = "total"` and `"singly"`, detailed results include the -#' `group_by` columns and, when the decay function has several values, -#' `decay_function_arg`. +#' - `constraint = "doubly"`: one row per origin-destination pair, with the +#' columns `from_id`, `to_id`, `flow`, the balancing factors `A_i` and `B_j`, +#' `kappa_doubly` and the final balancing `error`. `detailed_results` and +#' `active` are not read. +#' +#' Detailed results include the `group_by` columns and, when the decay +#' function has several values, `decay_function_arg`. #' #' @references #' \insertAllCited{} @@ -268,7 +270,7 @@ #' ) #' #' # Doubly-constrained: returns units of flow (requires both demand and supply -#' # (totals that match) and `detailed_results = TRUE`) +#' # with matching totals) #' #' # Using a small toy dataset with matching totals. #' tm_small <- data.table::data.table( @@ -288,8 +290,18 @@ #' constraint = "doubly", #' decay_function = decay_exponential(0.1), #' demand = "population", -#' supply = "jobs", -#' detailed_results = TRUE +#' supply = "jobs" +#' ) +#' +#' # With several decay values, each one is balanced separately +#' constrained_accessibility( +#' travel_matrix = tm_small, +#' land_use_data = lu_small, +#' travel_cost = "travel_time", +#' constraint = "doubly", +#' decay_function = decay_exponential(c(0.1, 0.5)), +#' demand = "population", +#' supply = "jobs" #' ) #' #' @export diff --git a/R/doubly_constrained.R b/R/doubly_constrained.R index b02013c..b776fd3 100644 --- a/R/doubly_constrained.R +++ b/R/doubly_constrained.R @@ -8,8 +8,8 @@ #' #' @name doubly_constrained #' @keywords internal -#' @return A `data.table`/`data.frame` with either OD-level flows (`detailed_results = TRUE`) -#' or marginals; see Details. +#' @return A `data.table`/`data.frame` with origin-destination flows, balancing +#' factors (`A_i`, `B_j`), and doubly-constrained weights (`kappa_doubly`). #' @examples NULL #' @importFrom utils globalVariables utils::globalVariables(c( @@ -22,89 +22,65 @@ utils::globalVariables(c( # doubly-constrained "kappa_doubly", "flow", "error" )) -doubly_constrained <- function(travel_matrix, - land_use_data, - travel_cost, - decay_function, - demand, - supply, - error_threshold = 0.001, - improvement_threshold = 1e-6, - max_iterations = 1000, - active, - group_by = character(0), - fill_missing_ids = TRUE, - detailed_results = FALSE - ) { - # Validate inputs - checkmate::assert_string(demand) - checkmate::assert_string(supply) - checkmate::assert_number(error_threshold, lower = 0) - checkmate::assert_number(improvement_threshold, lower = 0) - checkmate::assert_int(max_iterations, lower = 1) - - # Convert to data.table - if (!inherits(travel_matrix, "data.table")) { - original_class <- class(travel_matrix) - data <- data.table::as.data.table(travel_matrix) - } else { - data <- data.table::copy(travel_matrix) - } - if (!inherits(land_use_data, "data.table")) { - land_use_data <- data.table::as.data.table(land_use_data) - } - - # Merge demand and supply - merge_by_reference( +run_standalone_doubly_ipf <- function( data, land_use_data, demand, - left_df_idcol = "from_id", - na_as_zero = TRUE - ) - merge_by_reference( - data, - land_use_data, supply, - left_df_idcol = "to_id", - na_as_zero = TRUE - ) + error_threshold, + improvement_threshold, + max_iterations, + group_label = NULL +) { - # Apply decay - data <- apply_gravity_measure(data, decay_function, travel_cost) + # with group_by or several decay values, messages name the group they refer + # to, so a failing group can be told apart from the others + + in_group <- if (is.null(group_label)) { + character(0) + } else { + c("i" = "In group {group_label}.") + } # Prepare vectors and impedance matrix origins <- unique(data$from_id) destinations <- unique(data$to_id) + O <- land_use_data[[demand]][match(origins, land_use_data$id)] D <- land_use_data[[supply]][match(destinations, land_use_data$id)] - # NA values and ids missing from land_use_data count as 0 demand/supply + # ids missing from land_use_data and NA values are treated as 0. this keeps + # the balancing well-defined and matches merge_by_reference(na_as_zero = TRUE) O[is.na(O)] <- 0 D[is.na(D)] <- 0 - # Validate totals match if (abs(sum(O) - sum(D)) > 1e-6) { cli::cli_abort( - "For doubly-constrained, the sum of origins must equal the sum of - destinations. NA values and ids missing from {.arg land_use_data} count - as 0.", + c( + "For doubly-constrained, the sum of origins must equal the sum of + destinations. NA values and ids missing from {.arg land_use_data} + count as 0.", + in_group + ), call = NULL ) } if (sum(O) <= 0) { cli::cli_abort( - "For doubly-constrained, the total demand and supply must be greater - than 0.", + c( + "For doubly-constrained, the total demand and supply must be greater + than 0.", + in_group + ), call = NULL ) } - # Build impedance matrix - # filled by id, so the result doesn't depend on the row order of - # travel_matrix. pairs missing from travel_matrix are unreachable (weight 0) + # the impedance matrix is filled by matching origin and destination ids, so + # the row order of travel_matrix doesn't matter and each weight goes to the + # right pair. pairs missing from travel_matrix are unreachable (weight 0) impedance_matrix <- matrix( 0, @@ -112,44 +88,85 @@ doubly_constrained <- function(travel_matrix, ncol = length(destinations), dimnames = list(origins, destinations) ) + impedance_matrix[ - cbind(match(data$from_id, origins), match(data$to_id, destinations)) + cbind( + match(data$from_id, origins), + match(data$to_id, destinations) + ) ] <- data$opp_weight - # Iterative proportional fitting Ai <- rep(1, length(O)) Bj <- rep(1, length(D)) + previous_error <- Inf iteration_count <- 0 stop_reason <- "" repeat { + iteration_count <- iteration_count + 1 - # Update Ai - # a null denominator means the zone reaches (or is reached by) no one, so - # its factor is 0 and it gets no flow. the denominators of all zones are - # calculated at once with matrix products + denominator_i <- drop( + impedance_matrix %*% (Bj * D) + ) - denominator_i <- drop(impedance_matrix %*% (Bj * D)) - Ai <- data.table::fifelse(denominator_i > 0, 1 / denominator_i, 0) + # a null denominator means the origin reaches no destination with + # weighted supply, so its factor is 0 (instead of Inf) and it gets no flow - # Update Bj - denominator_j <- drop(crossprod(impedance_matrix, Ai * O)) - Bj_new <- data.table::fifelse(denominator_j > 0, 1 / denominator_j, 0) + Ai <- data.table::fifelse( + denominator_i > 0, + 1 / denominator_i, + 0 + ) + + denominator_j <- drop( + crossprod( + impedance_matrix, + Ai * O + ) + ) - # Compute error - # the row and column sums of the flows (Tij = Ai * O_i * Bj * D_j * f_ij) - # are calculated from the factors, without building the flow matrix + # likewise, a destination that no origin with weighted demand reaches gets + # a factor of 0 + + Bj_new <- data.table::fifelse( + denominator_j > 0, + 1 / denominator_j, + 0 + ) + + # the row and column sums of the flows are calculated from the factors, + # without building the flow matrix + + flow_from <- Ai * O * + drop(impedance_matrix %*% (Bj_new * D)) - flow_from <- Ai * O * drop(impedance_matrix %*% (Bj_new * D)) flow_to <- Bj_new * D * denominator_j - error <- (sum(abs(O - flow_from)) + sum(abs(D - flow_to))) / sum(O) + + error <- ( + sum(abs(O - flow_from)) + + sum(abs(D - flow_to)) + ) / sum(O) + error_change <- abs(previous_error - error) - if (error < error_threshold || error_change < improvement_threshold || iteration_count >= max_iterations) { + if ( + error < error_threshold || + error_change < improvement_threshold || + iteration_count >= max_iterations + ) { + Bj <- Bj_new - stop_reason <- if (iteration_count >= max_iterations) "Max iterations reached" else if (error < error_threshold) "Error threshold met" else "Slow improvement" + + stop_reason <- if (iteration_count >= max_iterations) { + "max iterations reached" + } else if (error < error_threshold) { + "error threshold met" + } else { + "slow improvement" + } + break } @@ -159,23 +176,31 @@ doubly_constrained <- function(travel_matrix, if (error >= error_threshold) { cli::cli_warn( - "Doubly-constrained balancing did not converge ({stop_reason} after - {iteration_count} iterations). Final error is {signif(error, 3)}, above - {.arg error_threshold} ({error_threshold}), so flows don't fully match - the demand and supply totals. Consider increasing - {.arg max_iterations} or decreasing {.arg improvement_threshold}." + c( + "Doubly-constrained balancing did not converge ({stop_reason} after + {iteration_count} iteration{?s}). Final error is {signif(error, 3)}, + above {.arg error_threshold} ({error_threshold}), so flows don't fully + match the demand and supply totals. Consider increasing + {.arg max_iterations} or decreasing {.arg improvement_threshold}.", + in_group + ) ) } - # Compute flows - Tij <- outer(Ai * O, Bj * D) * impedance_matrix + Tij <- outer( + Ai * O, + Bj * D + ) * impedance_matrix + + # kappa_doubly is the allocation weight kappa_ij = A_i * O_i * B_j * f(c_ij), + # so that the flow is T_ij = kappa_ij * D_j - # Compute kappa_doubly -# kappa_ij^D = A_i * B_j * O_i * f(c_ij) - kappa_matrix <- outer(Ai * O, Bj) * impedance_matrix + kappa_matrix <- outer( + Ai * O, + Bj + ) * impedance_matrix - # Prepare output - detailed_dt <- data.table::data.table( + data.table::data.table( from_id = rep(origins, each = length(destinations)), to_id = rep(destinations, times = length(origins)), flow = as.vector(t(Tij)), @@ -185,20 +210,155 @@ doubly_constrained <- function(travel_matrix, error = error ) - if (detailed_results) { - if (exists("original_class")) class(detailed_dt) <- original_class - return(detailed_dt[]) - } else { - cli::cli_warn( - "Aggregated results equal marginals (O_i or D_j). Interpret with - caution." +} + +run_grouped_doubly_ipf <- function( + data, + group_by, + land_use_data, + demand, + supply, + error_threshold, + improvement_threshold, + max_iterations +) { + + if ("decay_function_arg" %in% names(data)) { + group_by <- c(group_by, "decay_function_arg") + } + + if (length(group_by) == 0) { + + return( + run_standalone_doubly_ipf( + data = data, + land_use_data = land_use_data, + demand = demand, + supply = supply, + error_threshold = error_threshold, + improvement_threshold = improvement_threshold, + max_iterations = max_iterations + ) ) - agg <- data.table::rbindlist(list( - data.table::data.table(id = origins, flow = O), - data.table::data.table(id = destinations, flow = D) - )) - if (exists("original_class")) class(agg) <- original_class - return(agg[]) } + # drop = TRUE skips unused factor levels and level combinations that don't + # occur in the data, which would otherwise be empty groups + + grouped_data <- split( + data, + by = group_by, + keep.by = TRUE, + drop = TRUE + ) + + results <- data.table::rbindlist( + lapply(grouped_data, function(dt) { + + group_vals <- dt[1, ..group_by] + group_label <- paste0( + group_by, + " = ", + vapply(group_vals, as.character, character(1)), + collapse = ", " + ) + + out <- run_standalone_doubly_ipf( + data = dt, + land_use_data = land_use_data, + demand = demand, + supply = supply, + error_threshold = error_threshold, + improvement_threshold = improvement_threshold, + max_iterations = max_iterations, + group_label = group_label + ) + + for (g in group_by) { + out[, (g) := group_vals[[g]]] + } + + out + + }), + fill = TRUE + ) + + # group columns go right after the ids, as in the other constraints + + data.table::setcolorder(results, c("from_id", "to_id", group_by)) + + return(results[]) + +} + +doubly_constrained <- function(travel_matrix, + land_use_data, + travel_cost, + decay_function, + demand, + supply, + error_threshold = 0.001, + improvement_threshold = 1e-6, + max_iterations = 1000, + active, + group_by = character(0), + fill_missing_ids = TRUE, + detailed_results = FALSE +) { + # Validate inputs + checkmate::assert_string(demand) + checkmate::assert_string(supply) + checkmate::assert_number(error_threshold, lower = 0) + checkmate::assert_number(improvement_threshold, lower = 0) + checkmate::assert_int(max_iterations, lower = 1) + + # Convert to data.table + if (!inherits(travel_matrix, "data.table")) { + original_class <- class(travel_matrix) + data <- data.table::as.data.table(travel_matrix) + } else { + data <- data.table::copy(travel_matrix) + } + if (!inherits(land_use_data, "data.table")) { + land_use_data <- data.table::as.data.table(land_use_data) + } + + # Merge demand and supply + merge_by_reference( + data, + land_use_data, + demand, + left_df_idcol = "from_id", + na_as_zero = TRUE + ) + merge_by_reference( + data, + land_use_data, + supply, + left_df_idcol = "to_id", + na_as_zero = TRUE + ) + + # Apply decay + data <- apply_gravity_measure(data, decay_function, travel_cost) + + # Run doubly-constrained model + result <- run_grouped_doubly_ipf( + data = data, + group_by = group_by, + land_use_data = land_use_data, + demand = demand, + supply = supply, + error_threshold = error_threshold, + improvement_threshold = improvement_threshold, + max_iterations = max_iterations + ) + + if (exists("original_class")) { + class(result) <- original_class + } + + return(result[]) + } diff --git a/man/constrained_accessibility.Rd b/man/constrained_accessibility.Rd index 1592abe..2e331fa 100644 --- a/man/constrained_accessibility.Rd +++ b/man/constrained_accessibility.Rd @@ -96,7 +96,10 @@ the function identifies which combinations would be left out and fills their respective accessibility values with 0, which incurs a performance penalty.} -\item{detailed_results}{Logical. Whether to return detailed OD-level results.} +\item{detailed_results}{Logical. Whether to return detailed OD-level +results for \code{constraint = "total"}- and \code{constraint = "singly"} +accessibility. Currently ignored for \code{constraint = "doubly"} accessibility, +which always returns OD-level flows.} } \value{ A data frame of the same class as \code{travel_matrix} (\code{data.table}, @@ -117,18 +120,14 @@ the allocated flow (\code{supply} or \code{demand}) and the scaling constant origin-destination pair, with the columns \code{from_id}, \code{to_id}, the allocation share (\code{kappa_singly} or \code{hatkappa_singly}), the allocated flow (\code{supply} or \code{demand}) and the balancing factor (\code{B_j} or \code{A_i}). -\item \code{constraint = "doubly"}, \code{detailed_results = TRUE}: one row per -origin-destination pair, with the columns \code{from_id}, \code{to_id}, \code{flow}, the -balancing factors \code{A_i} and \code{B_j}, \code{kappa_doubly} and the final balancing -\code{error}. -\item \code{constraint = "doubly"}, \code{detailed_results = FALSE}: the columns \code{id} -and \code{flow}, holding the demand of each origin followed by the supply of -each destination (so an id can appear twice). +\item \code{constraint = "doubly"}: one row per origin-destination pair, with the +columns \code{from_id}, \code{to_id}, \code{flow}, the balancing factors \code{A_i} and \code{B_j}, +\code{kappa_doubly} and the final balancing \code{error}. \code{detailed_results} and +\code{active} are not read. } -For \code{constraint = "total"} and \code{"singly"}, detailed results include the -\code{group_by} columns and, when the decay function has several values, -\code{decay_function_arg}. +Detailed results include the \code{group_by} columns and, when the decay +function has several values, \code{decay_function_arg}. } \description{ Calculates accessibility using constraints, as proposed in @@ -150,7 +149,9 @@ opportunities (or population) associated with the ids that appear in that group's rows. As well, when \code{fill_missing_ids = TRUE}, ids that are absent from a particular -group's rows are still returned with accessibility equal to 0. +group's rows are still returned with accessibility equal to 0. This doesn't +apply to \code{constraint = "doubly"}, which ignores \code{fill_missing_ids} and +returns every origin-destination pair of the ids in each group. \subsection{Total Constrained Accessibility}{ Allocates the system-wide total proportionally based on travel impedance @@ -289,12 +290,13 @@ travel impedance. \itemize{ \item Both \code{demand} and \code{supply} must be provided. \item Unlike \code{total} and \code{singly}, \code{doubly} requires the sum of demand and supply -to match; otherwise, the model will not converge. -\item \code{active} must be \code{NULL}. Since supply must match demand, their units are +to match; otherwise, an error is raised. When \code{group_by} or multiple decay +values are used, the totals must match within each independently balanced +system. +\item \code{active} is ignored. Since supply must match demand, their units are the same and there is no distinction between 'active' and 'passive' notions. -\item Should be used with \code{detailed_results = TRUE}. With -\code{detailed_results = FALSE}, it only returns the demand and supply -marginals, with a warning. +\item \code{detailed_results} is currently ignored for doubly-constrained +accessibility. OD-level flows are always returned. } } @@ -368,7 +370,7 @@ constrained_accessibility( ) # Doubly-constrained: returns units of flow (requires both demand and supply -# (totals that match) and `detailed_results = TRUE`) +# with matching totals) # Using a small toy dataset with matching totals. tm_small <- data.table::data.table( @@ -388,8 +390,18 @@ constrained_accessibility( constraint = "doubly", decay_function = decay_exponential(0.1), demand = "population", - supply = "jobs", - detailed_results = TRUE + supply = "jobs" +) + +# With several decay values, each one is balanced separately +constrained_accessibility( + travel_matrix = tm_small, + land_use_data = lu_small, + travel_cost = "travel_time", + constraint = "doubly", + decay_function = decay_exponential(c(0.1, 0.5)), + demand = "population", + supply = "jobs" ) \dontshow{\}) # examplesIf} } diff --git a/man/doubly_constrained.Rd b/man/doubly_constrained.Rd index 1a62da9..3ad7c13 100644 --- a/man/doubly_constrained.Rd +++ b/man/doubly_constrained.Rd @@ -4,8 +4,8 @@ \alias{doubly_constrained} \title{Doubly constrained accessibility} \value{ -A \code{data.table}/\code{data.frame} with either OD-level flows (\code{detailed_results = TRUE}) -or marginals; see Details. +A \code{data.table}/\code{data.frame} with origin-destination flows, balancing +factors (\code{A_i}, \code{B_j}), and doubly-constrained weights (\code{kappa_doubly}). } \description{ Calculates accessibility using Wilson's doubly-constrained gravity model. diff --git a/tests/testthat/test-constrained-essentials.R b/tests/testthat/test-constrained-essentials.R index 208469a..bbaf8d1 100644 --- a/tests/testthat/test-constrained-essentials.R +++ b/tests/testthat/test-constrained-essentials.R @@ -24,7 +24,7 @@ make_lu_match20 <- function() { exp_decay_01 <- decay_exponential(decay_value = 0.1) pow_decay_3 <- decay_power(decay_value = 3) -#------------------------------- TOTAL (6 tests) ------------------------------- +#------------------------------- TOTAL (9 tests) ------------------------------- test_that("total-constrained: preserves totals on supply/demand sides", { tm <- make_tm_3x3() lu <- make_lu_large() @@ -1034,29 +1034,7 @@ test_that("singly-constrained (active) fills missing group combinations", { ) }) -# ------------------------------ DOUBLY ------------------------------- -test_that("doubly-constrained: errors when totals mismatch", { - tm <- make_tm_3x3() - lu_bad <- data.table::copy(make_lu_match20()) - lu_bad[id == "3", jobs := jobs + 1] # break equality - - expect_error( - constrained_accessibility( - constraint = "doubly", - travel_matrix = tm, - land_use_data = lu_bad, - travel_cost = "travel_time", - decay_function = exp_decay_01, - demand = "population", - supply = "jobs", - detailed_results = TRUE, - active = NULL - ), - # cli wraps long messages, so spaces may be line breaks - "sum of origins must equal the sum of[[:space:]]+destinations" - ) -}) - +# ------------------------------ DOUBLY (19 tests)------------------------------- test_that("doubly-constrained: OD flows match marginals", { tm <- make_tm_3x3() @@ -1169,6 +1147,90 @@ test_that("doubly-constrained: results don't depend on row order or sparsity", { expect_identical(result[from_id == "1" & to_id == "3"]$flow, 0) }) +test_that("doubly-constrained: errors when totals mismatch", { + lu_bad <- data.table::copy(make_lu_match20()) + lu_bad[id == "3", jobs := jobs + 1] + + expect_error( + constrained_accessibility( + constraint = "doubly", + travel_matrix = make_tm_3x3(), + land_use_data = lu_bad, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs" + ), + regexp = "sum[[:space:]]+of[[:space:]]+origins[[:space:]]+must" + ) +}) + +test_that("doubly-constrained groups with different ids equal separate runs", { + + # ids 1 and 2 hold 14 people and 14 jobs, so a group that only covers them + # still has matching totals + + lu <- data.table::data.table( + id = c("1", "2", "3"), + population = c(4, 10, 6), + jobs = c(6, 8, 6) + ) + + tm <- make_tm_3x3() + + # "bus" covers only ids 1 and 2 and is twice as slow, "walk" misses 1->2 + + subsets <- list( + car = data.table::copy(tm), + bus = data.table::copy(tm)[ + from_id != "3" & to_id != "3" + ][, travel_time := travel_time * 2], + walk = data.table::copy(tm)[!(from_id == "1" & to_id == "2")] + ) + tm_modes <- data.table::rbindlist(subsets, idcol = "mode") + + run <- function(travel_matrix, ...) { + constrained_accessibility( + constraint = "doubly", + travel_matrix = travel_matrix, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(c(0.1, 0.2)), + demand = "population", + supply = "jobs", + ... + ) + } + + grouped <- run(tm_modes, group_by = "mode") + + for (m in names(subsets)) { + standalone <- run(subsets[[m]]) + merged <- merge( + grouped[mode == m], + standalone, + by = c("from_id", "to_id", "decay_function_arg"), + suffixes = c("", "_standalone") + ) + + expect_equal(nrow(merged), nrow(standalone), info = m) + expect_equal(merged$flow, merged$flow_standalone, info = m) + + # each group is balanced to its own totals: column sums equal the supply + # of the destinations in the group + + col_sums <- grouped[ + mode == m, + .(flow = sum(flow)), + by = .(to_id, decay_function_arg) + ] + col_sums[, jobs := lu$jobs[match(to_id, lu$id)]] + expect_equal(col_sums$flow, col_sums$jobs, info = m) + } + + expect_equal(nrow(grouped[mode == "bus"]), 2 * 2 * 2) +}) + test_that("doubly-constrained: errors when totals don't match", { # the missing id counts as 0, so the totals no longer match. the validators # also warn about the missing id @@ -1357,3 +1419,380 @@ test_that("total-constrained: doesn't add an index to land_use_data", { expect_true(is.null(attr(lu, "index"))) }) + +test_that("doubly-constrained grouped results equal standalone runs", { + + tm <- make_tm_3x3() + lu <- make_lu_match20() + + tm_modes <- data.table::rbindlist( + list(car = tm, bus = tm), + idcol = "mode" + ) + + grouped <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_modes, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + group_by = "mode", + detailed_results = TRUE + ) + + standalone <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + expect_equal( + grouped[mode == "car"]$flow, + standalone$flow + ) + + expect_equal( + grouped[mode == "bus"]$flow, + standalone$flow + ) +}) + +test_that("doubly-constrained multiple decay values equal separate runs", { + + tm <- make_tm_3x3() + lu <- make_lu_match20() + + multi <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(c(0.1, 0.5)), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + run_01 <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(0.1), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + run_05 <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(0.5), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + expect_equal( + multi[decay_function_arg == 0.1]$flow, + run_01$flow + ) + + expect_equal( + multi[decay_function_arg == 0.5]$flow, + run_05$flow + ) +}) + +test_that("doubly-constrained preserves grouping columns", { + + tm <- make_tm_3x3() + lu <- make_lu_match20() + + tm_modes <- data.table::rbindlist( + list(car = tm, bus = tm), + idcol = "mode" + ) + + grouped <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_modes, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + group_by = "mode", + detailed_results = TRUE + ) + + expect_true("mode" %in% names(grouped)) + + multi <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(c(0.1, 0.5)), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + expect_true("decay_function_arg" %in% names(multi)) +}) + + +test_that( + "doubly-constrained handles grouped and multi-decay runs at the same time", + { + + tm <- make_tm_3x3() + lu <- make_lu_match20() + + tm_modes <- data.table::rbindlist( + list( + car = tm, + bus = tm + ), + idcol = "mode" + ) + + result <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_modes, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(c(0.1, 0.5)), + demand = "population", + supply = "jobs", + group_by = "mode", + detailed_results = TRUE + ) + + run_01 <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(0.1), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + run_05 <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = decay_exponential(0.5), + demand = "population", + supply = "jobs", + detailed_results = TRUE + ) + + expect_identical( + sort(unique(result$mode)), + c("bus", "car") + ) + + expect_identical( + sort(unique(result$decay_function_arg)), + c(0.1, 0.5) + ) + + # 2 modes × 2 decay values × 9 OD pairs + + expect_identical( + nrow(result), + 36L + ) + + expect_equal( + result[mode == "car" & decay_function_arg == 0.1]$flow, + run_01$flow + ) + + expect_equal( + result[mode == "bus" & decay_function_arg == 0.1]$flow, + run_01$flow + ) + + expect_equal( + result[mode == "car" & decay_function_arg == 0.5]$flow, + run_05$flow + ) + + expect_equal( + result[mode == "bus" & decay_function_arg == 0.5]$flow, + run_05$flow + ) + } +) + +test_that("doubly-constrained works with factor group_by columns", { + + # unused factor levels ("walk") and level combinations that don't occur + # (car/pm, bus/am) must not become empty groups + + tm <- make_tm_3x3() + lu <- make_lu_match20() + + tm_modes <- data.table::rbindlist( + list( + car = data.table::copy(tm)[, period := "am"], + bus = data.table::copy(tm)[, travel_time := travel_time * 2][, period := "pm"] + ), + idcol = "mode" + ) + tm_modes[, mode := factor(mode, levels = c("bus", "car", "walk"))] + tm_modes[, period := factor(period)] + + run <- function(travel_matrix, ...) { + constrained_accessibility( + constraint = "doubly", + travel_matrix = travel_matrix, + land_use_data = lu, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + ... + ) + } + + grouped <- run(tm_modes, group_by = c("mode", "period")) + + expect_equal(nrow(grouped), 18) + expect_identical( + names(grouped)[1:4], + c("from_id", "to_id", "mode", "period") + ) + expect_true(is.factor(grouped$mode)) + + for (m in c("car", "bus")) { + standalone <- run(tm_modes[mode == m, !c("mode", "period")]) + merged <- merge( + grouped[mode == m], + standalone, + by = c("from_id", "to_id"), + suffixes = c("", "_standalone") + ) + + expect_equal(nrow(merged), 9) + expect_equal(merged$flow, merged$flow_standalone) + } +}) + +test_that("doubly-constrained puts group columns right after the ids", { + tm <- make_tm_3x3() + + tm_modes <- data.table::rbindlist( + list(car = data.table::copy(tm), bus = data.table::copy(tm)), + idcol = "mode" + ) + + result <- constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_modes, + land_use_data = make_lu_match20(), + travel_cost = "travel_time", + decay_function = decay_exponential(c(0.1, 0.5)), + demand = "population", + supply = "jobs", + group_by = "mode" + ) + + expect_identical( + names(result), + c( + "from_id", "to_id", "mode", "decay_function_arg", + "flow", "A_i", "B_j", "kappa_doubly", "error" + ) + ) +}) + +test_that("doubly-constrained warns about land_use_data only once", { + + # NA in both columns of the same id keeps the totals equal (14 = 14) + + lu <- data.table::data.table( + id = c("1", "2", "3"), + population = c(NA, 10, 4), + jobs = c(NA, 6, 8) + ) + + warnings <- character(0) + withCallingHandlers( + constrained_accessibility( + constraint = "doubly", + travel_matrix = make_tm_3x3(), + land_use_data = lu, + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs" + ), + warning = function(w) { + warnings <<- c(warnings, conditionMessage(w)) + invokeRestart("muffleWarning") + } + ) + + expect_equal(sum(grepl("population", warnings)), 1) + expect_equal(sum(grepl("jobs", warnings)), 1) +}) + +test_that("doubly-constrained messages name the group they refer to", { + tm <- make_tm_3x3() + + tm_modes <- data.table::rbindlist( + list(car = data.table::copy(tm), bus = data.table::copy(tm)), + idcol = "mode" + ) + + expect_warning( + constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_modes[mode == "bus"], + land_use_data = make_lu_match20(), + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + group_by = "mode", + max_iterations = 1 + ), + regexp = "mode[[:space:]]+=[[:space:]]+bus" + ) + + # "bus" doesn't reach destination 3, so its totals don't match + tm_uneven <- data.table::rbindlist( + list(car = data.table::copy(tm), bus = data.table::copy(tm)[to_id != "3"]), + idcol = "mode" + ) + + expect_error( + constrained_accessibility( + constraint = "doubly", + travel_matrix = tm_uneven, + land_use_data = make_lu_match20(), + travel_cost = "travel_time", + decay_function = exp_decay_01, + demand = "population", + supply = "jobs", + group_by = "mode" + ), + regexp = "mode[[:space:]]+=[[:space:]]+bus" + ) +}) diff --git a/tests/testthat/test-constrained-wrapper.R b/tests/testthat/test-constrained-wrapper.R index 8be4d6c..0c56f3c 100644 --- a/tests/testthat/test-constrained-wrapper.R +++ b/tests/testthat/test-constrained-wrapper.R @@ -161,8 +161,11 @@ test_that("returns a dataframe whose class is the same as travel_matrix's", { expect_is(result, "data.table") } - result <- suppressWarnings(tester("doubly", travel_matrix = tm_df)) + # doubly always returns OD flows, so detailed_results makes no difference + + result <- tester("doubly", travel_matrix = tm_df) expect_false(inherits(result, "data.table")) + expect_identical(tester("doubly"), tester("doubly", detailed_results = TRUE)) }) test_that("total constraint ignores the side not used by active", {