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"