Install and Setup

Audience

Engineers and analysts setting up DSAMbayes for local development or modelling runs. This page is written for a Unix shell (Linux or macOS). If you are on Windows using RStudio, especially on a work-issued machine without full administrator rights, use Install and Setup (Windows / RStudio) instead.

Prerequisites

• R >= 4.1: check with R --version.
• A C++ toolchain for Stan compilation. This is the most common source of setup issues:
  • macOS: install Xcode Command Line Tools (xcode-select --install).
  • Windows: install Rtools matching your R version. Ensure make is on your PATH.
  • Linux (Ubuntu/Debian): sudo apt install build-essential.
  • See the RStan Getting Started Guide for detailed platform instructions.
• A local checkout of this repository.

Quick setup (recommended)

Open a terminal in the repository root and run:

# 1. Select an ABI-safe host library and create it with the cache
source scripts/r-library-path.sh
dsambayes_set_r_library host
mkdir -p "$R_LIBS_USER" .cache

# 2. Set the cache path (add both settings to .bashrc/.zshrc for persistence)
export XDG_CACHE_HOME="$PWD/.cache"

# 3. Install DSAMbayes from the local checkout
R -q -e 'install.packages(".", repos = NULL, type = "source")'

This keeps all package libraries and Stan compilation caches inside the repo, avoiding permission issues with system library paths.

Do not share a compiled package library between R runtimes or containers. dsambayes_set_r_library host selects .Rlib-host-r<active-R-version>/; use dsambayes_set_r_library container inside a container instead. The path is deliberately derived from the active runtime, not hard-coded in the repository.

Verify the installation

1. Confirm DSAMbayes loads

R -q -e 'library(DSAMbayes); cat("Version:", as.character(utils::packageVersion("DSAMbayes")), "\n")'

Expected: prints the installed package version.

2. Confirm the runner works

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

Expected: validation completes without errors.

3. (Optional) Run the test suite

R -q -e 'testthat::test_dir("tests/testthat")'

Expected: all tests pass.

Alternative: install the private fork from GitHub

If you need only the package API and have read access to the private canonical repository, install it directly:

R -q -e 'remotes::install_github("tandpds/DSAMbayes-Charles-Dev", dependencies = NA, upgrade = "never")'

This installs the current package version from main. remotes reads GITHUB_PAT from the environment for private-repository access. Keep the token in your user environment or credential manager, never in a command, script, or tracked file. Clone the repository instead when you need its example configs, data, runme.R, or development tooling.

Using renv (optional)

The repository includes a renv.lock file for fully reproducible dependency management. To use it:

R -q -e 'install.packages("renv"); renv::restore()'

This installs the exact dependency versions used during development. It is optional but recommended for production runs where reproducibility matters.

Runner setup and first execution

1. Validate the example config

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

2. Execute a full run

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

Expected: a timestamped run directory is created under results/ with model outputs and diagnostics.

Troubleshooting

Stan compilation fails

Symptom: errors during Compiling model... referencing C++ or compiler issues.

Actions:

1. Confirm your C++ toolchain is working: R -q -e 'pkgbuild::has_build_tools(debug = TRUE)'.
2. On Windows, ensure Rtools is installed and make is on your PATH.
3. Clear the Stan cache and retry: rm -rf .cache/dsambayes.
4. Follow the RStan Getting Started Guide for your platform.

Package installation fails

Symptom: install.packages(".", repos = NULL, type = "source") errors.

Actions:

1. Confirm you are in the repository root directory.
2. Confirm the selected R_LIBS_USER directory exists and is writable.
3. Check for missing system dependencies in the error output.

Stale Stan cache

Symptom: unexpected model behaviour after updating the package.

Actions:

1. Clear the cache: rm -rf .cache/dsambayes.
2. Re-run with model.force_recompile: true in your config if you need to invalidate a stale compiled model.

Permission issues

Symptom: write failures for library, cache, or run outputs.

Actions:

1. Ensure R_LIBS_USER, .cache, and results/ are writable.
2. Keep R_LIBS_USER and XDG_CACHE_HOME set in your shell session.
3. Run all commands from the repository root.

Related pages

• Install and Setup (Windows / RStudio), setup guidance for admin-restricted Windows machines
• Quickstart (YAML Runner), first end-to-end run
• FAQ, short practical answers

Concepts

Purpose

Give new DSAMbayes users a compact conceptual orientation before they move into tutorials, runner usage, or the workflow section.

This page is intentionally introductory. It does not try to be the full methodology guide for Bayesian MMM. For that, use Principled Bayesian Workflow.

What is DSAMbayes?

DSAMbayes is an R package for Bayesian marketing mix modelling built on Stan. It provides:

• an lm()-style modelling interface for interactive work
• model classes for single-series, hierarchical, and pooled MMM
• prior and boundary controls
• post-fit extraction, diagnostics, decomposition, and optimisation tooling
• a YAML/CLI runner for reproducible runs

The main practical difference from classical regression is that DSAMbayes works with a posterior distribution, not just a single fitted coefficient vector.

Why Bayesian MMM?

MMM datasets often have the exact features that make naive regression unstable:

• short time series
• overlapping media timing
• strong baseline structure
• uncertain functional form
• real business need for uncertainty-aware decisions

Bayesian modelling helps because it makes several things explicit:

• regularisation through priors
• structural constraints through boundaries
• uncertainty propagation into downstream outputs
• diagnostic gates rather than fit-statistic-only thinking

The DSAMbayes mental model

DSAMbayes should be thought of as a workflow, not just a fitter.

At a high level:

1. specify the model and priors
2. fit the model
3. check whether the posterior computation is trustworthy
4. check whether the fitted model is adequate for the data
5. only then interpret decomposition, comparison, or optimisation outputs

That is the main philosophical shift from a simpler OLS-style workflow.

Model classes

DSAMbayes supports three main model classes.

BLM

Single-market Bayesian linear model.

Use when:

• you have one KPI series
• one market / brand / region is the modelling unit
• you want the simplest Bayesian MMM starting point

Hierarchical

Multi-group model with partial pooling.

Use when:

• you have panel data across markets, regions, or brands
• you want to borrow strength across groups while preserving group structure

Pooled

Single-market model with structured pooling across labelled media dimensions.

Use when:

• the outcome is one series
• the media structure has nested or repeated dimensions that should share information

For the detailed class contract, see Model Classes.

Interactive API vs runner

DSAMbayes has two main ways of working:

Interactive R API

Best when you want to prototype directly in R:

• blm()
• set_prior()
• set_boundary()
• fit()
• get_posterior()

YAML / CLI runner

Best when you want reproducibility and staged artefacts:

• validate
• run
• staged outputs under results/

See Quickstart and Runner.

What this page does not try to teach

This page does not try to fully answer:

• how to choose priors
• which diagnostics matter most
• when business interpretation is allowed

Those are workflow questions, and they are handled in the dedicated methodology pages:

• What Principled Means
• Frequentist to Bayesian Translation
• Stage 2: Model and Priors
• Stage 4: Computation and Sampler
• Stage 5: Model Adequacy

Recommended next steps

• Quickstart to run the tool
• Your First BLM Model for the interactive API
• Principled Bayesian Workflow for the methodological spine

Your First BLM Model

Goal

Build, fit, and interpret a single-market Bayesian linear model (BLM) using the DSAMbayes R API.

This page is a hands-on tutorial. For the broader methodological questions behind prior-setting and diagnostics, use the workflow pages:

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

Prerequisites

• DSAMbayes installed locally (see Install and Setup).
• Familiarity with R and lm()-style formulas.

Dataset

This walkthrough uses the tracked synthetic dataset at data/timeseries/demo_data_synthetic.csv. It contains weekly observations for a single series with columns for:

• Response: revenue, weekly synthetic KPI.
• Media: channel0_spend, channel1_spend, channel2_spend, channel3_spend.
• Controls: events, newsletters.
• Date: time, weekly date index.

library(DSAMbayes)
df <- read.csv("data/timeseries/demo_data_synthetic.csv")
str(df)

Step 1: Construct the model

blm() creates an unfitted model object. No fitting happens yet.

model <- blm(
  revenue ~
    events + newsletters +
    channel0_spend + channel1_spend + channel2_spend + channel3_spend,
  data = df
) %>%
  set_date(time)

Inspect defaults:

peek_prior(model)      # data-dependent normal priors: normal(ybar, sy) intercept, normal(0, sy / sx) per slope
peek_boundary(model)   # (-Inf, Inf), unconstrained

Step 2: Set boundaries

Media channels should have non-negative effects. Use inequality notation:

model <- model %>%
  set_boundary(
    channel0_spend > 0, channel1_spend > 0,
    channel2_spend > 0, channel3_spend > 0
  )

Step 3: (Optional) Override priors

Default priors are weakly informative. Override only with domain knowledge:

model <- model %>%
  set_prior(events ~ normal(0, 1))

See Stage 2: Model and Priors and Minimal-Prior Policy for guidance.

Step 4: Fit with MCMC

fitted_model <- model %>%
  fit(cores = 2, iter = 2000, warmup = 1000, seed = 123)

First-time Stan compilation takes 1–3 minutes. Subsequent runs use a cached binary. With the default 4 chains split across 2 cores, sampling on synthetic data typically completes in under 2 minutes.

Step 5: Sampler diagnostics

chain_diagnostics(fitted_model)

These are the computational checks. They do not by themselves prove the model is adequate for interpretation.

Step 6: Extract the posterior

post <- get_posterior(fitted_model)

post is a tibble with one row per draw containing coef (named coefficient list), yhat (fitted values), noise_sd, r2, rmse, and smape.

Summarise coefficients:

library(dplyr); library(tidyr)

coef_summary <- post %>%
  select(coef) %>%
  unnest_wider(coef) %>%
  pivot_longer(everything(), names_to = "term") %>%
  group_by(term) %>%
  summarise(
    mean = mean(value), median = median(value), sd = sd(value),
    ci_low = quantile(value, 0.025), ci_high = quantile(value, 0.975),
    .groups = "drop"
  )
print(coef_summary, n = 30)

What to look for:

• Media coefficients should be positive (boundaries enforce this).
• Wide credible intervals mean the prior dominates, the data cannot identify the effect precisely.

Step 7: Assess model fit

fit_tbl <- fitted(fitted_model)
cat("Median R²:", median(r2(fitted_model)), "\n")
cat("Median RMSE:", median(rmse(fitted_model)), "\n")

For a well-specified MMM on weekly data, in-sample R² above 0.85 is typical.

Step 8: Response decomposition

tbl_map <- data.frame(
  actual.vars = c(
    "intercept", "events", "newsletters",
    "channel0_spend", "channel1_spend", "channel2_spend", "channel3_spend"
  ),
  group = c(rep("BASE", 3), rep("media", 4)),
  ref_points = c("none", rep("mean", 6))
)
decomp_result <- decomp(fitted_model, tbl_map = tbl_map)
head(decomp_result$DecompedData)

$DecompedData shows each term’s contribution (coefficient × design-matrix column) to the predicted KPI at each time point. The result is a native dsambayes_decomposition S3 object.

Step 9: MAP for rapid iteration

During development, use MAP for fast point estimates:

map_model <- model %>% fit_map(n_runs = 10)
get_posterior(map_model)

Use MCMC for final reporting; MAP for formula iteration. A MAP result is one point estimate, not posterior draws: it has no valid credible intervals or MCMC diagnostics. Review the restart diagnostics if objectives differ materially; use fit() when uncertainty, convergence, or decision risk matters.

Common pitfalls

Next steps

• Run via YAML for reproducible runs: Run from YAML
• Interpret diagnostics: Interpret Diagnostics
• Workflow meaning of priors and diagnostics: Principled Bayesian Workflow
• Budget optimisation: Budget Optimisation
• Multi-market models: Your First Hierarchical Model

Your First Hierarchical Model

Goal

Build, fit, and interpret a multi-market hierarchical model with partial pooling and optional CRE (Mundlak) correction using the DSAMbayes R API.

This page is a hands-on tutorial. For the broader methodological questions behind prior-setting, diagnostics, and interpretation, use the workflow pages:

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

Prerequisites

• DSAMbayes installed locally (see Install and Setup).
• Familiarity with the BLM workflow (see Your First BLM Model).
• Understanding of random-effects / mixed-model concepts.

Dataset

This walkthrough uses the tracked data/geo_panel/demo_data_geo_panel.csv , a panel dataset with weekly observations across multiple geos. Key columns:

• Response: revenue, weekly synthetic KPI per geo.
• Group: geo, geo identifier.
• Media: channel0_signal, channel1_signal, channel2_signal, channel3_signal.
• Controls: t_scaled, sin52_1, cos52_1, events, newsletters.
• Date: date, weekly date index.

library(DSAMbayes)
panel_df <- read.csv("data/geo_panel/demo_data_geo_panel.csv")
table(panel_df$geo)  # Check group counts

Step 1: Construct the hierarchical model

The (term | group) syntax tells DSAMbayes to fit random effects. Terms inside the parentheses get group-specific deviations from the population mean:

model <- blm(
  revenue ~
    t_scaled + sin52_1 + cos52_1 + events + newsletters +
    channel0_signal + channel1_signal + channel2_signal + channel3_signal +
    (1 + channel0_signal + channel1_signal + channel2_signal + channel3_signal | geo),
  data = panel_df
)

This specifies:

• Population (fixed) effects for all terms, the average effect across markets.
• Random intercepts and slopes for media terms by market, each market can deviate from the population average.

Step 2: Set boundaries

model <- model %>%
  set_boundary(
    channel0_signal > 0, channel1_signal > 0,
    channel2_signal > 0, channel3_signal > 0
  )

Boundaries apply to the population-level coefficients.

Step 3: (Optional) Add CRE / Mundlak correction

If you suspect that group-level spending patterns are correlated with unobserved market characteristics (e.g. high-spend markets also have higher baseline demand), CRE can model this correlation when the conditional mean of the group effect is adequately represented by the included group means:

model <- model %>%
  set_cre(vars = c(
    "channel0_signal", "channel1_signal",
    "channel2_signal", "channel3_signal"
  ))

This adds one cre_mean_<channel> term for each media variable as a fixed effect. Conditional on the CRE specification and other included controls, the original media coefficient represents the within-group temporal association. CRE does not solve omitted time-varying confounding or establish a causal effect.

See CRE / Mundlak for when and why to use this.

Step 4: Fit with MCMC

fitted_model <- model %>%
  fit(cores = 4, iter = 2000, warmup = 1000, seed = 42)

Hierarchical models are slower than BLM, expect 10–30 minutes depending on group count and data size. First-time Stan compilation of the hierarchical template adds 2–3 minutes.

Step 5: Check diagnostics

chain_diagnostics(fitted_model)

Pay special attention to Rhat and ESS for sd_* parameters (group-level standard deviations), which are often harder to estimate than population coefficients.

Step 6: Extract the posterior

post <- get_posterior(fitted_model)

For hierarchical models, coefficient draws from get_posterior() return vectors (one value per group) rather than scalars. The population-level (fixed-effect) estimates are averaged across groups.

Step 7: Group-level results

Fitted values and decomposition are returned per group:

# Fitted values, one row per observation, grouped by geo
fit_tbl <- fitted(fitted_model)
head(fit_tbl)

# Decomposition, per-group predictor contributions
tbl_map <- data.frame(
  actual.vars = c(
    "intercept", "t_scaled", "sin52_1", "cos52_1", "events", "newsletters",
    "cre_mean_channel0_signal", "cre_mean_channel1_signal",
    "cre_mean_channel2_signal", "cre_mean_channel3_signal",
    "channel0_signal", "channel1_signal", "channel2_signal", "channel3_signal"
  ),
  group = c(rep("BASE", 10), rep("media", 4)),
  ref_points = c("none", rep("mean", 13))
)
decomp_result <- decomp(fitted_model, tbl_map = tbl_map)
# One native decomposition result per retained group:
head(decomp_result$decomp[[1]]$DecompedData)

Step 8: Budget optimisation (population level)

Budget optimisation uses population-level (fixed-effect) beta draws, not group-specific totals:

# See Budget Optimisation docs for full scenario specification
result <- optimise_budget(fitted_model, scenario = my_scenario)

Key differences from BLM

Common pitfalls

Next steps

• CRE / Mundlak, full CRE documentation
• Model Classes, detailed class comparison
• Diagnostics Gates, hierarchical-specific checks (within-variation)
• Principled Bayesian Workflow, methodology spine for interpretation and decision gates
• Run from YAML, reproducible hierarchical runs via the runner

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

Complete the environment setup in Install and Setup (selecting the host library, creating the cache directory, and exporting XDG_CACHE_HOME) before continuing.

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

FAQ

This page is for short, practical answers.

For the bigger methodological questions, start with:

• What Principled Means
• Frequentist to Bayesian Translation
• Stage 2: Model and Priors
• Stage 4: Computation and Sampler
• Stage 5: Model Adequacy

Installation and setup

How long does the first Stan compilation take?

Usually 1 to 3 minutes. Subsequent runs typically reuse the cached binary. If compilation appears stuck, check the C++ toolchain in Install and Setup.

Do I need to set R_LIBS_USER every time?

Yes, unless you add it to your shell profile. Use dsambayes_set_r_library host to select a repo-local path that is isolated from both your system library and any container library.

Can I use renv instead of .Rlib?

Yes. The repo includes renv.lock. Use renv::restore() if you want exact dependency restoration.

Modelling

How many weeks of data do I need?

There is no hard minimum, but a useful rule of thumb is:

• BLM: about 100+ weeks for a model with roughly 10 to 15 predictors
• Hierarchical: about 80+ weeks per group, ideally with at least 4 groups

Shorter series can still be modelled, but the posterior will usually be much more prior-driven and less decision-ready.

Should I use identity or log response?

• Identity when the KPI is naturally additive and variance is fairly stable
• Log when the KPI is strictly positive and effect interpretation is more naturally multiplicative

If unsure, fit both and compare the adequacy and diagnostic picture, not just a single fit metric. See Response Scale Semantics.

How should I think about priors?

Start with Stage 2: Model and Priors.

The short answer is:

• start with defaults
• add sparse sign constraints only for structural assumptions
• add sparse prior overrides only when you can defend them in business or modelling terms
• do not use priors as a substitute for weak model design

Where do prior numbers come from, and why aren’t they standardised like some other MMM tools?

Short answer: in DSAMbayes, you write priors in the original units of your data, for example revenue, not in a standardised or z-score space. This is a deliberate design choice, not a mistake, and it differs from some other MMM tools, including Abacus, which ask you to specify priors directly in their internal standardised space.

What “standardised space” means

Before Stan samples, most Bayesian MMM tools, DSAMbayes included, centre and scale the response and predictors so the sampler works with unit-scale quantities. This is a computational convenience: it improves sampler efficiency and keeps step sizes well behaved across parameters with very different natural magnitudes (e.g. revenue in the hundreds of thousands versus a spend variable in the low thousands).

Where tools differ is which layer of that process they ask the user to think in.

• Abacus-style: you write the prior directly on the standardised space. A config entry such as intercept: Normal(mu = 0, sigma = 2) is only interpretable because Abacus has already decided how the target is scaled; the 2 is “2 standard deviations of the standardised target”, not “2 units of revenue”.
• DSAMbayes: you write the prior on the original, reporting-scale units of your data. intercept: Normal(mu = 120000, sigma = 15000) means “baseline revenue is around 120,000, plus or minus roughly 15,000”, in whatever currency or unit your target column uses. When model.scale: true (the default), DSAMbayes converts this raw-scale prior into the correct standardised parameterisation internally, fits, and then back-transforms the posterior draws to your original units automatically. You never see or touch the standardised numbers unless you set model.scale: false.

Both approaches produce equivalent underlying sampler behaviour. Neither is “unscaled” in the sense of skipping standardisation; DSAMbayes just does not require you to author priors in the post-scaling space.

Why DSAMbayes uses the reporting scale for the prior contract

1. The numbers stay checkable by a non-modeller. A stakeholder, or a colleague reviewing your config, can look at mu = 120000, sigma = 15000 and immediately judge whether that is a sane assumption about baseline revenue. Nobody outside the modelling team can sanity-check Normal(0, 2) on a standardised scale without first recomputing what that implies in revenue terms.
2. The prior’s meaning does not silently drift between runs. A standardised-space prior such as Normal(0, 2) means something different each time you refit, because the underlying standard deviation used to derive that scale changes with the data (different date range, different market, a new data pull). A reporting-scale prior such as Normal(120000, 15000) means the same thing, “baseline revenue is about 120k”, regardless of what the data’s standard deviation happens to be on any given run. This avoids a common failure mode where a prior that looked reasonable on one dataset becomes accidentally very informative, or accidentally very diffuse, on the next.
3. It matches how priors are usually elicited in practice. Domain knowledge about a KPI baseline, a channel’s plausible ROI, or a competitor effect is almost always expressed in business units. Asking the analyst to translate that into a standardised space by hand is an extra, error-prone step that this design avoids.

This is consistent with standard Bayesian workflow guidance (see What Principled Means and Stage 2: Model and Priors): elicit priors where you have real, defensible intuition, and let the software handle re-parameterisation for computation.

What actually happens under the hood

DSAMbayes’s internal scaling of priors and boundaries, including the exact transformation ratios for slopes, the intercept, and hierarchical group-level standard deviations, is fully documented in Priors and Boundaries under “Scale semantics”. That page is the technical reference; this FAQ entry is only the “why”.

How to sanity-check a prior you have written

• Reason about it directly in your data’s natural units; that is what the YAML priors: block and set_prior() both expect.
• Use peek_prior(model) to see the full prior table on the reporting scale before fitting.
• If you want to see the internal standardised-space numbers DSAMbayes actually passes to Stan, set model.scale: false on an otherwise identical model and compare, or inspect the scaling terms directly; this is rarely necessary for day-to-day modelling.
• Do not manually convert your prior into a standardised space and enter that instead. That would be double-scaling and will produce the wrong prior.

See also Minimal-Prior Policy for the recommended default-first, sparse-override operating rule that this scaling behaviour is designed to support.

How many MCMC iterations do I need?

The defaults are a reasonable starting point. Then inspect the Stage 4 diagnostics:

• Rhat <= 1.01 and healthy ESS usually mean the draw count is adequate
• Rhat > 1.01 or weak ESS usually means you need to increase iterations and warmup
• any divergences should be addressed before treating the fit as decision-ready

See Stage 4: Computation and Sampler.

How strict is the stationarity requirement for MMM?

DSAMbayes does not require the raw KPI to satisfy a textbook stationarity condition before fitting.

The important question is whether the remaining unexplained structure, after adding sensible controls and baseline terms, is weak enough that media effects are not standing in for missing baseline dynamics.

When should I set boundaries on media coefficients?

Use m_channel > 0 when non-negativity is a structural belief you would defend in writing. Do not apply blanket sign constraints just to make the output look tidier. See Stage 2: Model and Priors and Minimal-Prior Policy.

When should I use CRE (Mundlak)?

Use CRE when you want to separate within-group temporal effects from between-group cross-sectional structure in a hierarchical model. See CRE / Mundlak.

How should I handle CRE mean terms in decomposition / attribution?

Treat cre_mean_* terms as baseline or between-group structure, not as media attribution terms. They are there to absorb confounding structure, not to claim channel contribution.

What priors should I use on CRE mean terms?

Usually the defaults. Avoid manually tightening or positivity-constraining them unless you have a very strong reason, because that can undermine the whole point of CRE adjustment.

Can I add random slopes for CRE mean terms?

No. Those terms are constant within group, so random slopes on them are not separately identifiable from the group intercept.

What does scale = TRUE do?

It standardises the response and predictors before Stan fitting to improve sampler efficiency. Post-fit coefficient extraction is back-transformed automatically.

Runner and outputs

How long does a typical run take?

Roughly:

• BLM MCMC: a few minutes
• BLM MAP: seconds
• Hierarchical MCMC: tens of minutes depending on size
• Pooled MCMC: usually between BLM and hierarchical

First-time Stan compilation adds extra startup time.

What is the difference between validate and run?

• validate checks config and data contracts without compiling or fitting Stan
• run validates, fits, writes staged artefacts, and runs diagnostics

Always validate first after config changes.

Where do outputs go?

Under results/<timestamp>_<model_name>/ by default. See Output Artefacts.

How do I compare two model runs?

Use compare_runs() or compare the model-selection artefacts directly. See Compare Runs.

Diagnostics

Which diagnostics matter most?

Read them in order:

1. Stage 4: Computation and Sampler
2. Stage 5: Model Adequacy

That is more important than memorising one threshold in isolation.

What does “Pareto-k > 0.7” mean?

It means the LOO approximation is unreliable for that observation and the point is highly influential. Investigate the observation and be cautious about using LOO-based comparisons mechanically.

My diagnostics say warn. Should I worry?

Usually yes, but not always in the same way.

• in exploratory work, a warning may be acceptable if understood
• in shareable reporting, warnings should be disclosed and interpreted
• repeated or severe warnings usually mean the model needs revision before decision use

Use Interpret Diagnostics for triage and the workflow pages for meaning.

Budget optimisation

How does the allocator work?

It searches feasible spend allocations within channel constraints and scores them against the fitted model. It is a decision layer built on the model, not an independent source of truth.

Can I use budget optimisation with MAP-fitted models?

Yes, but then the result is point-estimate-driven rather than uncertainty-rich. That is fine for rough iteration, not ideal for final decision support.

What Principled Means

Objective

Define what DSAMbayes means by a principled Bayesian MMM workflow.

The term is intentionally about process, not brand loyalty to a particular model class or sampler. A principled workflow is one where assumptions are explicit, diagnostics are stage-gated, and downstream interpretation is conditioned on those gates.

The short definition

A DSAMbayes workflow is principled when it does all of the following:

1. states a clear modelling objective and decision context
2. specifies an explicit model with explicit priors and boundaries
3. checks whether the posterior computation is trustworthy
4. checks whether the fitted model is adequate for the data
5. carries uncertainty and gate status into decomposition, optimisation, and reporting

If any one of those steps is skipped, the workflow becomes less defensible even if the final coefficients look plausible.

Workflow contract at a glance

The key design choice in DSAMbayes is that downstream outputs are conditional on upstream gates. A model that fits is not automatically a model that should be decomposed, compared, optimised, or deployed.

Four commitments

1. Generative transparency

The model should tell a clear story about how the outcome is generated from:

• media terms
• baseline structure
• controls
• observation noise

That is why DSAMbayes exposes priors, boundaries, response scale, CRE terms, time components, and model classes explicitly. The point is not to burden users with knobs; it is to make assumptions inspectable.

2. Stage-gated inference

The workflow should move in order:

1. question and data design
2. model and priors
3. fit
4. computational diagnostics
5. model adequacy checks
6. interpretation and decision support

Downstream outputs should only be trusted if the upstream gates have been checked.

3. Diagnostic sufficiency for computation, not causality

Diagnostics answer questions like:

• did the sampler converge?
• are the posterior draws stable?
• does the fitted model describe the observed data credibly?

Diagnostics do not answer:

• did the model identify the true causal effect of media?
• did we control for every relevant confounder?
• is the chosen baseline structure the only defensible one?

This distinction is essential in MMM.

4. Decision-linked reporting

Decomposition shares, response curves, deployment artifacts, and budget recommendations should be treated as functions of the gated fit, not as standalone truths. If the fit has warnings or failures, those limitations must travel with the result.

The three layers of trust

DSAMbayes users should separate three different questions:

Passing the first layer does not imply the second. Passing the second does not imply the third.

How DSAMbayes supports this workflow

DSAMbayes already provides several pieces of the workflow contract:

• explicit model classes and response-scale semantics
• default priors plus selective overrides and hard boundaries
• pre-flight design checks
• post-fit diagnostics with pass / warn / fail statuses
• staged runner artifacts under results/
• model comparison and optional time-series selection tooling
• decision-layer optimisation with uncertainty-aware summaries

What the package cannot do automatically is replace analyst judgment about:

• business estimands
• causal assumptions
• whether a structural prior is genuinely defensible
• whether a warned run is acceptable for the specific business use

Failure policy in plain language

If Stage 4 fails

Do not trust decomposition, response curves, or optimisation outputs. The posterior sample itself is numerically unreliable.

If Stage 5 fails

The sampler may have worked, but the model is not yet adequate for business interpretation. Use the run for diagnosis, not for stakeholder recommendations.

If causal assumptions are weak

Even a clean computational and adequacy profile may still only support associational interpretation. Report it that way.

Related pages

• Frequentist to Bayesian Translation
• Stage 2: Model and Priors
• Stage 4: Computation and Sampler
• Stage 5: Model Adequacy

Frequentist to Bayesian Translation

Objective

Translate familiar classical regression instincts into the DSAMbayes workflow so users coming from OLS, GLM, or general frequentist econometrics can adopt Bayesian MMM without losing methodological discipline.

What does not change

Moving to DSAMbayes does not remove the need for:

• careful data definition
• sensible controls
• thinking about omitted variables
• residual scrutiny
• skepticism about causal claims

Bayesian MMM is not a shortcut around model design. It is a different way of expressing assumptions and uncertainty.

What changes

1. From one best coefficient to a posterior distribution

In OLS, the default object of interest is a point estimate plus a standard error. In DSAMbayes, the default object is a posterior distribution. That means:

• coefficients are uncertain objects, not fixed truths
• decomposition and optimisation should inherit that uncertainty
• wide intervals are information, not a nuisance to hide

2. From “no prior” to “explicit prior assumptions”

Frequentist workflows often treat themselves as prior-free. In practice, they still encode structure through model choice, variable transformations, and constraints.

DSAMbayes makes that structure explicit:

• default priors express mild regularisation
• boundaries express structural sign assumptions
• overrides should be sparse and justified

3. From significance-thinking to decision-thinking

The key question becomes less “is beta significantly different from zero?” and more:

• is the posterior sufficiently stable?
• is the model adequate?
• is the interval narrow enough for the business decision?
• what risks remain if we act on this estimate?

Quick translation table

The priors question in frequentist language

The question “where do priors come from?” is often really one of these:

1. What assumptions am I already making implicitly?
2. Which assumptions deserve to be encoded explicitly?
3. Where do I have stable directional knowledge versus weak intuition?

For DSAMbayes, the practical default is:

• start with package defaults
• add boundaries only for structural signs you would defend in writing
• add sparse prior overrides only for high-conviction terms
• do not use priors to force a preferred answer out of weak data

See Stage 2: Model and Priors.

The diagnostics question in frequentist language

The question “which diagnostics matter?” is best answered in order:

1. Are the posterior draws numerically trustworthy?
2. Does the model fit the data adequately?
3. Are the business conclusions robust to what remains uncertain?

This translates into:

• Stage 4: Rhat, ESS, divergences, treedepth, BFMI
• Stage 5: fit plots, residual behaviour, PPC, LOO/Pareto-k

See Stage 4: Computation and Sampler and Stage 5: Model Adequacy.

Common transition mistakes

Mistake 1: treating defaults as magic

Default priors are a sensible starting point, not proof that prior design is solved forever.

Mistake 2: using priors as a repair tool for poor design

If media terms are badly collinear with baseline structure or controls are missing, stronger priors may stabilise numerics without fixing the underlying modelling problem.

Mistake 3: treating warning-level diagnostics as a cosmetic issue

A warned run may still be usable, but only if the warning is understood and disclosed. The right response is not “the model ran, so ship it.”

Mistake 4: confusing predictive success with causal proof

A model can rank well by ELPD and still be causally fragile.

Practical recommendation

If you are used to classical MMM, use DSAMbayes in this order:

1. run Quickstart to learn the tool surface
2. read What Principled Means
3. use Stage 2: Model and Priors before customising priors
4. use Stage 4: Computation and Sampler and Stage 5: Model Adequacy before interpreting any decision-layer output

Stage 2: Model and Priors

Objective

Specify a model that is explicit enough to be audited and simple enough to be defended.

For most DSAMbayes users, this stage is where the biggest conceptual shift happens. In classical MMM, the common instinct is to choose variables, run the regression, and worry about coefficient stability afterwards. In DSAMbayes, priors and boundaries are part of the specification from the start.

The operating rule

Use a default-first workflow unless there is a strong reason not to.

That means:

1. start with the package defaults
2. add sparse sign constraints only where the business logic is structural
3. add sparse prior overrides only where the prior story is stable and defensible
4. fit the model
5. inspect whether the posterior is still dominated by weak design rather than by a sensible prior choice

This is the same operating stance documented in Minimal-Prior Policy, but framed here as part of the modelling workflow rather than as a standalone policy page.

Prior specification pathways

This is the short answer to “where should priors come from?” Defaults are the starting point. Boundaries and overrides are additive, sparse, and justified by business or structural reasoning. The blm(lm_object, data) path is the empirical-Bayes-like option when a credible legacy model already exists.

Where priors should come from

In DSAMbayes, priors should usually come from one of four sources.

1. Structural sign knowledge

Examples:

• additional media exposure should not reduce KPI
• competitor discount should not increase our sales

This is usually best expressed as a boundary, not as an aggressive mean-shifting prior.

2. Stable business knowledge about magnitude

Examples:

• price elasticity is probably negative and modest
• distribution is probably positive and not enormous

This is where a sparse override like normal(-0.2, 0.1) may be justified.

3. Historical learning from previous analyses

If the same brand, market, or response has been analysed repeatedly under a similar data-generating regime, you may have enough evidence to justify informative priors on a small number of terms.

4. Explicit regularisation when the data are weak

Sometimes priors are primarily there to stabilise a short, collinear MMM. That is acceptable, but it should be acknowledged honestly as regularisation rather than presented as deep subject-matter certainty.

Where priors should not come from

Do not set priors mainly because:

• one previous run looked better with them
• they remove a warning without improving model design
• they force a preferred channel ranking
• they make weak data look more certain than it really is

That is specification-hunting, not principled prior design.

Practical DSAMbayes policy

Step 1: start with defaults

For most first-pass BLM and hierarchical work, the package defaults are the right starting point.

• default coefficient priors are weakly informative
• default boundaries are unconstrained
• you should not feel obliged to invent bespoke priors on every term

Step 2: add selective boundaries

Use set_boundary() or YAML boundaries.overrides when the sign is structural and defensible.

Good examples:

• media terms constrained positive
• competitor discount constrained non-positive

Poor examples:

• constraining every control just to reduce posterior variance
• forcing signs on variables whose mechanism is genuinely ambiguous

Step 3: add sparse prior overrides only where conviction is real

Typical candidates:

• price
• distribution
• a small number of strategically important baseline controls

Typical non-candidates:

• every media term
• every generated seasonal component
• every term simply because the data are noisy

Step 4: keep the reasoning on the original outcome scale

DSAMbayes can scale internally when scale = TRUE, but your reasoning about priors should still happen on the original business scale. Ask:

• what outcome change would this prior imply?
• would that be plausible for this KPI?
• would I be comfortable defending it in a model review?

Prior predictive discipline in DSAMbayes

The Bayesian workflow ideal is to inspect prior implications before posterior fitting. In practical DSAMbayes use today, that discipline is still partly analyst-driven.

v1.3.3 does not yet provide a fully productised, first-class prior-predictive runner stage with its own public gate contract. So the current disciplined approach is:

1. keep the prior design simple
2. reason on the original outcome scale
3. avoid over-confident overrides unless they are well supported
4. fit the model and then inspect whether the posterior behaviour is compatible with the prior story and the data

That makes the lack of a first-class prior-predictive stage a reason to be more conservative, not less.

Prior calibration and sensitivity loop

For DSAMbayes users, a prior grid is a robustness tool, not a scoring contest. Use it to check whether the substantive conclusion survives plausible prior choices. Do not use it to hunt for the prior that makes one run look best.

How to know whether the priors are doing sensible work

After fitting, ask:

Are the intervals still wide?

If yes, the data may simply be weak. Do not respond automatically by tightening priors.

Are signs unstable without a clear design reason?

Check the baseline structure, controls, collinearity, and response-scale choice before strengthening priors.

Are coefficients pinned to hard bounds?

That can indicate that the boundary is too strong, or that the model is trying to express a structure the current formula does not support well.

A simple prior-setting decision table

Cross-references

• Priors and Boundaries for the technical contract
• Minimal-Prior Policy for the concise governance rule set
• Your First BLM Model for concrete R API examples

Stage 4: Computation and Sampler

Objective

Decide whether the posterior draws are numerically trustworthy.

This stage is about computation quality, not business interpretation and not causal validity. If it fails, every downstream quantity that depends on posterior draws becomes unreliable.

The key question

Before asking whether the model is good, ask whether the sampler actually explored the posterior well enough for the summaries to mean what they appear to mean.

In DSAMbayes, this is the stage where you care most about:

• divergences
• Rhat
• effective sample size
• treedepth and BFMI when available

Recommended order of attention

1. Divergences

Any non-zero divergences should be treated seriously. They are often the strongest sign that the sampler struggled with posterior geometry.

Typical actions:

• increase adapt_delta
• simplify the model
• revisit boundaries or extreme prior choices
• inspect whether a hierarchical structure is too ambitious for the data

2. Rhat

Rhat answers: did the chains mix into the same posterior region?

Practical rule:

• at or below 1.01 is the target
• above 1.01 fails the publish and strict diagnostics policies

3. Effective sample size

ESS answers: how much independent information do the posterior summaries really contain after accounting for autocorrelation?

Low ESS means:

• interval estimates may be unstable
• tail probabilities may be noisy
• apparent posterior precision may be misleading

4. Treedepth and BFMI

These are geometry warnings. They often indicate a difficult posterior shape even when Rhat looks acceptable.

What DSAMbayes gives you

You can inspect this stage through:

• chain_diagnostics(model) for interactive fitted models
• 40_diagnostics/diagnostics_report.csv
• 40_diagnostics/diagnostics_summary.txt
• diagnostics plots and residual artifacts produced by the runner

The threshold reference lives in Diagnostics Gates. The task-oriented post-run triage guide lives in Interpret Diagnostics.

Minimal decision rule

What Stage 4 does not tell you

Passing Stage 4 does not mean:

• the model fits the data well
• the residual structure is acceptable
• the decomposition is substantively meaningful
• the media effects are causally identified

It only means the sampler did a credible job approximating the posterior of the model you gave it.

Common mistake

The most common analytical error is to stop at Stage 4 and say “the model converged, so we can trust the answer.”

That is wrong.

Convergence tells you the computation is trustworthy. It does not tell you the model is adequate. That is the next stage.

What to do if Stage 4 fails

Start with the least cosmetic explanation:

1. Is the model too complicated for the data?
2. Is the baseline structure poorly separated from media?
3. Are priors or boundaries too aggressive?
4. Are hierarchical or pooled structures under-informed?

Only after that should you reach for sampler tuning.

Related pages

• Stage 5: Model Adequacy
• Diagnostics Gates
• Interpret Diagnostics

Stage 5: Model Adequacy

Objective

Decide whether the fitted model is a credible description of the observed data.

This is the stage that sits between computational trust and business interpretation. A model can pass sampler diagnostics and still fail here.

The key question

If I simulate from the fitted model, does it reproduce the important structure of the observed data well enough for decomposition, comparison, and optimisation to be taken seriously?

What to inspect first

1. Fitted-versus-observed behaviour over time

Ask:

• does the model track the broad level and movement of the KPI?
• are there long runs of systematic over- or under-prediction?
• are key seasonal or event patterns still unexplained?

2. Posterior predictive checks

Posterior predictive plots tell you whether the fitted model can generate data that look like what you observed.

In DSAMbayes, this is the right way to think about the ppc.png artifact: not as decoration, but as an adequacy check.

3. Residual behaviour

Residual autocorrelation or visible structure usually means the model has not absorbed an important baseline, timing, or event component.

4. LOO and Pareto-k

Model comparison and calibration-style plots help answer:

• which candidate model predicts better?
• are some observations highly influential?
• is the leave-one-out approximation trustworthy?

These are useful, but they should not override a bad adequacy profile.

What this stage means for decisions

The main practical consequence of Stage 5 is that predictive ranking and downstream business outputs are conditional on adequacy. Passing computation checks is not enough if the fitted model still behaves poorly against the data.

If adequacy is poor

Do not interpret decomposition shares as if they were stable statements about media contribution.

Do not treat optimisation outputs as reliable budget guidance.

Use the run to diagnose misspecification, then revise the model.

If adequacy is acceptable but not clean

A warning-level result may still be useful for exploratory work, but the caveat should travel with the output.

Adequacy is not the same as causality

A model can:

• fit well
• calibrate well
• compare well by predictive metrics

and still produce biased media-effect interpretation if confounding or structural misspecification remains.

So Stage 5 is a gate on model adequacy, not proof of causal validity.

Practical DSAMbayes reading order

1. Check Stage 4 first: are the draws trustworthy?
2. Inspect fit plots and PPC
3. Inspect residual diagnostics
4. Inspect LOO / Pareto-k and compare candidate runs
5. Only then interpret decomposition or decision-layer outputs

Common failure patterns

Pattern 1: good convergence, bad residual structure

Interpretation: the sampler worked, but the baseline or control structure is incomplete.

Pattern 2: good fit plot, unstable influential observations

Interpretation: apparent adequacy may depend too heavily on a small number of points. Treat model comparison and downstream interpretation cautiously.

Pattern 3: good predictive fit, weak causal story

Interpretation: the model may be operationally useful for forecasting or scenario analysis, but not for strong causal claims about media.

Relevant DSAMbayes surfaces

• 40_diagnostics/diagnostics_report.csv
• 40_diagnostics/ppc.png
• residual plots in 40_diagnostics/
• 50_model_selection/pareto_k.png
• compare_runs()

Related pages

• Stage 4: Computation and Sampler
• Interpret Diagnostics
• Compare Runs
• Diagnostics Plots

CLI Usage

Purpose

Define the supported command-line interface for scripts/dsambayes.R, including required flags, optional flags, and execution semantics.

Prerequisites

Before using the CLI:

• Complete Install and Setup.
• Run commands from repository root.
• Ensure DSAMbayes is installed in the role-specific R_LIBS_USER selected by dsambayes_set_r_library host.

Entry point

Rscript scripts/dsambayes.R <command> [flags]

Operational commands construct the package-owned DSAMbayes::runner_cli_adapter() before reading configs, fitting models, or writing artefacts. The startup panel records both the loaded package version and the checkout version from DESCRIPTION. runme.R applies the same gate and records the versions as package_version and checkout_version.

The versions must match exactly. A mismatch exits with status 2 before runner work begins. Reinstall the current checkout into the active role-specific library, then retry:

source scripts/r-library-path.sh
dsambayes_set_r_library host
R -q -e 'remotes::install_local(".", dependencies = NA, upgrade = "never")'
R -q -e 'library(DSAMbayes); packageVersion("DSAMbayes")'

This gate proves declared-version equality. It cannot prove Git-revision equality when the installed package has no revision metadata. Reinstall after changing branches or pulling changes that keep the same package version. For a CLI run, session_info.txt records the commit of the checkout that supplied the entry-point script. This identifies the checkout; it does not independently prove that a locally installed package with the same version contains identical source bytes.

The script supports these commands:

• init
• validate
• run
• help (or -h / --help)

Command summary

Flag reference

init

• --out <path> (required): output path for the generated YAML file.
• --template <name> (optional): template name. Default is blm.
  • Supported values in script: master, blm, re, cre, pooled, hierarchical.
  • hierarchical maps to the same template file as re.
• --overwrite (optional flag): allow overwrite of an existing --out file.

validate

• --config <path> (required): YAML config path.
• --run-dir <path> (optional): explicit run directory path.

run

• --config <path> (required): YAML config path.
• --run-dir <path> (optional): explicit run directory path.

Usage examples

Show help

Rscript scripts/dsambayes.R --help

Expected outcome: usage panel is printed with command syntax and notes.

Create a new config from template

Rscript scripts/dsambayes.R init --template blm --out config/local_quickstart.yaml

Expected outcome: config/local_quickstart.yaml is created.

Validate only (dry-run behaviour)

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

Expected outcome: validation completes without fitting Stan models.

Validate with explicit run directory

Rscript scripts/dsambayes.R validate \
    --config config/blm_timeseries.yaml \
    --run-dir results/quickstart_validate

Expected outcome: validation uses the provided run directory path when writing run metadata.

Execute full run

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

Expected outcome: full modelling pipeline executes and artefacts are written under results/.

Execute full run with explicit run directory

Rscript scripts/dsambayes.R run \
    --config config/cre_geo_panel.yaml \
    --run-dir results/quickstart_run

Expected outcome: artefacts are written to results/quickstart_run (subject to overwrite rules in config).

Exit and error behaviour

• Exit 0: command completed successfully. For run, this means the pipeline completed and diagnostics did not end in overall_status: fail.
• Exit 1: run completed far enough to preserve the fitted result, but the outcome is non-publishable. This includes diagnostics overall_status: fail, requested scenario-analysis failures, diagnostics publish-gate failures, and post-fit artefact-write failures.
• Exit 2: CLI argument, config, or runtime error before a completed run result could be returned.
• Typical hard failures include:
  • DSAMbayes not installed.
  • Loaded DSAMbayes and checkout versions do not match.
  • Missing required flags (--out or --config).
  • Unknown command.
  • Unknown argument format.

Operational notes

• validate is the recommended pre-run gate. Use it before run whenever you change config or data.
• run prints a run summary and suggested next-step artefacts at completion.
• The CLI itself does not define model semantics. Its package adapter delegates execution to DSAMbayes::run_from_yaml().

Config Schema

Purpose

This page documents the authored YAML contract used by:

• scripts/dsambayes.R
• DSAMbayes::run_from_yaml()
• runme.R

The authored schema is schema_version: 2 only. Older formula-driven YAML files are intentionally rejected.

Processing order

The runner processes configs in this order:

1. Parse YAML.
2. Coerce YAML infinity tokens (.Inf, -.Inf).
3. Apply v2 defaults.
4. Resolve relative paths against the config file directory.
5. Validate the authored v2 contract.
6. Compile the authored config into the internal runner config.
7. Apply managed holiday terms, then build the model and run.

Root sections

Unknown keys fail validation.

Minimal valid config

schema_version: 2

data:
  path: ../data/timeseries/demo_data_synthetic.csv
  format: csv
  date_var: date

target:
  column: revenue
  type: revenue
  transform: identity

media:
  - channel0_signal
  - channel1_signal

controls:
  - t_scaled
  - sin52_1
  - cos52_1

model:
  type: blm

Key differences from the retired schema

• model.formula is no longer authored directly.
• schema_version: 1 configs are rejected.
• Trend and seasonality stay user-authored as ordinary columns under controls.
• Managed time effects are limited to holidays under effects.holidays.
• re and cre models use hierarchy, not cre.enabled flags.
• pooled models use pooling, not pooling.enabled.
• fe models use fixed_effects.unit; hierarchy.group is not an FE alias.

Section reference

schema_version

data

target

media and controls

• media is a required list of modeled media terms.
• controls is a required list, but it may be empty ([]).
• A term may not appear in both lists.
• Manual trend and seasonality terms belong in controls.

All v2 names that become formula terms must be syntactic R names whose value is preserved by make.names(). This rule applies to target.column, target.offset_column, media, controls, fixed_effects.unit, hierarchy.group, and generated term prefixes. ASCII names such as sales_total and media.spend are the portable baseline. Non-ASCII names such as média are supported only when the active R locale preserves the exact name through make.names(). Rename columns containing spaces, operators, backticks, or backslashes before using them in a v2 config; examples such as sales value, paid-search, and sales`net are rejected during config validation. The formula sentinels ., ..., and ..1-style pronouns are also rejected because they do not evaluate as ordinary data columns.

Compiled formula order is:

1. generated holiday terms
2. controls
3. media
4. generated CRE mean terms
5. optional offset
6. hierarchical random-effects term

effects.holidays

Managed holidays are optional and are the only managed effect in M1.

effects:
  holidays:
    enabled: true
    path: ../data/holidays.csv
    label_col: holiday
    country: gb
    country_col: country
    week_start: monday
    prefix: holiday_

Notes:

• The data date column must be aligned to the configured weekly anchor.
• Country filtering materializes a filtered calendar artifact before the compiled config is written.

model

fixed_effects

fixed_effects is required exactly when model.type: fe. The approved shape has one unit key:

model:
  type: fe
  scale: true

fixed_effects:
  unit: geo

fixed_effects.unit must name one syntactic source column. It must differ from the target, date, media, and control columns. For long-format data it must equal data.long_id_col. FE configs cannot also contain hierarchy or pooling.

FE runner support includes validation, dry-run, and bounded non-dry MCMC fitting. Validation and dry-run construct and pre-flight the same unfitted fixed_effects model used by the direct API without Stan compilation or sampling. A materialised dry-run writes only 00_run_metadata/. A non-dry run uses the configured MCMC settings, the existing fit.fixed_effects() path, and the dedicated FE artefact writer.

The FE-safe resolved defaults are:

FE grouped priors support media_beta, control_beta, holiday_beta, and noise_sd. Explicit prior overrides may target an authored slope or noise_sd. Grouped boundaries support media_beta, control_beta, and holiday_beta; explicit boundary overrides may target authored slopes only. Intercept, CRE, pooling, random-effect, and residual-noise boundary requests are rejected.

FE v1 also rejects offsets, log targets, MAP, non-centred positive priors, internal media transformations, implicit row omission, scenario analysis, allocation, forecasting, model selection, time-series selection, generic identifiability output, publish-gate enforcement, flat output layout, level fitted or residual output, deployment, decomposition, and optimisation.

The resolved config exposes save_within_design_csv, save_contrast_residuals_csv, and save_contrast_ppc_csv for the dedicated FE artefact stage. Contrast-space fitted values are diagnostics, not level-scale fitted values or predictions. A completed FE run reports qualification_status: not_assessed and does not set a publishability result. No generic level-scale fitted, observed, residual, diagnostics, decomposition, scenario, optimisation, model-selection, time-series-selection, forecast, or deployment artefacts are written.

hierarchy

Required for model.type: re and model.type: cre.

pooling

Required for model.type: pooled.

priors

Grouped families are available when applicable:

• intercept
• media_beta
• control_beta
• holiday_beta
• cre_beta
• pooling_beta
• random_effect_sd
• noise_sd

Each grouped family accepts either the legacy DSAMbayes style:

family: normal    # or lognormal_ms where supported
mean: 0
sd: 0.5

or the more explicit alias:

distribution: Normal   # or HalfNormal / LogNormalMS where supported
mu: 0
sigma: 0.5

HalfNormal compiles to a zero-centered Normal prior plus an implied lower bound of 0 for unconstrained targeted parameter(s). Parameters that are already positive by construction, such as noise_sd and hierarchical sd_*[...], do not receive an extra boundary row.

The residual-noise prior also accepts this alias:

priors:
  likelihood:
    sigma:
      distribution: HalfNormal
      sigma: 2

boundaries

Boundary families mirror the grouped prior families and may also use explicit boundaries.overrides.

Each grouped or explicit boundary row uses:

lower: -Inf
upper: Inf

For FE, grouped boundaries support media_beta, control_beta, and holiday_beta. A boundary on noise_sd is not supported.

fit

diagnostics

Retains the current runner surface for:

• model_selection
• time_series_selection
• identifiability
• publish-gate controls

Important M1 rule:

• diagnostics.time_series_selection.enabled: true is not supported for pooled runs.
• time-series selection is advisory only in the current release contract; it is not part of publish-gate enforcement.
• lower-level runner paths with adstock/Hill media_transforms are not supported by time-series selection.
• diagnostics.time_series_selection.gap_weeks is optional, defaults to 0, and inserts an embargo between the training window and the scored holdout window.
• FE requires model selection, time-series selection, generic identifiability, and publish-gate enforcement to remain disabled.

scenario_analysis

Opt-in posterior scenario/reference evaluation after a successful MCMC fit:

scenario_analysis:
  enabled: true
  scenario_path: ../data/scenarios/planned.csv
  reference_path: ../data/scenarios/reference.csv
  scale: kpi
  log_response: mean
  interval: 0.9
  aggregate_by: []
  include_percent_lift: true
  save_draws: false

• scenario_path and reference_path must identify CSV or RDS data frames. Relative paths resolve from the config file directory.
• Both inputs must contain aligned rows and all predictors, offsets, date fields, and grouping fields required by the fitted model. They need not contain the response column.
• fit.method must be mcmc. MAP output does not provide posterior contrasts.
• scale is response or kpi. For log-response models, log_response chooses the lognormal conditional mean or the conditional median on the KPI scale.
• aggregate_by names retained label columns. An empty list aggregates the full supplied path within each draw.
• save_draws: false writes summaries and metadata only. Set it to true to add scenario_aggregate_draws.csv.
• For fitted adstock/Hill media, the first supplied observation resets carry-over. If decision-horizon values depend on known earlier exposure, prepend the same observed history to both inputs. The runner reports every supplied row, so retain a field that distinguishes warm-up rows from decision rows if needed.

The output is a model-implied fitted-response contrast, not automatic causal attribution. See Counterfactual response.

allocation

Retains the current runner surface for budget optimisation, with channel targeting based on authored media terms.

• allocation.n_candidates defaults to 2000 and must be a finite integer from 10 through .Machine$integer.max.
• allocation.posterior.draws defaults to 500 and must be a finite integer from 1 through .Machine$integer.max.
• Work scales approximately with candidates multiplied by retained posterior draws and, for efficient frontiers, by the number of feasible budget levels. See Budget Optimisation for measured review thresholds and the benchmark command.

outputs

outputs.root_dir and outputs.run_dir behave as before, but the metadata contract now includes:

• config.original.yaml
• config.resolved.yaml
• config.compiled.yaml
• outputs.save_model_rds controls the full fitted analysis artifact 20_model_fit/model.rds
• outputs.save_deployment_model_rds controls the compact deployment artifact 20_model_fit/deployment_model.rds

When outputs.overwrite: true targets an existing run directory, the runner first validates the complete directory tree. It deletes only recognised flat or staged artifact paths. Unknown files, nested directories, and symbolic links cause an error before any existing artifact is deleted. Empty recognised stage directories may remain and are reused. Concurrent mutation of a run directory during overwrite is not supported.

Current first-slice limit:

• outputs.save_deployment_model_rds: true is 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 keep the normalized pooling map, but deployment-time newdata / data = ... does not need the pooling columns unless they are also ordinary formula terms.
• Hierarchical deployment artifacts are seen-groups-only; explicit scoring/decomposition data must include the raw grouping columns, and decomposition also requires the response source column(s).
• FE dry-runs write metadata only. Non-dry FE runs use bounded MCMC fitting and may write the dedicated posterior summary, sampler text, within-design, contrast-residual, and contrast posterior-predictive artefacts. They do not enter generic post-fit or decision-layer paths and remain unqualified.

forecast

Reserved placeholder only. In v1.3.3, enabling forecast can materialise 70_forecast/, but the runner does not emit forecast files or plots.

Examples in this repository

• config/blm_timeseries.yaml, weekly time-series BLM example
• config/fe_panel.yaml, weekly geo-panel FE validation, dry-run, and bounded MCMC example
• config/re_geo_panel.yaml, weekly geo-panel RE example
• config/cre_geo_panel.yaml, weekly geo-panel CRE example

Related pages

• CLI Usage
• Run from YAML
• Time Components
• CRE / Mundlak

Output Artefacts

Purpose

This page defines what the YAML runner writes, where files are written, and which config flags control each artefact.

Related pages:

• CLI Usage
• Config Schema

Run directory and layout semantics

Run directory precedence:

1. CLI --run-dir
2. outputs.run_dir
3. Timestamped folder under outputs.root_dir

Layout behaviour:

• outputs.layout: staged (default) writes files under numbered stage folders.
• outputs.layout: flat writes all files directly under the run directory.

Stage folders used by the runner:

• 00_run_metadata
• 10_pre_run
• 20_model_fit
• 30_post_run
• 40_diagnostics
• 50_model_selection
• 60_scenario_analysis (only when scenario_analysis.enabled: true)
• 70_forecast (reserved; directory only when forecast.enabled: true)
• 80_optimisation (only when optimisation or allocation output is written)

artifact_schema_version: 2 identifies this layout. Schema-v1 run directories retain 60_optimisation/; the runner does not rename historical results.

Command behaviour

validate

• validate uses dry_run = TRUE.
• If no run directory is resolved, no artefacts are written.
• If a run directory is resolved (--run-dir or outputs.run_dir), config.original.yaml is written.
• If a run directory is resolved (--run-dir or outputs.run_dir), config.resolved.yaml is written.
• If a run directory is resolved (--run-dir or outputs.run_dir), config.compiled.yaml is written.
• If a managed holiday country filter is active and a run directory is resolved, holiday_calendar.filtered.csv is materialised under 10_pre_run/.
• If a run directory is resolved and outputs.save_session_info_txt: true, session_info.txt is written.
• If forecast is enabled and a run directory is materialised, the 70_forecast/ directory is created.

run

• run writes the full artefact set subject to config toggles and runtime conditions.

Fixed-effects run boundary

Fixed-effects (model.type: fe) runs use a dedicated artefact contract. They fit the existing coefficient-only MCMC estimator, then return before the generic post-fit and decision-layer paths.

With the tracked config/fe_panel.yaml defaults, a completed staged run writes:

• 00_run_metadata/artifact_schema.yaml
• 00_run_metadata/config.original.yaml
• 00_run_metadata/config.resolved.yaml
• 00_run_metadata/config.compiled.yaml
• 00_run_metadata/run_status.yaml
• 00_run_metadata/session_info.txt
• 20_model_fit/model.rds
• 30_post_run/posterior_summary.csv
• 40_diagnostics/chain_diagnostics.txt
• 40_diagnostics/diagnostics_summary.txt
• 40_diagnostics/within_design.csv
• 40_diagnostics/contrast_residuals.csv
• 40_diagnostics/contrast_ppc.csv

The relevant outputs.* flags may remove optional files from this inventory. Setting outputs.save_posterior_rds: true adds 20_model_fit/posterior.rds. Managed holidays may add the existing holiday provenance files under 10_pre_run/.

The two RDS files have different purposes. model.rds is the full fitted same-environment analysis object; it preserves the fitted RStan state and retained FE metadata for reload under the compatible R, RStan, and package environment. posterior.rds is the optional compact extracted posterior table; it is not an executable fitted model and does not replace model.rds.

FE CSV column contracts are:

posterior_summary.csv contains slopes and noise_sd; it does not contain a unit intercept, RMSE, or SMAPE. The three contrast tables use the deterministic orthonormal Helmert basis retained by the fitted model. Their values and labels are basis-dependent diagnostics, not row-level observations, level-scale fitted values, or predictions. Preserve contrast_label and contrast_basis when comparing or joining these files.

diagnostics_summary.txt records factual design metadata and includes:

generic_diagnostics_report: not_run
publish_gate: disabled
qualification_status: not_assessed

Therefore, a completed FE run makes no diagnostic pass, publishability, or production-qualification claim. No generic level-scale fitted, observed, residual, diagnostics, decomposition, scenario, optimisation, model-selection, time-series-selection, forecast, or deployment artefacts are written.

Artefact contract by stage

00_run_metadata

10_pre_run

20_model_fit

30_post_run

Active v1.3 pipeline note:

• 30_post_run/ emits observed and fitted summaries, posterior summaries, and runner linear term-contribution artefacts when their toggles are enabled.
• Runner contribution artefacts fail closed for hierarchical models, models with offsets, and models fitted with probabilistic media transforms. Use the native interactive decomp() contract where that model class is supported.
• When decomposition is unavailable, the runner records deterministic skip rows in 40_diagnostics/artifact_status.csv rather than silently dropping the contract entries.

40_diagnostics

50_model_selection

60_scenario_analysis

The runner emits model-implied fitted-response contrasts. These are not causal effects unless the model design and external assumptions justify that claim.

70_forecast

80_optimisation

Deployment artifact note:

• deployment_model.rds lives under 20_model_fit/, not 70_forecast/.
• It is a compact packaging artifact for deployment consumers, not a signal that the runner now generates future-data forecasts or scenarios.

Response scale semantics (*_kpi.csv vs base files)

Base files (observed.csv, fitted.csv) are always on the model response scale:

• identity response: KPI units
• log response: log(KPI)

KPI-scale files are written only for log-response models:

• observed_kpi.csv
• fitted_kpi.csv

Conversion metadata:

• observed_kpi.csv uses conversion_method = point_exp.
• fitted_kpi.csv uses conversion_method = lognormal_mean by default for log-response fitted values.
• fitted_kpi.csv uses conversion_method = point_exp only when the median back-transform is explicitly requested.

Diagnostics status semantics

diagnostics_report.csv status values:

• pass: check passed configured thresholds
• warn: check breached warning threshold
• fail: check breached fail threshold
• skipped: check not applicable or intentionally skipped

Overall status logic:

• fail if any check is fail
• warn if no fails and at least one warn
• pass otherwise

diagnostics_summary.txt reports:

• overall_status
• counts for pass, warn, fail, skipped

Quick verification commands

List produced files for a run:

latest_run="$(ls -td results/* | head -n 1)"
find "$latest_run" -type f | sort

Inspect key diagnostics files:

latest_run="$(ls -td results/* | head -n 1)"
head -n 20 "$latest_run/40_diagnostics/diagnostics_report.csv"
head -n 20 "$latest_run/40_diagnostics/diagnostics_summary.txt"

Model Classes

Purpose

DSAMbayes provides four model classes for Bayesian marketing mix modelling. Each class targets a different data structure and pooling strategy. This page describes the constructor pathways, fit support, and practical limitations of each class so that an operator can select the appropriate model for a given dataset.

The fixed-effects (FE) class is a separate coefficient-only estimator. A hierarchical model with unit random intercepts remains a random-effects model, not an FE estimator.

Use this page to choose the right modelling surface for your data structure and decision problem. Do not use it as a substitute for the broader workflow: class selection does not settle prior design, computational trustworthiness, model adequacy, or causal interpretation. For that framing, start with What Principled Means, Stage 2: Model and Priors, and Stage 5: Model Adequacy.

Selection discipline

• Choose the simplest class that matches the real data structure.
• Do not move to hierarchical or pooled models only because they look more advanced.
• Treat model class as a structural choice, not proof that the resulting model is decision-ready.
• After choosing a class, return to the workflow pages for prior-setting, diagnostics, and interpretation discipline.

Class summary

Fixed effects (fixed_effects)

Construction

model <- fixed_effects(kpi ~ m_tv + m_search + trend, panel_df, market) |>
  set_date(week)

FE v1 removes unrestricted unit intercepts with deterministic orthonormal within-unit contrasts. It estimates common slopes and residual noise through MCMC. Formula terms must be bare numeric columns, and retained unit-date keys must be unique. Unequal unit sizes and irregular date spacing are allowed.

Output boundary

Use get_posterior() for reporting-scale slope and residual-noise draws and within-contrast generated quantities. FE v1 does not recover unit intercepts or support MAP, level fitted values, prediction, model selection, decomposition, counterfactual analysis, optimisation, forecasting, or deployment. It supports YAML validation, dry-run, and bounded MCMC fitting with dedicated coefficient and contrast-space artefacts.

P4-J’s bounded live runner, explicit-prior prior-only, one-replication recovery, and sampler gates passed. These checks do not estimate repeated-sampling coverage or production reliability. The implementation is not production-qualified, so FE remains implemented_not_qualified. See Estimator Capabilities for the full contract.

BLM (blm)

Construction

model <- blm(kpi ~ m_tv + m_search + trend + seasonality, data = df)

blm() dispatches on the first argument. When passed a formula, it creates a blm object with default priors and boundaries. When passed an lm object, it creates a bayes_lm_updater whose priors are initialised from the OLS coefficient estimates and standard errors.

Fit support

Post-fit accessors

• get_posterior(), coefficient draws, fitted values, metrics
• fitted(), predicted response on the original scale
• decomp(), native predictor-level decomposition. It returns a dsambayes_decomposition S3 result for BLM objects; use $DecompedData for the long-form contribution table. Hierarchical models return a keyed tibble with one such result in each row’s decomp list-column.
• optimise_budget(), decision-layer budget allocation

Decomposition migration

decomp() no longer returns the external DSAMdecomp S4 calculators. This is a breaking development-version change. Replace S4 slot access such as result@DecompedData with result$DecompedData; use result$DecompGroupProps for grouped totals. The DSAMdecomp-only plotting and post-processing helpers are not part of the native result. Build any required downstream summaries from these two tables.

Limitations

• No group structure. For multi-market data, use the hierarchical class.
• optimise_budget() aborts if scale=TRUE and an offset is present (unsupported combination for the bayes_lm_updater Stan template).

Hierarchical (hierarchical)

Construction

The hierarchical class is created automatically when blm() detects random-effects syntax (|) in the formula:

model <- blm(
  kpi ~ m_tv + m_search + trend + (1 + m_tv + m_search | market),
  data = panel_df
)

Terms to the left of | become random slopes; the variable to the right defines the grouping factor. Multiple grouping terms are supported.

The ordinary random-effects specification partially pools group effects and uses both within-group and between-group information for population coefficients. Its interpretation requires the group effects to be conditionally mean-independent of the regressors. If this assumption is not credible, use a justified CRE specification or another design. Neither option solves omitted time-varying confounding by itself.

CRE / Mundlak extension

For correlated random effects, call set_cre() after construction:

cre_model <- blm(
  kpi ~ m_tv_signal + m_search_signal + trend + (1 | market),
  data = panel_df
) |>
  set_cre(vars = c("m_tv_signal", "m_search_signal"))

CRE v1 is restricted to a selected random-intercept group with no random slope in that group. Each CRE variable must be one simple numeric main effect and must not overlap an internal draw-dependent media transform. Fit preparation calculates the Mundlak means from the exact retained estimation frame. See CRE / Mundlak for details.

Fit support

Post-fit accessors

Same as BLM. Coefficient draws from get_posterior() return vectors (one value per group) rather than scalars. Budget optimisation uses the population-level (fixed-effect) coefficient draws from the beta parameter.

Limitations

• Stan template compilation uses a templated source (general_hierarchical.stan) rendered per number of groups and parameterisation mode. First compilation is slow; subsequent runs use a cached binary.
• Response decomposition is native and returns one result per retained group. Probabilistic media transforms remain unsupported for decomposition and are rejected explicitly.
• Formula offsets enter native decomposition as coefficient-one baseline components and must be included in the decomposition mapping table.
• Posterior forest and prior-vs-posterior plots average group-specific draws to produce a single population-level estimate.
• Offset support in the hierarchical Stan template is handled via stats::model.offset() within build_hierarchical_frame_data().

Pooled (pooled)

Construction

The pooled class is created by converting an existing BLM object with pool():

base <- blm(kpi ~ m_tv + m_search + trend + seasonality, data = df)
model <- pool(base, grouping_vars = c("channel"), map = pooling_map)

The map is a data frame with a variable column mapping formula terms to pooling dimension labels. Exact formula-term labels are preferred; raw variable names are accepted only when they resolve unambiguously to a single non-offset formula term. Priors and boundaries are reset to defaults when pool() is called.

Fit support

MAP fitting (fit_map) is not currently implemented for pooled models.

Post-fit accessors

Same as BLM. The design matrix is split into base terms (intercept + non-pooled) and media terms (pooled). The Stan template uses a per-dimension coefficient structure.

Limitations

• MAP fitting is not available.
• extract_stan_design_matrix() may return a zero-row matrix, which causes VIF computation to be skipped.
• The pooled Stan cache key includes sorted grouping variable names to avoid collisions between different pooling configurations.
• Time-series cross-validation is available for pooled MCMC models, subject to the same media-transform restrictions as other classes.

Class selection guide

In practice, the class decision should usually be driven by three questions:

1. Is the dataset a single time series or a grouped panel?
2. Do you need partial pooling across real groups, or pooling across labelled coefficient dimensions?
3. Is the added structure necessary for the business question, or are you adding complexity without a clear identifiability benefit?

Fit method selection

For inferential runs where diagnostics and uncertainty quantification matter, MCMC is the recommended fit method. MAP is useful for rapid iteration during model development. Fit method alone does not qualify an estimator for production use.

MAP returns one selected optimum, not posterior draws. Do not derive credible intervals or MCMC diagnostics from it; its point estimate can understate uncertainty, especially for hierarchical variance components. fit_map() retains the restart results for inspection (and runner outputs include optimisation_runs.csv), so materially different restart objectives should be treated as optimisation instability or competing local optima, not as a substitute for posterior uncertainty.

Cross-references

• Model Object Lifecycle, state transitions from construction to post-fit
• Priors and Boundaries, prior and constraint specifications
• CRE / Mundlak, correlated random effects for hierarchical models
• Diagnostics Gates, post-fit quality checks
• Stage 2: Model and Priors, workflow framing for structural choices and prior design
• Stage 5: Model Adequacy, what must still be checked after selecting a class

Model Object Lifecycle

DSAMbayes model objects (blm, hierarchical, pooled) are mutable S3 lists that progress through a well-defined sequence of states. Understanding these states helps avoid calling post-fit accessors on an unfitted object or forgetting to compile before fitting.

This page is an API/runtime reference. It explains how DSAMbayes model objects move through construction, compilation, fitting, and post-fit access. It is not the main guide for prior-setting, diagnostics meaning, or model adequacy. For that, use the Principled Bayesian Workflow.

State-machine diagram

                        ┌─────────────────────────────────────────┐
                        │           CREATED                       │
                        │  blm(), blm.formula(), blm.lm(),        │
                        │  as_bayes_lm_updater()                  │
                        │  Fields set: .formula, .original_data,  │
                        │    .prior, .boundaries                  │
                        └──────────────┬──────────────────────────┘
                                       │
            ┌──────────────────────────┼──────────────────────────┐
            ▼                          ▼                          ▼
    set_prior(obj, …)         set_boundary(obj, …)        set_date(obj, …)
    Mutates .prior            Mutates .boundaries         Sets .date_var
            │                          │                          │
            └──────────────────────────┼──────────────────────────┘
                                       │
                    (optional: pool() transitions blm → pooled,
                     resets .prior/.boundaries, adds .pooling_vars/.pooling_map)
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           CONFIGURED                    │
                        │  Priors, boundaries, date variable are  │
                        │  set (may still use defaults).          │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           COMPILED                      │
                        │  compile_model(obj)                     │
                        │  Sets .stan_model                       │
                        │  (pre_flight_checks auto-compiles if    │
                        │   .stan_model is NULL)                  │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           PRE-FLIGHTED                  │
                        │  pre_flight_checks(obj, data)           │
                        │  Validates formula/data compatibility,  │
                        │  auto-compiles and auto-sets date_var   │
                        │  if missing. Sets .response_transform,  │
                        │  .response_scale.                       │
                        └──────────────┬──────────────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────────────────┐
                        │           FITTED                        │
                        │  fit(obj) / fit_map(obj)                │
                        │  Calls pre_flight_checks internally,    │
                        │  then prep_data_for_fit → rstan.        │
                        │  Sets .stan_data, .date_val, .posterior │
                        └──────────────┬──────────────────────────┘
                                       │
                   ┌───────────────────┼───────────────────┐
                   ▼                   ▼                   ▼
           get_posterior(obj)    fitted(obj)         decomp(obj)
           Returns tibble of    Predicted values    Decomposition
           posterior draws      (yhat)              native DSAMbayes result
                   │                                       │
                   ▼                                       ▼
           optimise_budget(obj, …)                         Further analysis
           Budget allocation
           (requires fitted model)

States and key fields

Post-fit accessors

These functions require a fitted model (.posterior is not NULL):

Guards and auto-transitions

• pre_flight_checks() auto-compiles via compile_model() if .stan_model is NULL, and auto-sets .date_var to "date" if not already set.
• fit() and fit_map() call pre_flight_checks() internally, so explicit compilation is optional.
• get_posterior() aborts with a clear error if .posterior is NULL.
• optimise_budget() aborts if the model has scale=TRUE and an offset is present (unsupported combination for the bayes_lm_updater class).

Object field reference

All fields are initialised by model_object_schema_defaults() in R/model_schema.R. The canonical field list:

Runner-injected fields

These are set by the YAML/CLI runner (run_from_yaml()) for artifact writing and are not part of the core modelling API:

• .runner_config, .runner_kpi_type, .runner_identifiability
• .runner_time_components, .runner_budget_optimisation
• .runner_model_selection, .runner_model_type

Priors and Boundaries

For the workflow guidance behind these controls, start with Stage 2: Model and Priors. This page is the technical contract for DSAMbayes prior and boundary behaviour.

Use this page when you need exact DSAMbayes semantics: supported prior families, override syntax, default generation rules, and scaling behaviour. Do not use it as the main argument for why a prior is reasonable. That reasoning belongs in the workflow pages and in your modelling rationale.

Purpose

This page defines how DSAMbayes specifies, defaults, overrides, and scales coefficient priors and parameter boundaries for all model classes. It covers the prior schema, supported families, default-generation logic, YAML override contract, and the interaction between priors, boundaries, and the scale=TRUE pathway.

How to read this page

• Use Minimal-Prior Policy if you want the short recommended operating rule.
• Use this page when you need to know exactly how DSAMbayes will interpret a prior or boundary specification.
• Return to Stage 2: Model and Priors if the question is whether a custom prior should be added at all.

Prior schema

Each model object carries a .prior tibble with one row per parameter. The columns are:

Supported prior families

All coefficient priors use normal(). The lognormal_ms family is parameterised by the mean and standard deviation on the original (non-log) scale; DSAMbayes converts these internally to log-space parameters.

Default prior generation

BLM and hierarchical (population terms)

default_prior.blm() calls standard_prior_terms(). On the reporting scale, the intercept prior is normal(ybar, sy), each slope prior is normal(0, sy / sx), and the residual-SD prior is normal(0, sy), where sy and sx are the response and term standard deviations. These defaults therefore map to unit-scale priors after internal standardisation and respond coherently when measurement units change.

Hierarchical (group-level standard deviations)

default_prior.hierarchical() additionally generates sd_<idx>[<term>] rows for each group factor. Each constrained group SD receives a zero-centred normal prior whose scale matches the corresponding coefficient scale: sy for a group intercept and sy / sx for a random slope. Because the SD parameter is constrained positive in Stan, this acts as a half-normal prior. It remains positive when observed group outcome means happen to be equal, and random-slope defaults change coherently when predictor measurement units change.

Specify hierarchical standard-deviation priors in reporting-scale units. With scale = TRUE, DSAMbayes transforms them to the Stan scale: intercept heterogeneity is divided by the response standard deviation, while slope heterogeneity is multiplied by the predictor-to-response standard-deviation ratio. The group intercept is defined at the internally centred predictor reference point. It is not a group intercept at raw predictor values of zero. With the defaults above, these transformations produce unit-scale group-SD priors in Stan space. Explicit user overrides retain their supplied reporting-scale meaning and are transformed by the same rules.

Default population and group-SD scales use the same population-model complete-case frame. This keeps the reporting-to-Stan transformation exact when a population term contains missing values. Random-slope terms must be numeric. Group-only random-slope terms are evaluated on the retained population rows. DSAMbayes aborts rather than deriving a group-SD default when a group term would drop additional rows or when a factor random slope is unsupported.

BLM from lm (Bayesian updating)

default_prior.bayes_lm_updater() initialises coefficient priors from the OLS point estimates (mean) and standard errors (sd), enabling informative Bayesian updating.

Pooled

default_prior.pooled() uses the BLM defaults for non-pooled terms (intercept, base regressors, noise_sd) and normal(0, 5) for each dimension-level pooled coefficient. Default pooled boundaries remain unconstrained; add explicit boundaries if a pooled dimension should be sign-restricted.

Boundary schema

Each model object carries a .boundaries tibble with one row per parameter:

Default boundaries are lower = -Inf, upper = Inf for all terms. No sign constraints are imposed by default.

YAML override contract

Prior overrides

priors:
  use_defaults: true
  overrides:
    - { parameter: m_tv, mean: 0.5, sd: 0.2 }
    - { parameter: price_index, mean: -0.2, sd: 0.1 }

Each override replaces the distribution call for the named parameter with normal(mean, sd). Overrides are sparse: only the listed parameters are changed; all other parameters keep their defaults.

In M1, use_defaults must remain true. The v2 runner is default-first: it always starts from the generated prior table, then applies sparse grouped aliases and explicit overrides.

The friendly YAML surface also accepts an explicit alias style:

priors:
  media_beta:
    distribution: HalfNormal
    sigma: 1

or:

priors:
  intercept:
    distribution: Normal
    mu: 120000
    sigma: 15000

HalfNormal is implemented by compiling to normal(0, sigma) plus an implied lower bound of 0 on targeted parameters that are otherwise unconstrained. The priors.likelihood.sigma alias compiles to the DSAMbayes noise_sd prior family.

Boundary overrides

boundaries:
  overrides:
    - { parameter: m_tv, lower: 0.0, upper: .Inf }
    - { parameter: competitor_discount, lower: -.Inf, upper: 0.0 }

Each override replaces the boundary entry for the named parameter. YAML infinity tokens (.Inf, -.Inf) are coerced during config resolution.

Scale semantics (scale = TRUE)

When model.scale: true (the default), the response and predictors are standardised before Stan fitting. This affects both priors and boundaries.

Coefficient prior scaling

Prior standard deviations are scaled by the ratio sx / sy for slope terms and by 1 / sy for the intercept. The noise_sd prior standard deviation is multiplied by sy (the response standard deviation) to remain interpretable in the scaled space.

Boundary scaling

• Zero boundaries (0) are invariant under scaling.
• Infinite boundaries (±Inf) are invariant under scaling.
• Finite non-zero boundaries for slope terms are scaled using scale_boundary_for_parameter(), which applies the same sx / sy ratio used for slope priors.
• If a finite non-zero boundary is specified for a parameter without a matching scale factor in the design matrix, DSAMbayes aborts with a validation error.

Practical implication

Users specify priors and boundaries on the original (unscaled) data scale. DSAMbayes converts them internally before passing data to Stan. Post-fit, coefficient draws are back-transformed to the original scale by get_posterior().

Interaction with model classes

Programmatic API

Inspect priors and boundaries

peek_prior(model)
peek_boundary(model)

Override priors

model <- model %>%
  set_prior(
    m_tv ~ normal(0.5, 0.2),
    price_index ~ normal(-0.2, 0.1)
  )

Override boundaries

model <- model %>%
  set_boundary(
    m_tv > 0,
    competitor_discount < 0
  )

Minimal-prior policy

The recommended operating profile for MMM is documented in Minimal-Prior Policy. The policy keeps priors weak by default and uses hard constraints only when there is structural business knowledge.

Cross-references

• Model Classes, constructor and fit support per class
• Minimal-Prior Policy, governance guidance for prior specification
• Response Scale Semantics, link vs KPI scale behaviour
• Config Schema, YAML prior and boundary keys

Minimal-Prior Policy

This page is the short operating rule for prior-setting in DSAMbayes. Use it when you want a compact default policy. For the full workflow logic, see Stage 2: Model and Priors. For the mechanics of YAML and API prior specification, see Priors and Boundaries.

Purpose

Use a principled but low-friction prior setup that avoids specification-hunting while preserving identifiability in short, collinear MMM datasets.

Policy

1. Default-first: keep priors.use_defaults: true.
2. Sparse overrides: only add priors.overrides for high-conviction terms.
3. Selective bounds: add boundaries.overrides only for structural signs.
4. No blanket constraints: do not force all controls/media to one sign by default.
5. Diagnose before tightening: use pre-flight and diagnostics gates first, then add priors/bounds if uncertainty is still unstable.

YAML mapping

priors:
  use_defaults: true
  overrides:
    # Optional high-conviction override examples:
    # - { parameter: price_index, mean: -0.2, sd: 0.1 }
    # - { parameter: distribution, mean: 0.15, sd: 0.1 }

boundaries:
  overrides:
    # Optional structural sign constraints:
    # - { parameter: m_tv, lower: 0.0, upper: .Inf }
    # - { parameter: competitor_discount, lower: -Inf, upper: 0.0 }

When to override defaults

• Do override when domain mechanism is stable and defensible.
• Do not override only to improve one run’s fit metrics.
• Do not add bounds if sign can plausibly flip under promotion, pricing, or substitution effects.

Review checklist

• Are overrides fewer than the number of major business assumptions?
• Is each bound tied to a concrete causal rationale?
• Did diagnostics indicate a real identifiability problem before tightening?

When to use this page

• Use this page when you need a concise prior-setting policy for routine MMM work.
• Use Stage 2: Model and Priors when you need the reasoning behind that policy.
• Use Priors and Boundaries when you need exact DSAMbayes syntax, scaling rules, or boundary mechanics.

Response Scale Semantics

Purpose

DSAMbayes models can operate on an identity (level) or log response scale. This page defines how response scale is detected, stored, and used for post-fit reporting, so that operators understand which scale their outputs are on and how KPI-scale conversions work.

Response scale detection

Response scale is determined at construction time by detect_response_scale(), which inspects the left-hand side of the formula:

The detected value is stored in two model-object fields:

• .response_transform: "identity" or "log". Describes the mathematical transform applied to the response before modelling.
• .response_scale: "identity" or "log". Used as a label when reporting whether outputs are on the model scale or the KPI scale.

Both fields are set by the constructor and confirmed by pre_flight_checks().

Model scale vs KPI scale

For identity-response models, model scale and KPI scale are identical. For log-response models, fitted values and residuals on the model scale are in log units and must be exponentiated to obtain KPI-scale values.

This is a semilog model, not a log-log model. In DSAMbayes, a coefficient from log(kpi) ~ x means:

So for a one-unit increase in x, the exact KPI-scale percentage change is:

The common shortcut 100 * beta is only a small-coefficient approximation.

Interpreting log-response models

This is the section to use when an analyst asks, “what does the coefficient actually mean on the KPI scale?”

1. Coefficients stay on the model scale

For a model written as:

the coefficient beta returned by get_posterior() and summarised in posterior_summary.csv is a log-KPI coefficient. DSAMbayes does not silently convert coefficient tables into KPI-scale percentage effects.

2. The exact KPI-scale effect depends on the predictor change

For a change of \Delta x in a predictor, the model implies:

Special cases:

• If \Delta x = 1, the exact percent change is 100 * (exp(beta) - 1).
• If x is a binary indicator changing from 0 to 1, use the same exact formula.
• The shortcut 100 * beta is only acceptable when beta * \Delta x is small enough that the approximation error is negligible for the use case.

3. This is not automatically an elasticity

log(kpi) ~ x is a semilog model. The coefficient is an elasticity only if the predictor is also logged, for example log(kpi) ~ log(x).

So in DSAMbayes:

• log(kpi) ~ x gives a semilog coefficient.
• log(kpi) ~ log(x) would be interpreted as an elasticity.

4. Coefficients attach to the modeled column, not necessarily raw spend

DSAMbayes coefficients describe the predictor that actually enters the model matrix.

That matters because in MMM workflows the modeled term is often:

• an adstocked media signal,
• a saturated transform,
• a normalized exposure metric,
• or another user-authored transformed column.

So if your YAML media block points to transformed signal columns, the coefficient is per unit of that transformed signal, not per unit of raw spend. The same caution applies to interactive formula workflows.

5. Use the right output for the question

Use these surfaces consistently:

• posterior_summary.csv and get_posterior() for coefficient summaries on the model scale.
• fitted.csv and observed.csv for fitted and observed values on the model scale.
• fitted_kpi.csv, observed_kpi.csv, and fitted_kpi() for business-facing values on the KPI scale.