Add route-decomposed Cori R_eff to an existing MOSAIC model output directory

Post-hoc driver that applies the route-decomposed Cori (2013) effective reproductive number reduction (calc_Reff: \(R_{eff} = R_{hum} + R_{env}\)) to a single MOSAIC model output directory laid out by run_MOSAIC. It loads the captured ensemble trajectories (2_calibration/trajectories_ensemble.rds) and the medoid config (2_calibration/best_model/config_medoid.json, falling back to 1_inputs/config.json with a warning), computes the per-location R_eff series, writes the tidy reproductive_numbers table to 3_results/posterior/reproductive_numbers.csv (and .rds), and optionally renders plot_Reff to 3_results/figures/reproductive_number/.

Usage

add_reproductive_numbers(
  output_dir,
  recompute_ci = FALSE,
  burn_in_days = NULL,
  infectiousness_floor = 1,
  plots = TRUE,
  overwrite = TRUE,
  verbose = TRUE,
  n_cores = 1L
)

Arguments

output_dir

Character. Path to ONE MOSAIC model output directory (the directory that contains 1_inputs/, 2_calibration/, and 3_results/). No path is hardcoded; all I/O is relative to this.

recompute_ci

Logical. When TRUE, build a proper posterior credible interval by re-simulating the run's posterior members and computing R_eff per member: central is the medoid trajectory's R_t and q2.5/q50/q97.5 are per-calendar-day cross-member weighted quantiles. Members are re-simulated from 2_calibration/ensemble_candidate.rds (whose seeds reproduce them) and weighted, and the medoid chosen, by the run's FINAL posterior (2_calibration/ensemble_optimized.rds, mapped onto the candidate by seed; the optimized subset when optimize_subset = TRUE). Requires a run with control$io$persist_ensemble_arrays = TRUE; does not need the trajectory artifact. This captures the daily route incidence, stock and decay-rate channels that the persisted trajectory artifact does not retain at a daily grid. A faithfulness gate confirms the re-sim reproduces the saved engine-level cases (cases_engine_array) before any CI is written. When FALSE (default) the cheap point-estimate path is used (renewal on the weighted-median route incidence from trajectories_ensemble.rds; CI columns are populated only if the artifact carries daily-consecutive per-member lines, otherwise NA).

burn_in_days

Integer or NULL. Number of leading days to exclude from the R_eff output (set to NA in the table). NULL (default) reads control$likelihood$burn_in_days from 1_inputs/control.json; if that is 0 or absent it defaults to 30 days. An explicit 0 disables the burn-in. Applied on both paths: early R reflects the reservoir filling from empty rather than the epidemic.

infectiousness_floor

Numeric scalar \(\ge 0\). Passed to calc_Reff; minimum generation-weighted past infectiousness required to report \(R_t\) (guards the initial-condition seed spike and deep inter-epidemic troughs). Default 1.

plots

Logical. Render and save plot_Reff (PNG + PDF) to 3_results/figures/reproductive_number/. Default TRUE.

overwrite

Logical. If FALSE and a route-decomposed output CSV already exists, skip recomputation and return a "skipped_exists" status (an older total-only CSV is always recomputed). Default TRUE.

verbose

Logical. Emit progress messages. Default TRUE.

n_cores

Integer. Workers used for the recompute_ci = TRUE re-simulation, which is the only expensive part of this function (~1,000 engine runs at run_MOSAIC() defaults). Greater than 1 builds a PSOCK cluster and stops it before returning; 1L (default) keeps the historical serial behaviour. Ignored when recompute_ci = FALSE.

Value

Invisibly, a one-row data.frame status with columns:

dir

The output_dir.

status

One of "ok", "skipped_exists", "skipped_missing_trajectories", "skipped_missing_config", "skipped_no_incidence" (no route incidence channels), or "error".

n_locations

Number of locations in the artifact (NA if not loaded).

ci_available

Logical; whether the posterior CI columns are populated (FALSE on production-default strided artifacts).

csv

Path to the written CSV (NA when not written).

rds

Path to the written RDS (NA when not written).

plot

Path to the written PNG (NA when not written).

message

Human-readable detail.

Details

Robust by design. Missing files, a trajectory artifact without the incidence_human/incidence_env channels, or a calc_Reff() error are handled by skipping with an informative message/warning and returning a status row; the function does not crash. It is therefore safe to map over the full per-ISO model tree.

See also

calc_Reff, plot_Reff.

Examples

if (FALSE) { # \dontrun{
# Single model directory
add_reproductive_numbers("/path/to/output/national/MOZ")

# Map over a per-ISO tree
dirs <- list.dirs("/path/to/output/national", recursive = FALSE)
status <- do.call(rbind, lapply(dirs, add_reproductive_numbers))
} # }