Package 'dynasimR'

Description

Quantifies the trade-off between event-rate reduction and the Compliance Index across autonomy levels AL0-AL5. Returns the trade-off table, the optimal AL level (highest event reduction still above the compliance threshold) and observed compliance violations. Missing compliance is unknown, cannot qualify an optimum, and is not labelled an observed violation. al_ratio is a descriptive ratio event_reduction_pct / (1 - compliance + 0.001) with a fixed stabilizer; it is not a validated utility or a criterion used to choose the optimum. event_ci_lo and event_ci_hi describe absolute event rates. event_reduction_ci_lo and event_reduction_ci_hi are percentile intervals for the reference-minus-scenario median difference in percentage points, assuming independent replications between scenarios. The reference compared with itself has zero difference and, when an interval is requested with at least two observed rates, bounds of zero.

Usage

al_efficiency(
  data,
  al_scenarios = c(`0` = "A-S00", `1` = "A-S05", `2` = "A-S09", `3` = "A-S10", `4` =
    "A-S11", `5` = "A-S12"),
  compliance_threshold = 0.8,
  reference_al = 0,
  n_bootstrap = 1000
)

Arguments

Value

An S3 object of class dynasimR_al_analysis with slots tradeoff_table, optimal_al, compliance_violations and params.

Examples

## Not run: 
sim <- load_example_data()
al  <- al_efficiency(sim)
plot_al_tradeoff(al)

## End(Not run)

Description

Inspects the ⁠Suggests:⁠ packages required by the embedded Shiny dashboard, including table export, and prints which ones are installed. This function reports an installation command; it does not install packages.

Usage

check_app_dependencies()

Value

A tibble with columns package, installed, version, invisibly.

Description

Fits a multinomial logistic regression of completion outcome (categorical) on scenario + covariates. Returns the model, tidied coefficients, and class-level proportions.

Usage

compute_completion_analysis(data, covariates = c("scenario", "severity"))

Arguments

Value

An S3 object of class dynasimR_completion with slots fit, tidy, proportions, params. Coefficient rows name the actual non-reference outcome classes; params$reference_outcome is the first factor level and params$n_obs is the analyzed sample size. When the optional package nnet is unavailable, only proportions are returned with a warning.

Description

Fraction of entities (irrespective of group) that receive service within a defined time window. A value below 0.80 is treated as a critical compliance violation.

Usage

compute_compliance_index(
  entities,
  window_min = 60,
  window_unit = c("min", "hours", "days"),
  by_scenario = TRUE,
  by_group = TRUE,
  n_bootstrap = 1000
)

Arguments

Details

When received_service is supplied, only a confirmed service (1) counts in the numerator. Missing times or service indicators are not confirmed timely service and remain in the denominator. Without an indicator, a nonmissing time is assumed to represent received service. For Profile B wait times, see compute_wait_gap_index(). Bootstrap intervals treat entities as independent observations.

Value

A tibble with columns scenario (if stratified), group (if stratified), ci, ci_ci_lo, ci_ci_hi, n_total, n_in_window, compliance_critical, window_min.

Examples

## Not run: 
sim <- load_example_data()
ci  <- compute_compliance_index(sim)

## End(Not run)

Description

Analogue of the Compliance Index for entity-flow profiles: fraction of entities whose wait time from arrival to activation does not exceed a threshold number of days (default 14). A value below 0.80 is flagged as a critical wait-gap. Missing wait times remain in the denominator and do not count as timely activation; negative or infinite waits are rejected. Supply observed activation waits only: encode unactivated entities with NA, not a censoring time. This index does not estimate a censoring-adjusted probability.

Usage

compute_wait_gap_index(
  data,
  window_days = 14,
  by_scenario = TRUE,
  by_cohort = TRUE,
  n_bootstrap = 1000
)

Arguments

Value

A tibble with columns scenario (if stratified), cohort (if stratified), wgi, wgi_ci_lo, wgi_ci_hi, n_total, n_in_window, wgi_critical, window_days.

Description

Cox proportional-hazards model for simulation data

Usage

cox_model(
  data,
  endpoint = c("stage2", "overall", "service"),
  covariates = c("scenario", "severity", "group"),
  reference_scenario = "A-S00"
)

Arguments

Value

An S3 object of class dynasimR_cox with slots fit, tidy, ph_test, forest_data and params.

Description

Identifies scenario-stage combinations where the median recorded time exceeds a percentile threshold relative to the grand distribution. This descriptive ranking does not establish a capacity bottleneck, especially when input times are cumulative or censored.

Usage

detect_bottlenecks(data, threshold = 0.75)

Arguments

Value

A tibble with only the bottleneck rows.

Description

Returns a named list of hex colours used by all ⁠plot_*⁠ functions.

Usage

dynasimR_colors()

Value

A named list with entries GROUP_A, GROUP_B, GROUP_C, POSITIVE, NEGATIVE, NEUTRAL, ACCENT, BG.

Examples

pal <- dynasimR_colors()
pal$GROUP_A

Description

Writes a ggplot2 object to PDF/SVG/PNG/TIFF/EPS at the specified physical dimensions (in millimetres) and resolution.

Usage

export_figure(
  plot,
  filename,
  width_mm = 174,
  height_mm = 120,
  dpi = 300,
  format = NULL
)

Arguments

Details

SVG uses R's Cairo graphics device. Its runtime libraries must be available; macOS builds of R linked to X11, including CRAN binaries, may require XQuartz. Install it and restart R if SVG reports missing X11/Cairo libraries. Exports are staged and checked for nonempty output before an existing file is replaced. Device errors and warnings remain visible.

Value

Invisibly, the filename.

Examples

## Not run: 
p <- ggplot2::ggplot(mtcars, ggplot2::aes(mpg, hp)) +
  ggplot2::geom_point()
export_figure(p, "mtcars.pdf", width_mm = 120, height_mm = 90)

## End(Not run)

Description

Produces a booktabs-style table using ⁠\\botrule⁠ instead of ⁠\\bottomrule⁠. Cells, column names, captions and notes are treated as literal text and escaped once. Notes use a threeparttable environment. The document needs booktabs and, for notes, threeparttable; outside a publisher class defining ⁠\\botrule⁠, add ⁠\\providecommand{\\botrule}{\\bottomrule}⁠ to the preamble.

Usage

export_latex_table(
  data,
  filename,
  caption,
  label,
  note = NULL,
  digits = 3,
  col_format = NULL
)

Arguments

Value

The LaTeX source, invisibly.

Examples

## Not run: 
export_latex_table(head(iris), "iris.tex",
                   caption = "First rows of iris.",
                   label   = "iris")

## End(Not run)

Description

Substitutes ⁠[XX_*]⁠ placeholders in a LaTeX source file with automatically computed simulation statistics. The mapping from placeholder to computation is assembled inside this function from policy_effect(), al_efficiency() and compute_compliance_index().

Usage

fill_placeholders(
  sim_data,
  tex_file,
  output_file = NULL,
  dry_run = FALSE,
  policy_a_scenario = "A-S08",
  policy_b_scenario = "A-S07",
  baseline_scenario = "A-S00",
  overwrite = FALSE
)

Arguments

Details

Policy event differences and their confidence limits use the signed A-minus-B convention, in percentage points. A write is refused if the manuscript requests unknown placeholders or unavailable/non-finite statistics. dry_run = TRUE reports these without writing a file.

Value

Named character vector of the replacements (invisibly).

Description

Compares two Profile B scenarios that differ only in inclusion rules for which groups are prioritised, and returns completion rates, the supplied cost metric and their differences (A minus B) with bootstrap CIs. Cost is summarized as supplied, not divided by completion rates. Replications are assumed independent and unpaired. Missing values are omitted; each scenario needs at least one observed completion rate. Intervals are unavailable with fewer than two observations per group.

Usage

group_effect(
  data,
  group_a_scenario,
  group_b_scenario,
  outcome_col = "completion_rate",
  cost_col = "cost",
  alpha = 0.05,
  n_bootstrap = 1000
)

Arguments

Value

An S3 object of class dynasimR_group_effect with slots completion, cost, delta_completion, delta_cost, params.

Description

Estimates survival functions from simulated entity outcomes. Supports several endpoints for both output profiles.

Usage

km_estimate(
  data,
  scenarios = NULL,
  endpoint = c("stage2", "overall", "service", "regression", "completion", "phase_c"),
  stratify_by = "scenario",
  ci_method = "log",
  n_bootstrap = 0,
  seed = 42
)

Arguments

Value

An S3 object of class dynasimR_km (list) with slots fit, tidy, logrank, median_survival, boot_ci and params. boot_ci contains strata, time, estimate, conf.low, conf.high and successful replicate count n_boot, evaluated at time zero and the original observed times of each stratum. Bands are unavailable for a stratum with fewer than two entities. tidy retains the analytic intervals selected by ci_method.

Examples

## Not run: 
sim <- load_example_data()
km <- km_estimate(sim, endpoint = "stage2",
                  stratify_by = "scenario")
print(km)
plot_km(km)

## End(Not run)

Description

Starts the interactive analysis app bundled with dynasimR. The app requires simulation data; either supply a directory via data_dir or leave it NULL to use the bundled example data. Profile B supports progress/completion overview, comparison and summary table export. Other dashboard analyses require Profile A. Mixed-profile directories must be separated for dashboard use; the R loading API can still read them together.

Usage

launch_app(data_dir = NULL, port = 3838, launch.browser = TRUE, ...)

Arguments

Value

Does not return (blocks until the app is closed).

Examples

## Not run: 
launch_app()
launch_app(data_dir = "~/my-simulation/data/raw/")

## End(Not run)

Description

Convenience wrapper around read_simulation() pointing at the CSVs shipped in ⁠inst/extdata/⁠.

Usage

load_example_data()

Value

A dynasimR_data object.

Examples

sim <- load_example_data()
print(sim)

Description

Fits a separate linear association between each input and the outcome, after standardizing paired complete observations. Despite its legacy name, this function does not implement Morris elementary effects or a variance decomposition. It can miss nonlinear effects and cannot separate correlated inputs or establish causality. For a Morris design use sensitivity::morris() on an appropriate simulation design.

Usage

morris_screening(data, outcome = "event_rate", inputs)

Arguments

Value

A tibble with input, legacy mu_star (absolute standardized slope, equal to absolute Pearson correlation), legacy sigma (standardized regression residual SD), r2, n_observed, status and rank. Missing pairs are omitted independently for each input.

Description

Autonomy-level trade-off plot: event reduction vs. compliance

Usage

plot_al_tradeoff(al_result, label_points = TRUE, highlight_optimal = TRUE)

Arguments

Value

A ggplot2 object.

Description

Compares scenario medians with fixed reference medians. The optional threshold curve reports the observed fraction of scenario runs with positive incremental net benefit relative to those fixed medians. It does not propagate reference uncertainty, pair runs across scenarios, or estimate a cost-effectiveness acceptability probability. Higher outcome values are treated as better. Cost and willingness-to-pay units must be consistent with the outcome unit.

Usage

plot_cost_effectiveness(
  data,
  reference,
  scenarios,
  outcome_col = "completion_rate",
  cost_col = "cost",
  wtp = seq(0, 2e+05, length.out = 40),
  show_ceac = FALSE
)

Arguments

Value

A ggplot2 object. Plane data include delta_effect, delta_cost, icer (their ratio, NA when the effect difference is zero), and n_observed. Curve data retain the legacy prob_ce column name for the observed fraction with strictly positive net benefit; ties do not count as positive. These fractions are not uncertainty probabilities.

Description

Forest plot of Cox hazard ratios

Usage

plot_forest(cox_result, reference_label = "No effect (HR = 1)", ...)

Arguments

Value

A ggplot2 object.

Description

Plots a dynasimR_km object.

Usage

plot_km(
  km_result,
  show_ci = TRUE,
  show_risktable = FALSE,
  show_pval = TRUE,
  show_median = TRUE,
  color_by = "scenario",
  title = NULL,
  subtitle = NULL,
  xlab = "Time",
  ylab = "Survival probability",
  xlim = NULL,
  manuscript_width = 174,
  ...
)

Arguments

Value

A ggplot2 object, or a patchwork composition when show_risktable = TRUE.

Description

Scatter plot of entity positions (requires x and y columns in the entity table) coloured by group or status.

Usage

plot_map(data, color_by = c("group", "status"), scenarios = NULL)

Arguments

Value

A ggplot2 object.

Description

Plots the delta_event table from a dynasimR_policy object as a horizontal bar chart with bootstrap CI whiskers.

Usage

plot_policy(policy_result)

Arguments

Value

A ggplot2 object.

Description

Plots longitudinal progress-score trajectories from the output of progress_trajectory() (with longitudinal = TRUE).

Usage

plot_progress_curves(progress_result, show_ci = TRUE)

Arguments

Value

A ggplot2 object.

Description

Quick visual summary of several outcome metrics by scenario using a radial (polar) coordinate system.

Usage

plot_radar(data, scenarios, metrics = c("event_rate", "compliance_index"))

Arguments

Value

A ggplot2 object.

Description

Heatmap of metric values (median across replications) for each scenario-metric combination. Useful as an at-a-glance summary across all scenarios.

Usage

plot_scenario_heatmap(
  data,
  scenarios = NULL,
  metrics = c("event_rate", "compliance_index")
)

Arguments

Value

A ggplot2 object.

Description

Visualises per-region SDI as a tiled map. If the data contain x and y region centroid columns, tiles are placed at those coordinates; otherwise the regions are displayed as a simple bar-style strip.

Usage

plot_sdi_map(sdi)

Arguments

Value

A ggplot2 object.

Description

Plots a metric column from the timeseries table over time_step, stratified by scenario (and optionally another variable).

Usage

plot_timeline(data, metric, scenarios = NULL, group = NULL)

Arguments

Value

A ggplot2 object.

Description

Computes the full suite of effect metrics comparing two scenarios that differ only in the allocation policy. Returns deltas on the event rate and the Compliance Index, Cohen's d, risk differences and an auto-generated narrative suitable for pasting into a report. All event-rate differences are signed policy A minus B. Cohen's d uses the independent-sample, degrees-of-freedom-weighted pooled standard deviation. Bootstrap intervals and Wilcoxon tests assume independent simulation replications, not paired runs. NNT_surrogate is the reciprocal absolute mean rate difference; its direction is supplied by Risk_Difference_event. Missing replicate rates are omitted and effective counts are recorded. Each scenario needs an observed rate; intervals and standardized effects need at least two observations per scenario. Subgroup rates use the binary event flag, or status == "TERMINATED" only when the flag column is absent.

Usage

policy_effect(
  data,
  policy_a_scenario,
  policy_b_scenario,
  alpha = 0.05,
  n_bootstrap = 1000
)

Arguments

Details

No hardcoded defaults are used - you must supply both scenario IDs explicitly, so that the same function works for Profile A (e.g. "A-S08" vs. "A-S07") and Profile B (e.g. "B-S19" vs. "B-S00").

Value

An S3 object of class dynasimR_policy with slots delta_event, compliance_comparison, effect_sizes, wilcoxon_tests, narrative, and params.

Examples

## Not run: 
sim <- load_example_data()
pol <- policy_effect(sim,
  policy_a_scenario = "A-S08", policy_b_scenario = "A-S07")
print(pol)
cat(pol$narrative)

## End(Not run)

Description

Summarises longitudinal progress-score trajectories by scenario and optional grouping variables. By default, the summary pools entities within each scenario; include replication in group_by for replicate summaries. Quantile bounds describe the observed entity distribution, not confidence intervals for the median. Also returns a longitudinal tidy table suitable for plot_progress_curves().

Usage

progress_trajectory(data, group_by = c("scenario"), longitudinal = FALSE)

Arguments

Value

An S3 object of class dynasimR_progress with slots summary, longitudinal (if available) and params.

Description

Reads CSV outputs from any discrete-event or agent-based simulation framework that follows the dynasimR file-naming convention and validates them against the dynasimR data schema. Returns a structured S3 object of class dynasimR_data.

Usage

read_simulation(data_dir, scenarios = NULL, validate = TRUE, verbose = TRUE)

Arguments

Details

An optional scenario_metadata.csv uses one unique id per scenario. Its columns are joined without suffixes; conflicts with nonmissing table values are errors when validate = TRUE. With validation disabled, existing table values take precedence. The bundled scenario settings are used only for the package example directory, with local metadata taking precedence over bundled descriptions. External files never inherit example settings merely by sharing an ID. Each row retains its scenario's profile_type; load_info$profile_type is "mixed" when the loaded scenarios use different profiles.

Value

An S3 object of class dynasimR_data (a list) with slots summary, entities, timeseries, metadata and load_info.

Examples

## Not run: 
sim <- read_simulation("data/raw/")
sim <- read_simulation("data/raw/",
                       scenarios = c("A-S00", "A-S07", "A-S08"))
sim <- read_simulation(system.file("extdata", package = "dynasimR"))

## End(Not run)

Description

Aggregates primary outcome metrics (event rate, Compliance Index and - if present - median time-to-first-service) by the resource column of the joined scenario metadata.

Usage

resource_comparison(
  data,
  scenarios = NULL,
  metrics = c("event_rate", "compliance_index")
)

Arguments

Value

A tibble with one row per resource configuration and columns resource, n_scenarios, n_reps, and for each metric the median and 2.5%/97.5% quantile.

Examples

## Not run: 
sim <- load_example_data()
resource_comparison(sim)

## End(Not run)

Description

Applies dynasimR group colours (A/B/C) to a ggplot2 color aesthetic.

Usage

scale_color_group_dynasimR(...)

Arguments

Value

A ggplot2 scale object.

Description

Colour scale for policy

Usage

scale_color_policy_dynasimR(...)

Arguments

Value

A ggplot2 scale object.

Description

As scale_color_group_dynasimR() but for the fill aesthetic.

Usage

scale_fill_group_dynasimR(...)

Arguments

Value

A ggplot2 scale object.

Description

Describes all supported simulation scenarios (Profile A: A-S00..A-S14; Profile B: B-S00..B-S20) with their research-question mapping, policy, resource configuration and autonomy level.

Usage

scenario_meta

Format

A tibble with 36 rows and the following columns:

id

Character. Scenario identifier with prefix ("A-" for Profile A, "B-" for Profile B).

profile

Character. "Profile_A" or "Profile_B".

label

Character. Human-readable scenario name.

rq

Character. Associated research question tag ("RQ1".."RQ4", "SENS", "PIPE").

policy

Character. Policy type ("policy_a", "policy_b", "mixed", "NA").

resource

Character. Auxiliary-resource configuration ("none", "observation", "transport", "active", "mixed").

al

Integer. Autonomy level (0-5) or NA.

Source

Package example data.

Description

Computes the ratio of available service capacity to positive demand. Values > 1 indicate oversupply, values < 1 undersupply, and equal supply and demand give exactly 1. Rows with zero demand have an undefined ratio and are excluded from SDI summaries; a region with no valid ratio has NA SDI and NA undersupply status.

Usage

spatial_supply_demand(
  data,
  region_col = "region",
  supply_col = "supply",
  demand_col = "demand",
  eps = 1
)

Arguments

Value

A tibble with the region column, supply_median, demand_median, sdi_median, sdi_q025, sdi_q975, undersupply, n_observed (valid paired ratios) and n_zero_demand. The interval is the observed 2.5th to 97.5th percentile range, not a confidence interval for the median.

Description

Computes median and interquartile range of recorded times for each processing stage along the entity flow. If a reached_stageN column is present in the entity data, computes the fraction of entities completing each stage among nonmissing completion indicators. Time summaries use all recorded nonmissing values, including values for unreached entities if supplied; they are descriptive quantiles, not censoring-adjusted estimates. A time_to_stageN column may contain cumulative elapsed time rather than time spent in that stage.

Usage

stage_throughput(data, stages = c("Stage1", "Stage2", "Stage3", "Stage4"))

Arguments

Value

A tibble with columns scenario, stage, n, median_time, q25, q75, completed_frac.

Description

Illustrative Weibull shape and scale parameters for modelling time-to-event trajectories, stratified by priority category (P1-P4). Values are provided as a starting point and can be replaced by domain-specific values for a particular application.

Usage

survival_params

Format

A tibble with 4 rows and the following columns:

category

Character. Priority category ("P1".."P4").

k

Numeric. Weibull shape parameter.

lambda

Numeric. Weibull scale parameter (time units).

source

Character. Source note.

Source

Package example data.

Description

A minimalist ggplot2 theme tuned for publication-quality single and double-column output at 11 pt base size.

Usage

theme_dynasimR(base_size = 11, legend_pos = "bottom")

Arguments

Value

A ggplot2 theme object.

Description

Given a baseline scenario and perturbation scenarios, computes the change in the outcome metric for each perturbation relative to the baseline.

Usage

tornado_data(data, baseline, perturbations, outcome = "event_rate")

Arguments

Value

A tibble suitable for a tornado plot with columns scenario, delta, lo, hi, sorted by absolute delta. lo and hi are the perturbation's observed percentile range minus the fixed baseline median, not a confidence interval for their difference.

Description

Checks required columns, nonmissing scenario/replication identifiers, numeric types, finite observed values and bounded rates. Entity and time-series scenario/replication pairs must occur in the summary table. Missing measurements are allowed; analysis functions document their treatment. Data values are not modified.

Usage

validate_dynasimR_data(x, strict = FALSE)

Arguments

Value

The input x, invisibly, with current issues in the validation_issues attribute, or no such attribute when valid.