Aggregate Floating Catchment Area Ratios

Calculate aggregate sums or means, potentially weighted by number of consumers.

catchment_aggregate(from, to = NULL, id = "GEOID", value = "access",
  consumers = "population", to_id = id, to_consumers = consumers,
  map = NULL, original_from = TRUE, return_type = "original",
  verbose = FALSE)

Arguments

from

A matrix-like object with IDs, values, and number of consumers, or a vector of values. These are the lower-level entities to be aggregated up to entries in to.

to

A matrix-like object with IDs and total consumers. These are higher-level entities containing from entities.

id

The column name of IDs in from, or a vector of IDs.

value

The column name of values in from or a vector of values to be aggregated.

consumers

The column name of consumer totals in from, or a vector of said totals of the same length as from IDs.

to_id

The column name of IDs in to, or a vector if IDs.

to_consumers

The column name of consumer totals in to, or a vector of said totals of the same length as to IDs.

map

A named list, with names as or corresponding to to IDs, and vectors containing from IDs as entries.

original_from

Logical indicating whether the from values are original (default). If from values are original and consumers are specified, from values will be multiplied by consumers before aggregation. Set this to FALSE if this has already been done (such as if you set return_type to "region" in catchment_ratio).

return_type

Determines the values that are returned: "original" (default) for an average for each to ID based on the region sum of consumers, or specified to_consumers. If a number, original scores will be multiplied by the number then averaged like "original". If "region", the sum for each to ID is returned.

verbose

Logical; if TRUE, will print a log of the aggregation process.

Value

A vector with an aggregate value (determined by return_type) for each entry in to.

Examples

# lower-level entries prepended with higher-level IDs (like GEOIDs)
higher <- data.frame(id = c(100, 110), pop = c(500, 500))
lower <- data.frame(
  id = paste0(higher$id, 1:5),
  value = 1:5 / 10,
  pop = c(50, 10, 100, 40, 30)
)
catchment_aggregate(
  lower, higher,
  consumers = "pop", id = "id", value = "value",
  to_id = "id", verbose = TRUE
)
#> ── Aggregating Values ──────────────────────────────────────────────────────────
#> ℹ from IDs: `id` column
#> ℹ from values: `value` column
#> ℹ consumers: `pop` column
#> ℹ to IDs: `id` column
#> ℹ to consumers: `pop` column
#> ℹ mapping: by first 3 character match
#> ✔ returning sum of value over total `to` consumers per `to` ID
#>   100   110 
#> 0.100 0.036 

# same thing with IDs specified in a map
catchment_aggregate(
  lower, higher,
  consumers = "pop", id = "id", value = "value",
  map = list("100" = c(1001, 1003, 1005), "110" = c(1102, 1104)), verbose = TRUE
)
#> ── Aggregating Values ──────────────────────────────────────────────────────────
#> ℹ from IDs: `id` column
#> ℹ from values: `value` column
#> ℹ consumers: `pop` column
#> ℹ to IDs: `id` column
#> ℹ to consumers: `pop` column
#> ℹ mapping: by map list
#> ✔ returning sum of value over total `to` consumers per `to` ID
#>   100   110 
#> 0.100 0.036