Run from YAML

Objective

Execute a complete dsambayesplus model run from a YAML configuration file and verify the staged output artefacts.

Prerequisites

  • dsambayesplus installed locally (see Install and Setup).
  • A YAML config file (see Config Schema for structure).
  • Data file(s) referenced by the config are accessible.

Steps

1. Set up the environment

Complete the environment setup in Install and Setup (selecting the host library, creating the cache directory, and exporting XDG_CACHE_HOME) before continuing.

2. Validate the configuration (dry run)

Rscript scripts/dsambayesplus.R validate --config config/blm_timeseries.yaml

Expected outcome:

  • Exit code 0.
  • No Stan compilation or sampling occurs.
  • Metadata artefacts are written only if you supply --run-dir or set outputs.run_dir.

If validation fails:

  • Check the error message for missing data paths, invalid YAML keys, or formula errors.
  • Remember that the authored v2 schema does not expose model.formula; the runner compiles it from target, media, controls, and optional hierarchy / effects.
  • Fix the config and re-run validate before proceeding.

3. Run the model

Rscript scripts/dsambayesplus.R run --config config/cre_geo_panel.yaml

Expected outcome:

  • Exit code 0.
  • Full staged artefact tree under the run directory.

For the bounded fixed-effects runner path:

Rscript scripts/dsambayesplus.R run --config config/fe_panel.yaml

This runs the coefficient-only FE MCMC estimator and writes only the dedicated FE files documented under Output Artefacts. It does not run generic level-scale diagnostics, PSIS model selection, scenario analysis, optimisation, forecasting, or deployment. To add seen-unit expanding-window validation, enable diagnostics.time_series_selection; every fold must contain only holdout units already seen in training and at least two training rows per unit. A completed FE run is not a production qualification; its diagnostics summary records qualification_status: not_assessed.

4. Locate the run directory

The runner prints the run directory path during execution. It follows the pattern:

results/YYYYMMDD_HHMMSS_<run_label>/

5. Verify artefacts

Check that the following stage folders are populated:

Stage Folder Key files
Metadata 00_run_metadata/ config.original.yaml, config.resolved.yaml, config.compiled.yaml, artifact_schema.yaml, session_info.txt
Pre-run 10_pre_run/ Media spend plots, VIF bar chart
Model fit 20_model_fit/ model.rds, optional deployment_model.rds, fit plots
Post-run 30_post_run/ posterior_summary.csv, observed.csv, fitted.csv, plus runner linear term-contribution tables/plots when enabled and supported
Diagnostics 40_diagnostics/ diagnostics_report.csv, diagnostic plots
Model selection 50_model_selection/ LOO summary, Pareto-k plot (if MCMC)
Scenario analysis 60_scenario_analysis/ Scenario/reference response summaries (if enabled)
Optimisation 80_optimisation/ Allocation summary, response curves (if enabled)

The runner files retain legacy decomp_* names, but they are not the mapping/reference-point result returned by interactive decomp(). They fail closed for hierarchical, offset-bearing, and probabilistic-media-transform models, with the reason recorded in artifact_status.csv.

Optional deployment artifact:

  • Set outputs.save_deployment_model_rds: true to write 20_model_fit/deployment_model.rds.
  • This artifact is a compact deployment package for explicit predict(newdata = ...) and explicit-data decomposition; it does not replace model.rds.
  • Supported for model.type: blm, model.type: pooled with fit.method: mcmc, or hierarchical model.type: re / cre with fit.method: mcmc.
  • Pooled deployment artifacts score on authored terms and do not require pooling columns in deployment-time newdata / data = ... unless those columns are also ordinary formula terms.
  • Hierarchical deployment artifacts are seen-groups-only. Explicit newdata / data = ... must include the raw grouping columns, and decomposition also requires the response source column(s).
  • FE does not support deployment_model.rds. Its optional posterior.rds is a compact extracted posterior table, while model.rds is the fitted same-environment analysis object.

6. Quick verification commands

# Check diagnostics overall status
head -1 results/<run_dir>/40_diagnostics/diagnostics_report.csv

# View posterior summary
head results/<run_dir>/30_post_run/posterior_summary.csv

# Count artefact files
find results/<run_dir> -type f | wc -l

Failure handling

Symptom Likely cause Action
Exit code 2 during validate Config, data, or environment error Read error message; fix config or local setup
Exit code 1 during run Diagnostics overall status is fail, requested scenario analysis failed, diagnostics publish-gate enforcement failed, or a post-fit artefact write failed Review diagnostics and 00_run_metadata/run_status.yaml if present; the fit completed but the outcome is not publishable
Exit code 2 during run Stan compilation, sampling, config, or environment failure before a completed run result was returned Check the CLI error message, Stan cache, and local setup
Missing 20_model_fit/model.rds Fit did not complete Review runner log for Stan errors
Missing 20_model_fit/deployment_model.rds outputs.save_deployment_model_rds is false, model type / fit method is unsupported, or fit did not complete Check resolved config and confirm either model.type: blm, model.type: pooled with fit.method: mcmc, or hierarchical model.type: re/cre with fit.method: mcmc
Missing 40_diagnostics/ Diagnostics writer failed Check for upstream fit failures; review tryCatch messages
Missing 60_scenario_analysis/ Scenario analysis is disabled or failed Check scenario_analysis.enabled, input paths, and 00_run_metadata/run_status.yaml

For FE runs, missing generic observed.csv, fitted.csv, diagnostics_report.csv, PSIS model-selection, scenario, optimisation, forecast, or deployment files is expected. Use within_design.csv, contrast_residuals.csv, contrast_ppc.csv, level_diagnostics.csv, and diagnostics_summary.txt for the bounded FE runner reporting contract. level_diagnostics.csv is an in-sample conditional diagnostic for retained units, not held-out validation. When FE time-series validation is enabled, use 50_model_selection/tscv_summary.csv and, if requested, tscv_pointwise.csv for held-out seen-unit scoring. The direct R API separately supports conditional retained-unit intercepts, fitted level values, observed level data, and retained-unit prediction after MCMC.

Programmatic API note:

  • dsambayesplus::run_from_yaml() can return outcome: completed_with_scenario_analysis_fail when the fit succeeded but the requested scenario analysis failed, or completed_with_artifact_write_fail when a later artefact-writing step failed, including TSCV artefact writes.
  • For automation, inspect outcome, postfit_issue, and postfit_message instead of assuming every non-error return is fully successful.
  • Diagnostics publish-gate failures still raise dsambayesplus_runtime_error, with the same runner_result attached as condition$result.