Skip to content
Merged

Dev #73

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
56 changes: 34 additions & 22 deletions R/constrained_accessibility.R
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
#'
Expand Down Expand Up @@ -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`,
Expand Down Expand Up @@ -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{}
Expand Down Expand Up @@ -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(
Expand All @@ -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
Expand Down
Loading
Loading