DSAMbayes Documentation

Documentation for DSAMbayes 1.3.5, a Bayesian marketing mix modelling toolkit for R, built on Stan.

DSAMbayes provides interfaces for single-market regression (BLM), multi-market hierarchical models with partial pooling, pooled models with structured media coefficients, and a bounded fixed-effects estimator. The fixed-effects API is coefficient-only and deliberately excludes the level-scale post-fit interfaces available to other model classes.

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 behaviour, 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 1.3.5

  • Supported workflows: BLM, RE, CRE, and pooled modelling; interactive R workflows; YAML runner validate and run; diagnostics; model selection; and budget optimisation.
  • Implemented but not qualified: the direct R fixed_effects() API supports Gaussian coefficient and residual-noise inference through MCMC plus within-contrast diagnostics. FE supports YAML runner validation, dry-run, and bounded MCMC fitting with a dedicated coefficient, sampler, within-design, contrast-residual, and contrast posterior-predictive artefact set. P4-J bounded technical gates passed for live runner execution, explicit-prior prior-only sampling, balanced and unbalanced one-replication recovery, and sampler diagnostics. This execution and regression evidence does not make the estimator production-qualified: it does not estimate repeated-sampling coverage or reliability. FE still rejects MAP, unit-intercept recovery, level prediction, generic model diagnostics, model selection, decomposition, counterfactual analysis, optimisation, forecasting, and deployment.
  • 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, and time-series CV is not supported for pooled runs.
  • Reserved or limited surfaces: forecast currently creates only the 70_forecast/ stage with no forecast files or plots. Runner decomposition artefacts are linear term-contribution summaries and fail closed for hierarchical, offset-bearing, and probabilistic-media-transform models.

Changes in 1.3.5

Version 1.3.5 adds the bounded coefficient-only fixed_effects() API and its bounded YAML validation, dry-run, fitting, and artefact contract. Completed FE runs remain unqualified and do not enter the generic level-scale or decision-layer pipeline. See Estimator Capabilities for the exact execution boundary and separately gated repeated-sampling qualification work.

The earlier v1.3.4 release introduced:

  • Posterior counterfactual response: aligned scenario and reference paths can be evaluated with posterior uncertainty for supported fitted models.
  • Safer transformed-media handling: hierarchical row alignment and single-channel Stan payload dimensions are preserved explicitly.
  • Clearer runner stages: scenario analysis uses 60_scenario_analysis/, forecasting remains reserved at 70_forecast/, and optimisation uses 80_optimisation/.
  • Native decomposition: the external DSAMdecomp and teller path has been removed; unsupported decomposition paths fail closed.

Estimator qualification remains gated by the estimator-methodology plan. An implemented capability is not a production qualification.

Authorship