Output Directory Schema

Each pipeline run creates a timestamped directory under the configured output_dir:

<output_dir>/<run_name>_<YYYYMMDD_HHMMSS>

The timestamp is generated in UTC. The runner creates every stage directory up front, then updates run_manifest.json as stages start, complete, skip, or fail.

Directory tree

results/
  geo_panel_baseline_20260308_153000/
    run_manifest.json
    00_run_metadata/
    10_pre_diagnostics/
    20_model_fit/
    30_model_assessment/
    35_holdout_validation/
    40_decomposition/
    50_diagnostics/
    60_response_curves/
    70_optimisation/

Stage directories

See Runner Overview for the stage order and optionality.

Main artefacts by stage

00_run_metadata

Main files:

• a copy of the original config under its source filename
• config.original.yaml
• config.resolved.yaml
• session_info.txt
• dataset_metadata.json
• model_metadata.json
• data_dictionary.csv
• design_matrix_manifest.csv
• spec_summary.csv
• holiday_feature_manifest.csv when holidays are configured

config.resolved.yaml normalises configured data and holiday paths to absolute paths and records the effective sampler configuration on the model.

10_pre_diagnostics

Main files:

• prior_predictive.nc
• prior_predictive.png

20_model_fit

Main files:

• model.nc
• trace.png
• posterior_summary.csv

30_model_assessment

Main files:

• posterior_predictive.nc
• posterior_predictive.png
• posterior_predictive_summary.csv
• observed.csv
• fitted.csv
• fit_timeseries.png
• fit_scatter.png
• residuals.csv
• residuals_timeseries.png
• residuals_hist.png
• residuals_vs_fitted.png

This stage is the in-sample or training-fit assessment. It uses the same data the model was fit on and should not be read as the pipeline’s out-of-sample validation layer.

35_holdout_validation

Main files:

• validation_metadata.json
• holdout_posterior_predictive.nc
• holdout_predictive_summary.csv
• holdout_predictive_report.json
• holdout_observed.csv
• holdout_fitted.csv
• holdout_residuals.csv
• holdout_timeseries.png
• holdout_residuals_acf.png

The holdout summary and report include uncertainty-aware metrics such as crps, bias, and fixed coverage columns for coverage_50, coverage_80, and coverage_94.

This stage is optional. When validation is absent or disabled in YAML, the directory still exists and the stage is marked skipped.

40_decomposition

Main files:

• waterfall_components_decomposition.png
• weekly_media_contribution.png
• channel_contributions.csv
• baseline_contributions.csv
• mean_contributions_over_time.csv

50_diagnostics

Main files:

• design_summary.csv
• design_report.json
• vif_report.csv
• mcmc_summary.csv
• mcmc_report.json
• predictive_summary.csv
• predictive_report.json
• residual_diagnostics.csv
• residuals_acf.png
• diagnostics_report.csv
• diagnostics_summary.txt
• chain_diagnostics.txt

The design-oriented files are raw input screening outputs. In particular, diagnostics_report.csv labels the corresponding phase as raw_input_screening rather than design.

60_response_curves

Main files:

• saturation_curve.nc
• saturation_curve_summary.csv
• saturation_curve.png
• forward_pass_contribution_curve.nc
• forward_pass_contribution_curve_summary.csv
• forward_pass_contribution_curve.png
• adstock_curve.nc
• adstock_curve_summary.csv
• adstock_curve.png

These artefacts are intentionally different:

• saturation_curve.* is the sampled saturation transformation on the scaled channel axis, exported with original-scale contribution values for easier reading. The PNG overlays that saturation-only curve against posterior mean realised contributions.
• forward_pass_contribution_curve.* is a full-model direct contribution artefact. It rescales the observed historical spend path from 0% to 200%, runs that spend through the fitted adstock and saturation path, and records the resulting total channel contribution in original target units.
• adstock_curve.* is the sampled carryover-weight profile for one impulse.

70_optimisation

This directory is present for every run, but the stage is skipped unless the YAML config contains an optimization block.

Main files when the stage runs:

• optimized_allocation.nc
• optimized_allocation.csv
• response_distribution.nc
• optimize_result.json
• budget_summary.csv
• budget_response_points.csv
• budget_impact.csv
• budget_bounds_audit.csv
• budget_roi_cpa.csv
• budget_response_curves.csv
• budget_mroi.csv
• budget_optimisation.json
• several PNG plots for allocation, contribution over time, response curves, impact, bounds audit, and ROI or CPA

run_manifest.json

The manifest is the machine-readable index for the whole run.

Top-level fields include:

data includes:

• x_shape
• y_length
• target_column
• x_columns

Stage records

Each stage record contains:

The artifacts mapping uses root-relative paths such as 20_model_fit/model.nc.

Stage statuses

Common cases:

• Stage 35 is skipped when validation is missing or disabled from YAML.
• Stage 70 is skipped when optimization is missing from YAML.
• Later stages become not_reached after the first failure.

Practical use

Use the run directory when you want:

• a stable folder for downstream reporting
• a machine-readable audit trail through run_manifest.json
• stage-level links to artefacts without hard-coding filenames

If you want to add new artefact types or stages, see Extending the Runner.