Quickstart (YAML Runner)

Goal

Complete one reproducible DSAMbayes runner execution from validation to artefact inspection, then load the fitted model in R to explore the results interactively.

This page is operational by design. It teaches you how to run the package, not the full modelling methodology. After the quickstart succeeds, use Principled Bayesian Workflow before treating outputs as decision-ready.

Before you start

Complete the setup in Install and Setup. If you want to build a model interactively from R code instead of YAML, see Your First BLM Model.

1. Set up the environment

Open a terminal in the repository root:

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: exits with code 0. No Stan compilation or sampling occurs.

3. Execute the full run

Rscript scripts/dsambayes.R run --config config/blm_timeseries.yaml

Expected: a timestamped run directory under results/ with staged outputs.

4. Locate and inspect the run directory

latest_run="$(ls -td results/* | head -n 1)"
echo "$latest_run"
find "$latest_run" -maxdepth 2 -type d | sort

Expected stage folders:

5. Verify key artefacts

test -f "$latest_run/00_run_metadata/config.compiled.yaml" && echo "ok: config.compiled.yaml"
test -f "$latest_run/00_run_metadata/config.resolved.yaml" && echo "ok: config.resolved.yaml"
test -f "$latest_run/20_model_fit/model.rds" && echo "ok: model.rds"
test -f "$latest_run/30_post_run/posterior_summary.csv" && echo "ok: posterior_summary.csv"
test -f "$latest_run/40_diagnostics/diagnostics_report.csv" && echo "ok: diagnostics_report.csv"

6. Load the model in R

The fitted model is saved as an RDS object. Load it interactively to explore:

library(DSAMbayes)

model <- readRDS("results/<run_dir>/20_model_fit/model.rds")

# Posterior coefficient summary
post <- get_posterior(model)

# Fit quality
cat("Median R²:", median(r2(model)), "\n")

# Sampler diagnostics
chain_diagnostics(model)

# Fitted values
head(fitted(model))

7. Review diagnostics

Open 40_diagnostics/diagnostics_report.csv:

cat "$latest_run/40_diagnostics/diagnostics_summary.txt"

Quick interpretation:

• pass — no immediate blocker
• warn — review before sharing or acting
• fail — do not treat the run as publishable or decision-ready

For the operational triage, see Interpret Diagnostics. For the methodological meaning of these gates, see:

• Stage 4: Computation and Sampler
• Stage 5: Model Adequacy

8. Start from a tracked example config

Copy one of the two tracked examples and adapt it to your data:

• config/blm_timeseries.yaml for single-series work
• config/cre_geo_panel.yaml for geo-panel CRE work

Edit the copied YAML to point to your data and columns, then validate and run.

What the quickstart does not prove

A successful run means:

• the package is installed correctly
• the runner contract works on the example config
• you have a complete staged result

It does not by itself prove:

• the priors are appropriate
• the fit is decision-ready
• the decomposition is substantively meaningful
• the optimisation output should be acted on

That is why the next stop should be the workflow pages.

If the quickstart fails

• re-run validate before run
• read the full error message
• inspect 00_run_metadata/config.resolved.yaml
• inspect 00_run_metadata/config.compiled.yaml
• use Debug Run Failures

Next steps

• Principled Bayesian Workflow — methodology before interpretation
• Your First BLM Model — interactive R API walkthrough
• Config Schema — full YAML reference
• Output Artefacts — file-level run contract
• Plot Catalogue — plot interpretation