Compute the model-implied mobility flux from a run configuration

Derives the model's own implied daily mobility flux from a simulation configuration's population sizes and calibrated mobility point estimates. This is the single source of truth for the four mobility figures in the "spatial" group of render_MOSAIC_figures ($\pi_{ij}$ diffusion, $\tau_i$ departure, modeled flux matrix, mobility network).

Usage

calc_mobility_flux(config)

Arguments

config: A simulation configuration list (as read from 1_inputs/config.json or produced by make_simulation_config). Must contain longitude, latitude, N_j_initial, tau_i, location_name, and the scalars mobility_omega, mobility_gamma.

Value

A list with elements, all in config order:

location_name: Character vector of location labels (length J).
coords: A J x 2 numeric matrix of longitude, latitude.
N: Numeric vector of origin populations (length J), named by location.
tau: Numeric vector of daily departure probabilities (length J), named.
omega: Numeric scalar gravity population exponent.
gamma: Numeric scalar gravity distance-decay exponent.
D: J x J Haversine distance matrix (km), config order.
pi: J x J normalized gravity connectivity, diagonal NA.
flux: J x J modeled daily flux $M_{ij}=N_i\tau_i\pi_{ij}$, diagonal NA.

Details

The modeled daily flux is $$M_{ij} = N_i \, \tau_i \, \pi_{ij}$$ the expected number of travelers per day moving from origin $i$ to destination $j$, where $N_i$ is the origin population, $\tau_i$ is the (daily) departure probability, and $\pi_{ij}$ is the normalized gravity connectivity (calc_diffusion_matrix_pi). The diagonal is NA (no self-travel), so rowSums(flux, na.rm = TRUE) equals $N_i\,\tau_i$, the total daily travelers leaving each origin.

This differs from plot_mobility, which visualizes the observed OAG flight matrix used to fit the mobility model. This function returns the model's implied flux from its calibrated parameters, and is therefore run-specific and fully computable from the run's config.json alone (no observed flight data, no disk, no estimation, no API call).

Ordering

All outputs are carried in config order (the order locations appear in the configuration, which is the order the engine consumes them). The location_name element is aligned element-wise to every vector and to both axes of every matrix. This function never sorts.

Examples

if (FALSE) { # \dontrun{
cfg  <- jsonlite::fromJSON(system.file("extdata", "config_default.json",
                                        package = "MOSAIC"), simplifyVector = TRUE)
flux <- calc_mobility_flux(cfg)
# Identity: row sums equal N * tau (daily travelers leaving each origin)
stopifnot(all.equal(rowSums(flux$flux, na.rm = TRUE), flux$N * flux$tau,
                    check.attributes = FALSE))
} # }