Runner

Purpose

Document CLI and YAML runner contracts for reproducible DSAMbayes runs.

Audience

  • Users operating DSAMbayes through scripts/dsambayes.R.
  • Engineers maintaining runner config and artefact contracts.

Pages

Page Topic
CLI Usage Commands, flags, exit codes, and error modes
Config Schema YAML keys, defaults, and validation rules
Output Artefacts Staged folder layout, file semantics, and precedence rules

Subsections of Runner

CLI Usage

Purpose

Define the supported command-line interface for scripts/dsambayes.R, including required flags, optional flags, and execution semantics.

Prerequisites

Before using the CLI:

  • Complete Install and Setup.
  • Run commands from repository root.
  • Ensure DSAMbayes is installed and available in R_LIBS_USER.

Entry point

Rscript scripts/dsambayes.R <command> [flags]

The script supports these commands:

  • init
  • validate
  • run
  • help (or -h / --help)

Command summary

Command Required flags Optional flags Behaviour
init --out --template, --overwrite Writes a config template file.
validate --config --run-dir Runs config and data checks only (dry_run = TRUE).
run --config --run-dir Executes the full pipeline (dry_run = FALSE) and writes run artefacts.
help none none Prints usage text and exits.

Flag reference

init

  • --out <path> (required): output path for the generated YAML file.
  • --template <name> (optional): template name. Default is blm.
    • Supported values in script: master, blm, re, cre, pooled, hierarchical.
    • hierarchical maps to the same template file as re.
  • --overwrite (optional flag): allow overwrite of an existing --out file.

validate

  • --config <path> (required): YAML config path.
  • --run-dir <path> (optional): explicit run directory path.

run

  • --config <path> (required): YAML config path.
  • --run-dir <path> (optional): explicit run directory path.

Usage examples

Show help

Rscript scripts/dsambayes.R --help

Expected outcome: usage panel is printed with command syntax and notes.

Create a new config from template

Rscript scripts/dsambayes.R init --template blm --out config/local_quickstart.yaml

Expected outcome: config/local_quickstart.yaml is created.

Validate only (dry-run behaviour)

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml

Expected outcome: validation completes without fitting Stan models.

Validate with explicit run directory

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/quickstart_validate

Expected outcome: validation uses the provided run directory path when writing run metadata.

Execute full run

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.yaml

Expected outcome: full modelling pipeline executes and artefacts are written under results/.

Execute full run with explicit run directory

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/quickstart_run

Expected outcome: artefacts are written to results/quickstart_run (subject to overwrite rules in config).

Exit and error behaviour

  • Success exits with status 0.
  • CLI argument or runtime errors exit with status 2.
  • Typical hard failures include:
    • DSAMbayes not installed.
    • Missing required flags (--out or --config).
    • Unknown command.
    • Unknown argument format.

Operational notes

  • validate is the recommended pre-run gate. Use it before run whenever you change config or data.
  • run prints a run summary and suggested next-step artefacts at completion.
  • The CLI itself does not define model semantics. It delegates execution to DSAMbayes::run_from_yaml().

Config Schema

Purpose

This page defines the YAML contract used by:

  • scripts/dsambayes.R
  • DSAMbayes::run_from_yaml()

It documents defaults, allowed values, and cross-field constraints enforced by the runner.

Schema processing order

The runner processes config in this order:

  1. Parse YAML.
  2. Coerce YAML infinity tokens (.Inf, -.Inf).
  3. Apply defaults (resolve_config_defaults()).
  4. Resolve relative paths against the config file directory (resolve_config_paths()).
  5. Validate values and cross-field constraints (validate_config()).
  6. Validate formula safety unless security.allow_unsafe_formula: true.

Root sections

Key Default Notes
schema_version 1 Must be 1.
data object Input data path, format, date handling, dictionary metadata.
model object Formula, model type, scaling, compile behaviour.
cre object Correlated random effects settings (Mundlak).
pooling object Pooled model map and grouping settings.
transforms object Transform mode and sensitivity scenarios.
priors object Default priors plus sparse overrides.
boundaries object Parameter boundary overrides.
time_components object Managed holiday feature generation.
fit object MCMC or optimisation fit arguments.
allocation object Post-fit budget optimisation settings.
outputs object Run directory and artefact save flags.
forecast object Reserved forecast stage toggle.
diagnostics object Policy mode, identifiability, model selection, time-series selection.
security object Formula safety bypass flag.

Minimal valid config

schema_version: 1

data:
  path: data/your_data.csv
  format: csv

model:
  formula: y ~ x1 + x2

Expected outcome: this resolves with defaults for all omitted sections and passes schema validation if the file exists and formula variables exist in data.

Section reference

schema_version

Key Type Default Rules
schema_version integer 1 Only 1 is supported.

data

Key Type Default Rules
data.path string none Required. File must exist. Relative path resolves from config directory.
data.format string inferred from file extension Must be csv, rds, or long.
data.date_var string or null null Required for data.format: long. Required when holidays are enabled. Required at runtime for time-series selection.
data.date_format string or null null Optional date parser format for date columns.
data.na_action string omit Must be omit or error during formula/data checks.
data.long_id_col string or null null Required when data.format: long.
data.long_variable_col string or null null Required when data.format: long.
data.long_value_col string or null null Required when data.format: long.
data.dictionary_path string or null null Optional CSV. Must exist if provided. Relative path resolves from config directory.
data.dictionary mapping {} Optional inline metadata keyed by term name. Allowed fields: unit, cadence, source, transform, rationale.

Long-format-specific rules:

  • data.long_id_col, data.long_variable_col, data.long_value_col, and data.date_var must all be set.
  • These four column names must be distinct.
  • Long data is reshaped wide before modelling and duplicate key rows are rejected.

model

Key Type Default Rules
model.name string config filename stem Used in run folder slug.
model.formula string none Required. Must parse to y ~ ....
model.type string auto auto, blm, re, cre, pooled.
model.kpi_type string revenue revenue or subscriptions.
model.scale boolean true Controls internal scaling before fit.
model.force_recompile boolean false Forces Stan recompile when true.

Model type resolution rules:

  • auto resolves to pooled if pooling.enabled: true.
  • auto resolves to cre if cre.enabled: true.
  • auto resolves to re if formula contains bar terms (for example (1 | group)).
  • auto resolves to blm otherwise.
  • re or cre requires bar terms in formula.
  • blm or pooled cannot be used with bar terms.

cre

Key Type Default Rules
cre.enabled boolean false (or true when model.type: cre) Cannot be true for model.type: blm or pooled.
cre.vars list of strings [] Required and non-empty when cre.enabled: true.
cre.group string or null null Grouping column used in CRE construction.
cre.prefix string cre_mean_ Prefix for generated CRE mean terms.

pooling

Key Type Default Rules
pooling.enabled boolean false (or true when model.type: pooled) Cannot be true for model.type: re or cre.
pooling.grouping_vars list of strings [] Required and non-empty when pooling is enabled.
pooling.map_path string or null null Required when pooling is enabled. File must exist. Relative path resolves from config directory.
pooling.map_format string or null inferred from map_path extension Must be csv or rds.
pooling.min_waves integer or null null If set, must be positive integer.

Pooling map requirements at model-build time:

  • Must include a variable column.
  • Must include every column named in pooling.grouping_vars.
  • variable values must be unique.

transforms

Key Type Default Rules
transforms.mode string fixed_formula Currently only fixed_formula is supported.
transforms.sensitivity.enabled boolean false If true, requires fit.method: optimise.
transforms.sensitivity.scenarios list [] Required and non-empty when sensitivity is enabled.

Each sensitivity scenario requires:

  • name (unique, non-empty, not base)
  • formula (safe formula string unless unsafe mode is enabled)

priors

Key Type Default Rules
priors.use_defaults boolean true Must be true in current runner version.
priors.overrides list [] Optional sparse overrides.

Prior override row contract:

  • parameter (string, must exist in model prior table)
  • family (normal or lognormal_ms, default normal)
  • mean (numeric)
  • sd (numeric, > 0)

lognormal_ms extra constraints:

  • mean > 0
  • allowed only for noise_sd and parameters matching sd_<index>[<term>]

boundaries

Key Type Default Rules
boundaries.overrides list [] Optional parameter boundary overrides.

Boundary override row contract:

  • parameter (string, must exist in model boundary table)
  • lower (numeric, default -Inf)
  • upper (numeric, default Inf)

time_components

Key Type Default Rules
time_components.enabled boolean false Master toggle.
time_components.holidays.enabled boolean false Enables holiday feature generation.
time_components.holidays.calendar_path string or null null Required when holidays are enabled. CSV or RDS. Relative path resolves from config directory.
time_components.holidays.date_col string or null null Optional calendar date column override.
time_components.holidays.label_col string holiday Holiday label column.
time_components.holidays.date_format string or null null Optional parser format for character dates.
time_components.holidays.week_start string monday One of monday … sunday.
time_components.holidays.timezone string UTC Timezone used in week alignment.
time_components.holidays.prefix string holiday_ Prefix for generated terms.
time_components.holidays.window_before integer 0 Must be non-negative.
time_components.holidays.window_after integer 0 Must be non-negative.
time_components.holidays.aggregation_rule string count count or any.
time_components.holidays.overlap_policy string count_all count_all or dedupe_label_date.
time_components.holidays.add_to_formula boolean true Auto-add generated terms to formula.
time_components.holidays.overwrite_existing boolean false If false, generated name collisions abort.

fit

Key Type Default Rules
fit.method string mcmc mcmc or optimise.
fit.seed numeric or null null Optional scalar seed.
fit.optimise.n_runs integer 10 Multi-start retries for fit_map().
fit.mcmc.chains integer 4 MCMC chains.
fit.mcmc.iter integer 2000 Total iterations per chain.
fit.mcmc.warmup integer 1000 Warmup iterations per chain.
fit.mcmc.cores integer 1 Parallel chains.
fit.mcmc.refresh integer 0 Stan progress refresh interval.
fit.mcmc.parameterization.positive_priors string centered centered or noncentered.

Allowed keys under fit.optimise:

  • n_runs, iter, seed, init, algorithm, hessian, as_vector

Allowed keys under fit.mcmc:

  • chains, iter, warmup, thin, cores, refresh, seed, init, control, parameterization

Allowed keys under fit.mcmc.parameterization:

  • positive_priors

allocation

Key Type Default Rules
allocation.enabled boolean false Enables budget optimisation stage.
allocation.scenario string max_response max_response or target_efficiency.
allocation.target_value numeric or null null Required and > 0 for target_efficiency.
allocation.n_candidates integer 2000 Must be integer >= 10.
allocation.seed numeric or null null Optional allocator seed.
allocation.budget.total numeric or null null Required and > 0 for max_response. Optional > 0 for target_efficiency.
allocation.channels list [] Required and non-empty when allocation is enabled.
allocation.reference_spend numeric/list or null null Optional baseline spend vector.
allocation.currency_scale numeric or null null Optional positive scaling factor.
allocation.posterior.draws integer 500 Must be positive integer when provided.
allocation.objective.target string kpi_uplift kpi_uplift or profit.
allocation.objective.value_per_kpi numeric or null null Required at optimisation runtime for objective.target: profit.
allocation.objective.kpi_baseline numeric or null null Must be > 0 when provided.
allocation.objective.allow_relative_log_uplift boolean false Allows relative uplift output for log-response runs without baseline.
allocation.objective.risk.type string mean mean, mean_minus_sd, or quantile.
allocation.objective.risk.lambda numeric 0 Must be >= 0 when risk.type: mean_minus_sd.
allocation.objective.risk.quantile numeric 0.1 Must be in (0, 1).

Channel row contract (allocation.channels[]):

  • term required, scalar string, unique across channels.
  • name optional, defaults to term, must be unique.
  • spend_col optional, defaults to name.
  • bounds.min optional, defaults 0, must be finite and >= 0.
  • bounds.max optional, defaults Inf, but operationally must be finite and >= bounds.min.
  • currency_col optional.
  • response optional mapping:
    • type: identity (default)
    • type: atan requires positive scale
    • type: log1p requires positive scale
    • type: hill requires positive k and positive n

Log-response runtime rules:

  • scenario: target_efficiency requires allocation.objective.kpi_baseline.
  • Other scenarios require kpi_baseline unless allow_relative_log_uplift: true.

outputs

Path keys:

Key Type Default Rules
outputs.root_dir string results Relative path resolves from config directory.
outputs.run_dir string or null null If relative, resolves under outputs.root_dir.
outputs.overwrite boolean false Existing run dir can be reused only when true and contents are recognised runner artefacts.
outputs.layout string staged staged or flat.
outputs.decomp_top_n integer 8 Must be positive integer.

Save toggles (all booleans):

Key Default
outputs.save_model_rds true
outputs.save_posterior_rds false
outputs.save_posterior_summary_csv true
outputs.save_fitted_csv true
outputs.save_observed_csv true
outputs.save_chain_diagnostics_txt true
outputs.save_diagnostics_report_csv true
outputs.save_diagnostics_summary_txt true
outputs.save_session_info_txt true
outputs.save_transform_sensitivity_summary_csv true
outputs.save_transform_sensitivity_parameters_csv true
outputs.save_transform_assumptions_txt true
outputs.save_data_dictionary_csv true
outputs.save_allocator_csv true
outputs.save_allocator_png true
outputs.save_allocator_json false
outputs.save_decomp_csv true
outputs.save_decomp_png true
outputs.save_spec_summary_csv true
outputs.save_design_matrix_manifest_csv true
outputs.save_vif_report_csv true
outputs.save_predictor_risk_register_csv true
outputs.save_fit_png true
outputs.save_residuals_csv true
outputs.save_diagnostics_png true
outputs.save_model_selection_csv true
outputs.save_model_selection_pointwise_csv true

Run directory precedence:

  1. CLI --run-dir / run_from_yaml(..., run_dir=...)
  2. outputs.run_dir
  3. Timestamped directory under outputs.root_dir

forecast

Key Type Default Rules
forecast.enabled boolean false Reserved stage toggle (70_forecast).

diagnostics

Key Type Default Rules
diagnostics.enabled boolean true Enables diagnostics pipeline.
diagnostics.policy_mode string publish explore, publish, or strict.
diagnostics.enforce_publish_gate boolean false If true, run aborts only when overall status is fail.

diagnostics.model_selection:

Key Default Rules
enabled true Toggle PSIS-LOO check pipeline.
method psis_loo Currently only psis_loo is supported.
max_draws null If set, must be > 0.
pareto_k_warn 0.7 Finite value must be in [0, 1], or Inf.
pareto_k_fail Inf Finite value must be in [0, 1] and strictly greater than pareto_k_warn.
moment_match false Boolean.
reloo false Boolean.
top_n 10 Must be >= 0.

diagnostics.time_series_selection:

Key Default Rules
enabled false When true, runs refit-and-score time-series selection.
method blocked_cv blocked_cv or leave_future_out.
horizon_weeks 13 Positive integer.
n_folds 4 Positive integer.
stride_weeks horizon_weeks Positive integer.
min_train_weeks 52 Positive integer.
save_pointwise false Boolean.
save_png true Boolean.

Time-series selection constraints:

  • Requires fit.method: mcmc.
  • Not supported for pooled runs.
  • Requires data.date_var set and present in data.

diagnostics.identifiability:

Key Default Rules
enabled true Boolean.
media_terms [] Character list.
baseline_terms [] Character list.
baseline_regex `["^t(_ $)", “^sin[0-9]”, “^cos[0-9]”, “^holiday_”]`
abs_corr_warn 0.80 Must be in [0, 1).
abs_corr_fail 0.95 Finite value must be > abs_corr_warn and <= 1, or Inf.

security

Key Type Default Rules
security.allow_unsafe_formula boolean false If false, formula safety checks are enforced.

Safe formula calls when unsafe mode is disabled:

  • Operators: ~, +, -, *, /, ^, :, |, (
  • Functions: log, exp, sqrt, atan, sin, cos, tan, I, offset, pmax, pmin, abs
  • Namespaced calls: dplyr::lag, dplyr::lead
  1. Generate a template:
Rscript scripts/dsambayes.R init --template master --out config/my_run.yaml
  1. Validate before running:
R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/my_run.yaml
  1. Execute:
R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/my_run.yaml

Output Artefacts

Purpose

This page defines what the YAML runner writes, where files are written, and which config flags control each artefact.

Related pages:

Run directory and layout semantics

Run directory precedence:

  1. CLI --run-dir
  2. outputs.run_dir
  3. Timestamped folder under outputs.root_dir

Layout behaviour:

  • outputs.layout: staged (default) writes files under numbered stage folders.
  • outputs.layout: flat writes all files directly under the run directory.

Stage folders used by the runner:

  • 00_run_metadata
  • 10_pre_run
  • 20_model_fit
  • 30_post_run
  • 40_diagnostics
  • 50_model_selection
  • 60_optimisation
  • 70_forecast (directory only, when forecast.enabled: true)

Command behaviour

validate

  • validate uses dry_run = TRUE.
  • If no run directory is resolved, no artefacts are written.
  • If a run directory is resolved (--run-dir or outputs.run_dir), config.original.yaml is written.
  • If a run directory is resolved (--run-dir or outputs.run_dir), config.resolved.yaml is written.
  • If a run directory is resolved and outputs.save_session_info_txt: true, session_info.txt is written.
  • If forecast is enabled and a run directory is materialised, the 70_forecast/ directory is created.

run

  • run writes the full artefact set subject to config toggles and runtime conditions.

Artefact contract by stage

00_run_metadata

File Controlled by Written when Notes
config.original.yaml always run dir materialised Raw YAML text from the input config.
config.resolved.yaml always run dir materialised Defaults applied, paths resolved, schema validated.
session_info.txt outputs.save_session_info_txt flag is true Includes DSAMbayes version, schema version, model/fit metadata, and sessionInfo().

10_pre_run

File Controlled by Written when Notes
transform_assumptions.txt outputs.save_transform_assumptions_txt flag is true Written even if transform sensitivity scenarios are disabled.
transform_sensitivity_summary.csv outputs.save_transform_sensitivity_summary_csv sensitivity object exists with rows Requires transforms.sensitivity.enabled: true and successful scenario execution.
transform_sensitivity_parameters.csv outputs.save_transform_sensitivity_parameters_csv sensitivity object exists with rows Parameter means/SD by scenario.
dropped_groups.csv none groups dropped by pooling.min_waves filter Written only when sparse groups are excluded.
holiday_feature_manifest.csv none managed holidays enabled and features generated Documents generated holiday terms and active-week counts.
design_matrix_manifest.csv outputs.save_design_matrix_manifest_csv flag is true and manifest non-empty Per-term design metadata.
data_dictionary.csv outputs.save_data_dictionary_csv flag is true and dictionary table non-empty Merges inline YAML metadata and optional CSV dictionary metadata.
spec_summary.csv outputs.save_spec_summary_csv flag is true and table available Single-row model/spec summary.
vif_report.csv outputs.save_vif_report_csv flag is true and predictors available VIF diagnostics for non-intercept predictors.

20_model_fit

File Controlled by Written when Notes
model.rds outputs.save_model_rds flag is true Fitted model object.
posterior.rds outputs.save_posterior_rds flag is true and MCMC fit Raw posterior object for MCMC runs only.
fit_metrics_by_group.csv implicit fitted summary is computed Written when any of save_fitted_csv, save_fit_png, save_residuals_csv, save_diagnostics_png is true.
fit_timeseries.png outputs.save_fit_png flag is true and ggplot2 installed Observed vs fitted over time.
fit_scatter.png outputs.save_fit_png flag is true and ggplot2 installed Observed vs fitted scatter.

30_post_run

File Controlled by Written when Notes
observed.csv outputs.save_observed_csv flag is true Observed response on model response scale.
observed_kpi.csv outputs.save_observed_csv flag is true and response scale is log KPI-scale observed values (exp) with conversion_method = point_exp.
fitted.csv outputs.save_fitted_csv flag is true Fitted summaries on model response scale.
fitted_kpi.csv outputs.save_fitted_csv flag is true and response scale is log KPI-scale fitted summaries (exp).
posterior_summary.csv outputs.save_posterior_summary_csv flag is true and MCMC fit Posterior summaries for coefficients and scalar diagnostics.
optimisation_runs.csv none fit.method: optimise All optimisation starts.
optimisation_best.csv none fit.method: optimise Best run by RMSE.

Implementation note:

  • decomp_predictor_impact.csv, decomp_predictor_impact.png, decomp_timeseries.csv, and decomp_timeseries.png are present in stage mapping and config flags, but are not currently invoked by write_run_artifacts() in the active pipeline.

40_diagnostics

File Controlled by Written when Notes
chain_diagnostics.txt outputs.save_chain_diagnostics_txt flag is true and MCMC fit Chain diagnostics text output.
diagnostics_report.csv outputs.save_diagnostics_report_csv flag is true and diagnostics object exists One row per diagnostic check.
diagnostics_summary.txt outputs.save_diagnostics_summary_txt flag is true and diagnostics object exists Counts by status and overall status.
residuals.csv outputs.save_residuals_csv flag is true and fitted summary is computed Residual table on response scale.
residuals_timeseries.png outputs.save_diagnostics_png flag is true and ggplot2 installed Residuals over time.
residuals_vs_fitted.png outputs.save_diagnostics_png flag is true and ggplot2 installed Residuals vs fitted.
residuals_hist.png outputs.save_diagnostics_png flag is true and ggplot2 installed Residual histogram.
residuals_acf.png outputs.save_diagnostics_png flag is true and ggplot2 installed Residual autocorrelation plot.
residual_diagnostics.csv none diagnostics residual checks available Ljung-Box / ACF check outputs.
residuals_latent.csv none diagnostics latent residuals available Latent residual series from diagnostics object.
residuals_latent_acf.png outputs.save_diagnostics_png latent residuals available and ggplot2 installed Latent residual ACF plot.
boundary_hits.csv none boundary-hit table available Boundary-hit rates per parameter.
boundary_hits.png outputs.save_diagnostics_png boundary-hit table available and ggplot2 installed Boundary-hit visualisation.
within_variation.csv none within-variation table available Within-variation diagnostics for hierarchical terms.
within_variation.png outputs.save_diagnostics_png within-variation table available and ggplot2 installed Within-variation visualisation.
predictor_risk_register.csv outputs.save_predictor_risk_register_csv flag is true and table non-empty Ranked risk register combining VIF, within-variation, boundary hits, and slow-moving flags.

50_model_selection

File Controlled by Written when Notes
loo_summary.csv outputs.save_model_selection_csv flag is true, diagnostics.model_selection.enabled: true, and diagnostics report exists May be full PSIS-LOO summary or a stub row with skip reason.
loo_pointwise.csv outputs.save_model_selection_pointwise_csv flag is true, diagnostics report exists, and pointwise PSIS-LOO is available Optional pointwise LOO diagnostics.
tscv_folds.csv diagnostics.time_series_selection.enabled time-series selection enabled and folds produced Fold windows plus fold-level runtime/status metadata.
tscv_summary.csv diagnostics.time_series_selection.enabled time-series selection enabled Written for success, skipped, or error outcomes.
tscv_pointwise.csv diagnostics.time_series_selection.enabled + diagnostics.time_series_selection.save_pointwise enabled and pointwise rows available Optional pointwise holdout log predictive densities.
tscv_elpd_by_fold.png diagnostics.time_series_selection.save_png + outputs.save_diagnostics_png enabled and ggplot2 installed ELPD-by-fold chart.

60_optimisation

File Controlled by Written when Notes
budget_summary.csv outputs.save_allocator_csv allocation enabled and flag is true Scenario-level optimisation summary.
budget_allocation.csv outputs.save_allocator_csv allocation enabled and flag is true Recommended allocation by channel.
budget_diagnostics.csv outputs.save_allocator_csv allocation enabled and flag is true Candidate and objective diagnostics.
budget_response_curves.csv outputs.save_allocator_csv allocation enabled and flag is true Response-curve payload.
budget_response_points.csv outputs.save_allocator_csv allocation enabled and flag is true Key plotted points for response curves.
budget_roi_cpa.csv outputs.save_allocator_csv allocation enabled and flag is true ROI/CPA panel payload (depends on KPI type).
budget_impact.csv outputs.save_allocator_csv allocation enabled and flag is true Allocation impact payload.
budget_response_curves.png outputs.save_allocator_png allocation enabled, flag is true, and ggplot2 installed Response curves plot.
budget_roi_cpa.png outputs.save_allocator_png allocation enabled, flag is true, and ggplot2 installed ROI/CPA panel plot.
budget_impact.png outputs.save_allocator_png allocation enabled, flag is true, and ggplot2 installed Allocation impact plot.
budget_optimisation.json outputs.save_allocator_json allocation enabled, flag is true, and jsonlite installed Combined JSON payload (summary, allocation, diagnostics, plot_data).

70_forecast

Item Controlled by Written when Notes
70_forecast/ directory forecast.enabled flag is true Directory is created, but no forecast files are currently emitted by runner writers.

Response scale semantics (*_kpi.csv vs base files)

Base files (observed.csv, fitted.csv) are always on the model response scale:

  • identity response: KPI units
  • log response: log(KPI)

KPI-scale files are written only for log-response models:

  • observed_kpi.csv
  • fitted_kpi.csv

Conversion metadata:

  • observed_kpi.csv uses conversion_method = point_exp.
  • fitted_kpi.csv uses conversion_method = point_exp for fit.method: optimise.
  • fitted_kpi.csv uses conversion_method = drawwise_exp for fit.method: mcmc.

Diagnostics status semantics

diagnostics_report.csv status values:

  • pass: check passed configured thresholds
  • warn: check breached warning threshold
  • fail: check breached fail threshold
  • skipped: check not applicable or intentionally skipped

Overall status logic:

  • fail if any check is fail
  • warn if no fails and at least one warn
  • pass otherwise

diagnostics_summary.txt reports:

  • overall_status
  • counts for pass, warn, fail, skipped

Quick verification commands

List produced files for a run:

latest_run="$(ls -td results/* | head -n 1)"
find "$latest_run" -type f | sort

Inspect key diagnostics files:

latest_run="$(ls -td results/* | head -n 1)"
head -n 20 "$latest_run/40_diagnostics/diagnostics_report.csv"
head -n 20 "$latest_run/40_diagnostics/diagnostics_summary.txt"