From 04bff832afc9814bcf10a26c536119c50212c43b Mon Sep 17 00:00:00 2001 From: soukhova Date: Mon, 26 Oct 2026 20:07:15 -0400 Subject: [PATCH 1/4] second-part fix of issue #66 for doubly-constrained accessibility --- R/constrained_accessibility.R | 34 +- R/doubly_constrained.R | 314 +++++++++++++------ man/constrained_accessibility.Rd | 28 +- man/doubly_constrained.Rd | 4 +- tests/testthat/test-constrained-essentials.R | 242 ++++++++++++-- 5 files changed, 462 insertions(+), 160 deletions(-) diff --git a/R/constrained_accessibility.R b/R/constrained_accessibility.R index 4a6c86b..2961d88 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: @@ -167,11 +170,10 @@ #' - 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. +#' - `active` must be `NULL`. 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 +204,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 +266,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( diff --git a/R/doubly_constrained.R b/R/doubly_constrained.R index b02013c..6bd8a6c 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,134 +22,117 @@ 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 - ) - - # Apply decay - data <- apply_gravity_measure(data, decay_function, travel_cost) + error_threshold, + improvement_threshold, + max_iterations +) { # 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 - 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.", + "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.", call = NULL ) } if (sum(O) <= 0) { cli::cli_abort( - "For doubly-constrained, the total demand and supply must be greater - than 0.", + "For doubly-constrained, the total demand and supply must be greater than 0.", 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) - impedance_matrix <- matrix( 0, nrow = length(origins), 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) + ) + + Ai <- data.table::fifelse( + denominator_i > 0, + 1 / denominator_i, + 0 + ) - denominator_i <- drop(impedance_matrix %*% (Bj * D)) - Ai <- data.table::fifelse(denominator_i > 0, 1 / denominator_i, 0) + denominator_j <- drop( + crossprod( + impedance_matrix, + Ai * O + ) + ) - # Update Bj - denominator_j <- drop(crossprod(impedance_matrix, Ai * O)) - Bj_new <- data.table::fifelse(denominator_j > 0, 1 / denominator_j, 0) + Bj_new <- data.table::fifelse( + denominator_j > 0, + 1 / denominator_j, + 0 + ) - # 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 + 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 +142,23 @@ 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}." + "Doubly-constrained balancing did not converge ({stop_reason} + after {iteration_count} iterations). Final error is + {signif(error, 3)}." ) } - # Compute flows - Tij <- outer(Ai * O, Bj * D) * impedance_matrix + Tij <- outer( + Ai * O, + Bj * D + ) * impedance_matrix - # 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 +168,145 @@ 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[]) } + grouped_data <- split( + data, + by = group_by, + keep.by = TRUE + ) + + results <- data.table::rbindlist( + lapply(grouped_data, function(dt) { + + 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_vals <- dt[1, ..group_by] + + for (g in group_by) { + out[, (g) := group_vals[[g]]] + } + + out + + }), + fill = TRUE + ) + + 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) + + assert_decay_function(decay_function) + assert_group_by(group_by) + assert_travel_matrix(travel_matrix, travel_cost, group_by) + assert_land_use_data(land_use_data, travel_matrix, opportunity = supply, demand = demand) + + # 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..b58ace5 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 @@ -292,9 +291,8 @@ travel impedance. to match; otherwise, the model will not converge. \item \code{active} must be \code{NULL}. 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 +366,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( 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..6909b11 100644 --- a/tests/testthat/test-constrained-essentials.R +++ b/tests/testthat/test-constrained-essentials.R @@ -1035,28 +1035,6 @@ 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" - ) -}) - test_that("doubly-constrained: OD flows match marginals", { tm <- make_tm_3x3() @@ -1357,3 +1335,223 @@ 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 + ) + } +) From 6226899c5d4bca1b0e5891295861ec9925b2a156 Mon Sep 17 00:00:00 2001 From: rafapereirabr Date: Tue, 27 Oct 2026 21:30:30 -0300 Subject: [PATCH 2/4] Fix factor groups, messages and column order in doubly with group_by - Split groups with drop = TRUE, so unused factor levels and level combinations that don't occur no longer become empty groups that abort with "total demand and supply must be greater than 0". - Remove the input checks in doubly_constrained() that repeated the wrapper's, so each data-quality warning prints once. - Restore the full non-convergence warning and name the group (and decay value) in it and in the totals errors. - Put the group columns and decay_function_arg right after from_id/to_id, as for total and singly. - Docs: `active` is ignored; mismatched totals raise an error, checked within each group; the fill_missing_ids note doesn't apply to doubly; drop the ignored detailed_results from the example and add one with several decay values. - Tests for factor group columns, column order, single warnings and the group label in messages. Co-Authored-By: Claude Opus 5.5 --- R/constrained_accessibility.R | 23 ++- R/doubly_constrained.R | 71 ++++++--- man/constrained_accessibility.Rd | 23 ++- tests/testthat/test-constrained-essentials.R | 157 +++++++++++++++++++ 4 files changed, 245 insertions(+), 29 deletions(-) diff --git a/R/constrained_accessibility.R b/R/constrained_accessibility.R index 2961d88..c37f1ea 100644 --- a/R/constrained_accessibility.R +++ b/R/constrained_accessibility.R @@ -48,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 #' @@ -169,8 +171,9 @@ #' ### 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 +#' to match; otherwise, an error is raised. With `group_by`, the totals must +#' match within each group. +#' - `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. @@ -286,8 +289,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 6bd8a6c..0fd2d1e 100644 --- a/R/doubly_constrained.R +++ b/R/doubly_constrained.R @@ -29,9 +29,19 @@ run_standalone_doubly_ipf <- function( supply, error_threshold, improvement_threshold, - max_iterations + max_iterations, + group_label = NULL ) { + # 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) @@ -44,15 +54,23 @@ run_standalone_doubly_ipf <- function( 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 ) } @@ -126,11 +144,11 @@ run_standalone_doubly_ipf <- function( Bj <- Bj_new stop_reason <- if (iteration_count >= max_iterations) { - "Max iterations reached" + "max iterations reached" } else if (error < error_threshold) { - "Error threshold met" + "error threshold met" } else { - "Slow improvement" + "slow improvement" } break @@ -142,9 +160,14 @@ run_standalone_doubly_ipf <- function( 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)}." + 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 + ) ) } @@ -200,15 +223,27 @@ run_grouped_doubly_ipf <- function( ) } + # 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 + 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, @@ -216,11 +251,10 @@ run_grouped_doubly_ipf <- function( supply = supply, error_threshold = error_threshold, improvement_threshold = improvement_threshold, - max_iterations = max_iterations + max_iterations = max_iterations, + group_label = group_label ) - group_vals <- dt[1, ..group_by] - for (g in group_by) { out[, (g) := group_vals[[g]]] } @@ -231,6 +265,10 @@ run_grouped_doubly_ipf <- function( 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[]) } @@ -256,11 +294,6 @@ doubly_constrained <- function(travel_matrix, checkmate::assert_number(improvement_threshold, lower = 0) checkmate::assert_int(max_iterations, lower = 1) - assert_decay_function(decay_function) - assert_group_by(group_by) - assert_travel_matrix(travel_matrix, travel_cost, group_by) - assert_land_use_data(land_use_data, travel_matrix, opportunity = supply, demand = demand) - # Convert to data.table if (!inherits(travel_matrix, "data.table")) { original_class <- class(travel_matrix) diff --git a/man/constrained_accessibility.Rd b/man/constrained_accessibility.Rd index b58ace5..aa2877b 100644 --- a/man/constrained_accessibility.Rd +++ b/man/constrained_accessibility.Rd @@ -149,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 @@ -288,8 +290,9 @@ 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. With \code{group_by}, the totals must +match within each group. +\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 \code{detailed_results} is currently ignored for doubly-constrained accessibility. OD-level flows are always returned. @@ -386,8 +389,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/tests/testthat/test-constrained-essentials.R b/tests/testthat/test-constrained-essentials.R index 6909b11..49f19b1 100644 --- a/tests/testthat/test-constrained-essentials.R +++ b/tests/testthat/test-constrained-essentials.R @@ -1555,3 +1555,160 @@ test_that( ) } ) + +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" + ) +}) From 4e423741ee9033949d7b4871304bdced365a67ea Mon Sep 17 00:00:00 2001 From: soukhova Date: Wed, 28 Oct 2026 12:41:26 -0400 Subject: [PATCH 3/4] added comments to doubly_constrained.R, and updated the BREAKING news, light touch to testthat file and related doc. --- NEWS.md | 13 +++++++++---- R/constrained_accessibility.R | 5 +++-- R/doubly_constrained.R | 11 ++++++++--- man/constrained_accessibility.Rd | 5 +++-- tests/testthat/test-constrained-essentials.R | 4 ++-- 5 files changed, 25 insertions(+), 13 deletions(-) diff --git a/NEWS.md b/NEWS.md index 49fc0d6..db3782a 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 marginals instead of OD flows + -- deemed redundant. ## 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` + - `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 and both blended - several decay values into one result. Detailed results now keep the - `group_by` and `decay_function_arg` columns (#66, @soukhova). + these functions split the regional or marginal 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). + - `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 c37f1ea..2846de3 100644 --- a/R/constrained_accessibility.R +++ b/R/constrained_accessibility.R @@ -171,8 +171,9 @@ #' ### Requirements: #' - Both `demand` and `supply` must be provided. #' - Unlike `total` and `singly`, `doubly` requires the sum of demand and supply -#' to match; otherwise, an error is raised. With `group_by`, the totals must -#' match within each group. +#' 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 diff --git a/R/doubly_constrained.R b/R/doubly_constrained.R index 0fd2d1e..e28398a 100644 --- a/R/doubly_constrained.R +++ b/R/doubly_constrained.R @@ -35,7 +35,6 @@ run_standalone_doubly_ipf <- function( # 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 { @@ -49,6 +48,7 @@ run_standalone_doubly_ipf <- function( O <- land_use_data[[demand]][match(origins, land_use_data$id)] D <- land_use_data[[supply]][match(destinations, land_use_data$id)] + # IDs missing from land_use_data and NA values are treated as 0. This keeps the balancing procedure well-defined and matches the behaviour of merge_by_reference(..., na_as_zero = TRUE). O[is.na(O)] <- 0 D[is.na(D)] <- 0 @@ -75,6 +75,7 @@ run_standalone_doubly_ipf <- function( ) } + # Build the impedance matrix by matching origin and destination IDs. Using explicit ID matching makes the ordering of travel_matrix rows irrelevant and guarantees that impedance values are assigned to the correct origin-destination pair. impedance_matrix <- matrix( 0, nrow = length(origins), @@ -104,6 +105,7 @@ run_standalone_doubly_ipf <- function( impedance_matrix %*% (Bj * D) ) + # If an origin has a denominator of 0, its balancing factor is set to 0 rather than Inf. This can occur when no reachable destinations have positive impedance-weighted supply. Ai <- data.table::fifelse( denominator_i > 0, 1 / denominator_i, @@ -117,15 +119,17 @@ run_standalone_doubly_ipf <- function( ) ) + # If a destination has a denominator of 0, its balancing factor is set to 0 rather than Inf. Bj_new <- data.table::fifelse( denominator_j > 0, 1 / denominator_j, 0 ) + # row sums implied by the balancing factors (predicted demand allocated from each origin) flow_from <- Ai * O * drop(impedance_matrix %*% (Bj_new * D)) - + # column sums implied by the balancing factors (predicted supply allocated to each destination) flow_to <- Bj_new * D * denominator_j error <- ( @@ -175,7 +179,8 @@ run_standalone_doubly_ipf <- function( Ai * O, Bj * D ) * impedance_matrix - + # kappa_doubly represents the doubly-constrained allocation weight: kappa_ij = A_i * O_i * B_j * f(c_ij). + # Flow is then: T_ij = kappa_ij * D_j kappa_matrix <- outer( Ai * O, Bj diff --git a/man/constrained_accessibility.Rd b/man/constrained_accessibility.Rd index aa2877b..2e331fa 100644 --- a/man/constrained_accessibility.Rd +++ b/man/constrained_accessibility.Rd @@ -290,8 +290,9 @@ 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, an error is raised. With \code{group_by}, the totals must -match within each group. +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 \code{detailed_results} is currently ignored for doubly-constrained diff --git a/tests/testthat/test-constrained-essentials.R b/tests/testthat/test-constrained-essentials.R index 49f19b1..2116aae 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,7 +1034,7 @@ test_that("singly-constrained (active) fills missing group combinations", { ) }) -# ------------------------------ DOUBLY ------------------------------- +# ------------------------------ DOUBLY (17 tests)------------------------------- test_that("doubly-constrained: OD flows match marginals", { tm <- make_tm_3x3() From 5493b9a5d2e3a1bef36fb207acddb0087477b67c Mon Sep 17 00:00:00 2001 From: rafapereirabr Date: Wed, 28 Oct 2026 23:05:52 -0300 Subject: [PATCH 4/4] Tidy doubly comments and NEWS, test groups with different ids - Rewrap the explanatory comments in doubly_constrained.R to 80 columns, in the file's style. - NEWS: fix the formatting and wording of the #66 bullet (what each constraint did before) and credit #67 in the breaking change. - Restore the test where demand and supply totals differ, and test that grouped results equal separate runs when groups have different ids and travel times, with each group balanced to its own totals. - test-constrained-wrapper.R: drop the suppressWarnings() left from the old marginals warning and check that doubly ignores detailed_results. Co-Authored-By: Claude Opus 5.5 --- NEWS.md | 16 ++-- R/doubly_constrained.R | 30 +++++-- tests/testthat/test-constrained-essentials.R | 86 +++++++++++++++++++- tests/testthat/test-constrained-wrapper.R | 5 +- 4 files changed, 119 insertions(+), 18 deletions(-) diff --git a/NEWS.md b/NEWS.md index db3782a..047afae 100644 --- a/NEWS.md +++ b/NEWS.md @@ -22,8 +22,8 @@ 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 marginals instead of OD flows - -- deemed redundant. + Previously, `detailed_results = FALSE` returned the demand and supply + marginals instead (#67). ## Bug fixes @@ -48,12 +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"`,`"singly"`, and `doubly` now treat each `group_by` - combination and each decay value as an independent system. Previously, - these functions split the regional or marginal 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/doubly_constrained.R b/R/doubly_constrained.R index e28398a..b776fd3 100644 --- a/R/doubly_constrained.R +++ b/R/doubly_constrained.R @@ -35,6 +35,7 @@ run_standalone_doubly_ipf <- function( # 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 { @@ -48,7 +49,9 @@ run_standalone_doubly_ipf <- function( O <- land_use_data[[demand]][match(origins, land_use_data$id)] D <- land_use_data[[supply]][match(destinations, land_use_data$id)] - # IDs missing from land_use_data and NA values are treated as 0. This keeps the balancing procedure well-defined and matches the behaviour of merge_by_reference(..., na_as_zero = TRUE). + # 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 @@ -75,7 +78,10 @@ run_standalone_doubly_ipf <- function( ) } - # Build the impedance matrix by matching origin and destination IDs. Using explicit ID matching makes the ordering of travel_matrix rows irrelevant and guarantees that impedance values are assigned to the correct origin-destination pair. + # 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, nrow = length(origins), @@ -105,7 +111,9 @@ run_standalone_doubly_ipf <- function( impedance_matrix %*% (Bj * D) ) - # If an origin has a denominator of 0, its balancing factor is set to 0 rather than Inf. This can occur when no reachable destinations have positive impedance-weighted supply. + # 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 + Ai <- data.table::fifelse( denominator_i > 0, 1 / denominator_i, @@ -119,17 +127,21 @@ run_standalone_doubly_ipf <- function( ) ) - # If a destination has a denominator of 0, its balancing factor is set to 0 rather than Inf. + # 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 ) - # row sums implied by the balancing factors (predicted demand allocated from each origin) + # 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)) - # column sums implied by the balancing factors (predicted supply allocated to each destination) + flow_to <- Bj_new * D * denominator_j error <- ( @@ -179,8 +191,10 @@ run_standalone_doubly_ipf <- function( Ai * O, Bj * D ) * impedance_matrix - # kappa_doubly represents the doubly-constrained allocation weight: kappa_ij = A_i * O_i * B_j * f(c_ij). - # Flow is then: T_ij = kappa_ij * D_j + + # 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 + kappa_matrix <- outer( Ai * O, Bj diff --git a/tests/testthat/test-constrained-essentials.R b/tests/testthat/test-constrained-essentials.R index 2116aae..bbaf8d1 100644 --- a/tests/testthat/test-constrained-essentials.R +++ b/tests/testthat/test-constrained-essentials.R @@ -1034,7 +1034,7 @@ test_that("singly-constrained (active) fills missing group combinations", { ) }) -# ------------------------------ DOUBLY (17 tests)------------------------------- +# ------------------------------ DOUBLY (19 tests)------------------------------- test_that("doubly-constrained: OD flows match marginals", { tm <- make_tm_3x3() @@ -1147,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 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", {