dsambayesplus Documentation

Documentation for dsambayesplus 1.0.1, a private Bayesian marketing mix modelling toolkit for R, built on Stan.

dsambayesplus 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 provides retained-unit level fitted values and prediction after MCMC, but it remains restricted to its declared Gaussian panel contract.

The docs describe 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 dsambayesplus 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.0.1

  • 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, within-contrast diagnostics, conditional retained-unit intercept reconstruction, level fitted(), observed(), and retained-unit predict(). FE supports YAML runner validation, dry-run, and bounded MCMC fitting with a dedicated coefficient, sampler, within-design, contrast-residual, contrast posterior-predictive, and original-row conditional level-diagnostic artefact set. It can also run scoped seen-unit expanding-window validation with fold-local conditional intercept means; this is not PSIS model selection. 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, unseen-unit prediction, generic residual diagnostics, PSIS 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.enabled: true is rejected because the runner has no forecast-output contract. Runner decomposition artefacts are linear term-contribution summaries and fail closed for hierarchical, offset-bearing, and probabilistic-media-transform models.

Changes in 1.0.1

  • Editable diagnostic gates define warning and failure thresholds, including VIF, and produce detailed terminal reports.
  • Panel design diagnostics check same-date geographic variation and conditional support before fitting. Low variation warns; rank deficiency in the actual linear design stops the runner.
  • No-intercept models preserve their through-origin specification under scaling. Refit earlier affected models before interpreting their estimates.
  • LOO/WAIC use the unstandardised model-response density scale. Regenerate older score exports; comparison requires matching responses and observation sets.
  • Runner schema 4 distinguishes conditional-mean intervals from posterior predictive intervals. The predictive inclusion field is now posterior_predictive_coverage_95, replacing pi95_coverage.
  • Validation runs locally and manually; GitHub Actions is disabled.

These changes do not qualify an estimator for production or establish causal identification. The 1.0.0 provenance and estimator boundaries remain documented below.

Included in 1.0.0

Version 1.0.0 includes the bounded fixed_effects() API, including conditional retained-unit intercept reconstruction and direct level-scale fitted(), observed(), and predict() output after MCMC. The YAML runner retains its dedicated FE artefact contract and does not write generic level-scale or decision-layer outputs. FE remains unqualified. See Estimator Capabilities for the exact execution boundary and separately gated repeated-sampling qualification work.

The inherited DSAMbayes v1.3.4 candidate 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/ and optimisation uses 80_optimisation/; forecasting is rejected until it has a real output contract.
  • Native decomposition: the external DSAMdecomp and teller path has been removed; unsupported decomposition paths fail closed.

Estimator-wide qualification is post-release work. An implemented capability is not a production qualification.

Authorship

Current authorship as declared in DESCRIPTION:

  • Jamie Owen — author and creator
  • Charles Shaw — author
  • Nikoleta Nikitova, Nathan Wilby, Asher Moses, and Saskia Jennings — contributors