DSAMbayes Documentation

Documentation for DSAMbayes v1.3.3 — a Bayesian marketing mix modelling toolkit for R, built on Stan.

DSAMbayes provides a unified interface for building, fitting, and interpreting MMM models. It supports single-market regression (BLM), multi-market hierarchical models with partial pooling, and pooled models with structured media coefficients. All model types share the same post-fit interface for posterior extraction, diagnostics, decomposition, and budget optimisation.

The docs are organised around a simple idea: DSAMbayes is not just an API or a runner. It is a way of operating a principled Bayesian MMM workflow with explicit assumptions, diagnostic gates, and decision rules.

If you are coming from OLS or frequentist MMM

Start with the workflow pages, not the YAML reference.

Where to start

You want to… Start here
Install and run your first model Install and Setup → Quickstart
Understand the modelling workflow Principled Bayesian Workflow → What Principled Means
Translate from classical MMM thinking Frequentist to Bayesian Translation
Decide how to set priors Stage 2: Model and Priors → Priors and Boundaries
Decide which diagnostics matter most Stage 4: Computation and Sampler → Stage 5: Model Adequacy
Run a reproducible YAML-driven pipeline Quickstart → CLI Usage
Interpret run outputs and plots Interpret Diagnostics → Plot Catalogue
Compare models and select a candidate Compare Runs

Documentation sections

  • Getting Started — installation, environment setup, first runs, and first model tutorials
  • Principled Bayesian Workflow — the methodology spine: stages, assumptions, prior-setting discipline, diagnostics, and decision gates
  • Runner — CLI usage, YAML config schema, and output artefacts
  • Modelling Reference — model classes, priors, boundaries, diagnostics, response scale, and optimisation semantics
  • Plots — catalogue of every plot the runner produces, with interpretation guidance
  • How-To Guides — task-oriented recipes for common workflows
  • FAQ — answers to common questions
  • Appendices — glossary, module index, and traceability map

The workflow contract in one view

Stage Main question Typical DSAMbayes evidence
Model and priors Are the assumptions explicit and defensible? formula, priors, boundaries, response-scale choice
Computation Are the posterior draws trustworthy? Rhat, ESS, divergences, treedepth, BFMI
Adequacy Does the fitted model describe the data credibly? fit plots, PPC, residual behavior, LOO/Pareto-k
Interpretation Are decomposition and optimisation outputs fit for use? overall gate status plus uncertainty-aware reporting

Passing one row does not automatically imply the next row passes.

Support boundaries in v1.3.3

  • Supported workflows — BLM, RE, CRE, and pooled modelling; interactive R workflows; YAML runner validate and run; diagnostics; model selection; and budget optimisation.
  • Supported with explicit limits — pooled models require MCMC, target.offset_column is supported only for model.type: blm, outputs.save_deployment_model_rds is supported for model.type: blm, for model.type: pooled with fit.method: mcmc, and for hierarchical model.type: re/cre with fit.method: mcmc, hierarchical deployment scoring is seen-groups-only, time-series CV is not supported for pooled runs, and hierarchical response decomposition may be skipped when model.matrix() cannot evaluate formulas with random-effects syntax.
  • Reserved or limited surfaces — forecast currently creates only the 70_forecast/ stage with no forecast files or plots, and post-run decomposition artefacts are written only when they are enabled and can be computed from the fitted model.

What changed in v1.3.3

Key changes in this release (see CHANGELOG.md for full details):

  • Reliable local-run status — runme.R now preserves completed but non-publishable runner outcomes and exits non-zero when action is required.
  • Fail-closed quality lanes — explicitly requested lint and test checks fail when their required tooling is unavailable.

Earlier v1.3.2 changes included release-metadata alignment, stricter prior guardrails, and the pooled-boundary scaling fix.

Authorship