Load empirical travel-to-work example data

Loads the LAD travel-to-work example inputs used by package examples and vignettes. By default, the mobile-phone-derived OD data are read from the optional companion package debiasRdata (https://github.com/de-bias/debiasRdata) as lad_OD_travel2work. The benchmark OD data are the matching Census 2021 workplace-flow extract census_lad_OD_travel2work, also supplied by debiasRdata.

Usage

debiasR_example_data(
  n_areas = 25,
  data_package = "debiasRdata",
  mpd_path = NULL,
  census_path = NULL,
  include_self_flows = TRUE,
  complete_grid = FALSE,
  fill_missing_flow = 0,
  geography = c("lad", "msoa")
)

Arguments

n_areas

Number of high-flow overlapping areas to keep for examples. Use Inf or NULL to keep all overlapping areas.

data_package

Data package containing the empirical files. Default "debiasRdata".

mpd_path

Optional explicit path to the observed MPD OD CSV or .csv.gz.

census_path

Optional explicit path to the extracted Census 2021 travel-to-work OD CSV or .csv.gz.

include_self_flows

Logical; keep within-area flows. Default TRUE.

complete_grid

Logical; if TRUE, return MPD and benchmark OD tables on the same square area grid after area selection. Missing OD pairs are retained with zero-filled flows and row-status indicators. Default FALSE preserves the observed positive-flow support.

fill_missing_flow

Numeric value used for absent OD pairs when complete_grid = TRUE. Default 0.

geography

Area level to load from debiasRdata. The default "lad" uses lad_OD_travel2work, census_lad_OD_travel2work, optional lad_covariates, and optional lad_centroids. Use "msoa" only when MSOA-level examples are explicitly required.

Value

A named list with normalised OD matrices and derived teaching tables: lad_OD_travel2work and mpd_od for observed MPD flows, census_lad_OD_travel2work and benchmark_od for the Census benchmark, plus coverage, active_users, population, covariates, distance, od_audit, and metadata.

Details

Both sources are normalised to the package schema: origin, destination, and flow. The returned coverage table is derived from matched origin totals: Census workplace outflow is used as the benchmark population-like denominator and MPD travel-to-work outflow is used as the active-user numerator for the empirical examples. If debiasRdata supplies area-level covariates, the returned covariates table uses the selected rows from lad_covariates or msoa_covariates. If no matching covariate object is available, the package falls back to the derived covariates used in earlier examples. If debiasRdata supplies LAD centroids, the optional distance table is computed for the selected example areas from those real centroids rather than from a synthetic placeholder.

Examples

ex <- debiasR_example_data(n_areas = 12)
names(ex)
#>  [1] "mpd_od"                    "benchmark_od"             
#>  [3] "coverage"                  "active_users"             
#>  [5] "population"                "covariates"               
#>  [7] "distance"                  "od_audit"                 
#>  [9] "metadata"                  "lad_OD_travel2work"       
#> [11] "census_lad_OD_travel2work"
head(ex$lad_OD_travel2work)
#> # A tibble: 6 × 4
#>   origin    destination mpd_source                    flow
#>   <chr>     <chr>       <chr>                        <dbl>
#> 1 E06000023 E06000023   locomizer_travel_to_work_lad  2227
#> 2 E06000023 E06000052   locomizer_travel_to_work_lad    28
#> 3 E06000023 E06000054   locomizer_travel_to_work_lad    26
#> 4 E06000023 E06000060   locomizer_travel_to_work_lad     5
#> 5 E06000023 E06000062   locomizer_travel_to_work_lad     1
#> 6 E06000023 E08000003   locomizer_travel_to_work_lad     2
head(ex$census_lad_OD_travel2work)
#> # A tibble: 6 × 3
#>   origin    destination  flow
#>   <chr>     <chr>       <dbl>
#> 1 E06000023 E06000023   83959
#> 2 E06000023 E06000047       3
#> 3 E06000023 E06000052      52
#> 4 E06000023 E06000054     976
#> 5 E06000023 E06000060      26
#> 6 E06000023 E06000062      15