Run from YAML

Objective

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

Prerequisites

  • DSAMbayes 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

source scripts/r-library-path.sh
dsambayes_set_r_library host
mkdir -p "$R_LIBS_USER" .cache
export XDG_CACHE_HOME="$PWD/.cache"

2. Validate the configuration (dry run)

Rscript scripts/dsambayes.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/dsambayes.R run --config config/cre_geo_panel.yaml

Expected outcome:

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

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 decomposition tables/plots when enabled and available
Diagnostics 40_diagnostics/ diagnostics_report.csv, diagnostic plots
Model selection 50_model_selection/ LOO summary, Pareto-k plot (if MCMC)
Optimisation 60_optimisation/ Allocation summary, response curves (if enabled)

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).

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, diagnostics publish-gate enforcement failed, or a post-fit artifact 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

Programmatic API note:

  • DSAMbayes::run_from_yaml() can now return a completed runner_result with outcome: completed_with_artifact_write_fail when the fit succeeded but a later artifact-writing step failed, including TSCV artifact 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 dsambayes_runtime_error, with the same runner_result attached as condition$result.