Install and Setup

Audience

Engineers and analysts setting up DSAMbayes for local development or modelling runs.

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 Version: 1.3.3 (or current 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 from GitHub

If you do not have a local checkout, install from the GitHub remote:

R -q -e 'remotes::install_github("groupm-global/DSAMbayes")'

This installs the latest version on main. For the development fork with v1.3.3 features, use the local-checkout path above.

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.

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 synthetic dataset shipped at data/synthetic_dsam_example_wide_data.csv. It contains weekly observations for a single market with columns for:

• Response: kpi_os_hfb01_value — weekly KPI (e.g. revenue).
• Media: m_tv, m_search, m_social, m_display, m_ooh, m_email, m_affiliate.
• Controls: t_scaled (trend), sin52_1/cos52_1/sin52_2/cos52_2 (Fourier seasonality), price_index, distribution, bm_ikea_trust_12r (brand metric).
• Holidays: h_black_friday, h_christmas, h_new_year, h_easter, h_summer_sale.

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

Step 1: Construct the model

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

model <- blm(
  kpi_os_hfb01_value ~
    t_scaled + sin52_1 + cos52_1 + sin52_2 + cos52_2 +
    h_black_friday + h_christmas + h_new_year + h_easter + h_summer_sale +
    bm_ikea_trust_12r + price_index + distribution +
    m_tv + m_search + m_social + m_display + m_ooh + m_email + m_affiliate,
  data = df
)

Inspect defaults:

peek_prior(model)      # normal(0, 5) for all terms
peek_boundary(model)   # (-Inf, Inf) — unconstrained

Step 2: Set boundaries

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

model <- model %>%
  set_boundary(
    m_tv > 0, m_search > 0, m_social > 0,
    m_display > 0, m_ooh > 0, m_email > 0, m_affiliate > 0
  )

Step 3: (Optional) Override priors

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

model <- model %>%
  set_prior(price_index ~ normal(-0.2, 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 2 chains on synthetic data, sampling 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

decomp_tbl <- decomp(fitted_model)
head(decomp_tbl)

Shows each term’s contribution (coefficient × design-matrix column) to the predicted KPI at each time point — the foundation for media contribution and ROI reporting.

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 data/synthetic_dsam_example_hierarchical_data.csv — a panel dataset with weekly observations across multiple markets. Key columns:

• Response: kpi_value — weekly KPI per market.
• Group: market — market identifier.
• Media: m_tv, m_search, m_social — media exposure variables.
• Controls: trend, seasonality, brand_metric.
• Date: date — weekly date index.

library(DSAMbayes)
panel_df <- read.csv("data/synthetic_dsam_example_hierarchical_data.csv")
table(panel_df$market)  # 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(
  kpi_value ~
    trend + seasonality + brand_metric +
    m_tv + m_search + m_social +
    (1 + m_tv + m_search + m_social | market),
  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(m_tv > 0, m_search > 0, m_social > 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 controls for this:

model <- model %>%
  set_cre(vars = c("m_tv", "m_search", "m_social"))

This adds cre_mean_m_tv, cre_mean_m_search, cre_mean_m_social as fixed effects — the group-level means of each media variable. The within-group coefficients then represent purely temporal variation, controlling for between-group confounding.

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 market
fit_tbl <- fitted(fitted_model)
head(fit_tbl)

# Decomposition — per-group predictor contributions
decomp_tbl <- decomp(fitted_model)

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

Open a terminal in the repository root:

source scripts/r-library-path.sh
dsambayes_set_r_library host
mkdir -p "$R_LIBS_USER" .cache
export XDG_CACHE_HOME="$PWD/.cache"

2. Validate the configuration (dry run)

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

Expected: exits with code 0. No Stan compilation or sampling occurs.

3. Execute the full run

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

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

4. Locate and inspect the run directory

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

Expected stage folders:

5. Verify key artefacts

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

6. Load the model in R

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

library(DSAMbayes)

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

# Posterior coefficient summary
post <- get_posterior(model)

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

# Sampler diagnostics
chain_diagnostics(model)

# Fitted values
head(fitted(model))

7. Review diagnostics

Open 40_diagnostics/diagnostics_report.csv:

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

Quick interpretation:

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

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

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

8. Start from a tracked example config

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

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

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

What the quickstart does not prove

A successful run means:

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

It does not by itself prove:

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

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

If the quickstart fails

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

Next steps

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

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

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 behavior, 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 behavior 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 behavior 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 behavior

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/loo_pit.png
• 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]

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, diagnostics publish-gate failures, and post-fit artifact-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.
  • 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. It 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.

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.

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

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

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.

allocation

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

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

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).

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/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_optimisation
• 70_forecast (reserved; directory only when forecast.enabled: true)

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.

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, fitted, posterior summary, and decomposition artifacts when the corresponding output toggles are enabled and decomposition can be computed from the fitted model.
• 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_optimisation

70_forecast

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 three 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.

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

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() — predictor-level decomposition via DSAMdecomp
• optimise_budget() — decision-layer budget allocation

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.

CRE / Mundlak extension

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

model <- set_cre(model, vars = c("m_tv", "m_search"))

This augments the population formula with group-mean terms (cre_mean_*) and updates priors and boundaries accordingly. 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 via model.matrix() may fail for formulas containing | syntax. The runner wraps this in tryCatch and skips gracefully.
• 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 production runs where diagnostics and uncertainty quantification matter, MCMC is the recommended fit method. MAP is useful for rapid iteration during model development.

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)              via DSAMdecomp
                   │                                       │
                   ▼                                       ▼
           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 behavior.

Use this page when you need exact DSAMbayes semantics: supported prior families, override syntax, default generation rules, and scaling behavior. 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 available only for the noise_sd parameter and 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(), which produces normal(0, 5) for each population-formula term (intercept and slope terms) plus a noise_sd entry.

Hierarchical (group-level standard deviations)

default_prior.hierarchical() additionally generates sd_<idx>[<term>] rows for each group factor. The prior standard deviation is set to the between-group standard deviation of the response, rounded to two decimal places.

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.

For log-response models, posterior_summary.csv is therefore the wrong place to read off a KPI-scale uplift directly. It is the right place to get beta, which you then interpret with 100 * (exp(beta * \Delta x) - 1).

6. DSAMbayes labels KPI-scale conversions explicitly

When DSAMbayes writes KPI-scale outputs for log-response models, it records:

• source_response_scale = "log"
• response_scale = "kpi"
• conversion_method

This is intended to make it obvious that the values have been back-transformed and to distinguish the default lognormal-mean conversion from the simpler pointwise exp() median-style conversion.

Post-fit accessors and scale behaviour

fitted() — model scale

fitted() returns predicted values on the model scale. For identity-response models this is the KPI scale. For log-response models this is the log scale.

fit_tbl <- fitted(model)
# fit_tbl$fitted is on model scale

fitted_kpi() — KPI scale

fitted_kpi() applies the inverse transform draw-wise before summarising. For log-response models the default conversion (since v1.2.2) uses the conditional-mean estimator:

This is the bias-corrected back-transform that accounts for the log-normal variance term. The previous behaviour (v1.2.0) used the simpler exp(mu) estimator, which corresponds to the conditional median on the KPI scale. To retain that behaviour, pass log_response = "median":

# Default (v1.2.2): conditional mean — bias-corrected
kpi_tbl <- fitted_kpi(model)

# Explicit median — equivalent to pre-v1.2.2 behaviour
kpi_tbl <- fitted_kpi(model, log_response = "median")

The output includes source_response_scale (the model’s response scale), response_scale = "kpi", and conversion_method ("conditional_mean" or "point_exp") to label the result.

observed() — model scale

observed() returns the observed response on the model scale after unscaling (if scale=TRUE).

observed_kpi() — KPI scale

observed_kpi() returns the observed response on the KPI scale. For log-response models, this applies exp() to the model-scale observed values.

to_kpi_scale() helper

The internal function to_kpi_scale(x, response_scale) implements the conversion:

• If response_scale == "log": returns exp(x).
• Otherwise: returns x unchanged.

This function is used consistently by fitted_kpi(), observed_kpi(), and runner artefact writers.

Runner artefact scale conventions

Runner artefact writers use the response scale metadata to determine which scale to report:

Interaction with scale = TRUE

The scale flag and response scale are orthogonal:

• scale = TRUE standardises predictors and response by centring and dividing by standard deviation before Stan fitting. Coefficients and fitted values are back-transformed to the original scale by get_posterior().
• Response scale determines whether the original scale is levels (identity) or logs (log).

Both transformations compose: a log-response model with scale=TRUE first takes the log of the response (via the formula), then standardises the logged values. Post-fit, draws are first unscaled, then (for KPI-scale outputs) exponentiated.

Jensen’s inequality and draw-wise conversion

When converting log-scale posterior draws to KPI scale, DSAMbayes applies exp() to each draw individually before computing summaries (mean, median, credible intervals). This is the correct Bayesian approach because:

• E[exp(X)] ≠ exp(E[X]) when X has non-zero variance (Jensen’s inequality).
• Draw-wise conversion preserves the full posterior distribution on the KPI scale.
• Summary statistics (mean, quantiles) computed after conversion correctly reflect KPI-scale uncertainty.

Practical guidance

• Use identity-response models when the KPI is naturally additive and coefficients should represent unit changes.
• Use log-response models when the KPI is naturally multiplicative, when variance scales with level, or when the response must remain positive.
• Always check response_scale_label(model) before interpreting coefficient magnitudes.
• Do not call log-response coefficients elasticities unless the predictor is also logged. In log(kpi) ~ x, they are semilog coefficients.
• For KPI-scale percentage interpretation, use 100 * (exp(beta) - 1), not 100 * beta, unless the coefficient is small enough that the approximation is acceptable.
• Use fitted_kpi() for business reporting; use fitted() for diagnostics.
• Do not manually exponentiate posterior means from log-response models. Use fitted_kpi() or to_kpi_scale() on individual draws.

Cross-references

• Model Classes — constructor and formula conventions
• Priors and Boundaries — scale interaction with priors
• Diagnostics Gates — diagnostics computed on model scale
• Config Schema — target.*, media, controls, and model.scale keys

CRE / Mundlak

Purpose

The correlated random effects (CRE) pathway, implemented as a Mundlak device, augments hierarchical DSAMbayes models with group-mean terms. This separates within-group variation from between-group variation for selected regressors, reducing confounding bias when group-level means are correlated with the random effects.

When to use CRE

Use CRE when:

• The model is hierarchical (panel data with (term | group) syntax).
• Time-varying regressors (e.g. media spend) have group-level means that may be correlated with the group intercept or slope.
• You want to decompose effects into within-group (temporal) and between-group (cross-sectional) components.

Do not use CRE when:

• The model is BLM or pooled (CRE requires hierarchical class).
• The panel has only one group (no between-group variation exists).
• All regressors of interest are time-invariant (CRE mean terms would be constant).

Construction

CRE is applied after model construction via set_cre():

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

What set_cre() does

1. Resolves the grouping variable. If the formula has one group factor, it is used automatically. If multiple group factors exist, the group argument must be specified explicitly.

2. Generates group-mean column names. For each variable in vars, a mean-term column is named cre_mean_<variable> (configurable via prefix).

3. Augments the data. apply_cre_data() computes group-level means of each CRE variable and joins them back to the panel data as new columns.

4. Updates the formula. The generated mean terms are appended to the population formula as fixed effects.

5. Extends priors and boundaries. Default prior and boundary entries are added for each new mean term, matching the existing prior schema.

YAML runner configuration

When using the runner, CRE is configured via:

model:
  type: cre

hierarchy:
  group: market
  random_intercept: true
  random_slopes: []
  cre_variables: [m_tv, m_search, m_social]
  cre_prefix: cre_mean_

The runner calls set_cre() during model construction for model.type: cre.

Mundlak decomposition

For a regressor $x_{gt}$ (group $g$, time $t$), the Mundlak device decomposes the effect into:

• Within-group effect: the coefficient on $x_{gt}$ in the population formula captures temporal variation after conditioning on the group mean.
• Between-group effect: the coefficient on $\bar{x}_g$ (the CRE mean term) captures cross-sectional variation in group-level averages.

The original coefficient on $x_{gt}$ in a standard random-effects model conflates both sources. Adding $\bar{x}_g$ as a fixed effect separates them.

Validation and identification warnings

Input validation

set_cre() validates:

• The model is hierarchical (aborts for BLM or pooled).
• All vars are present in the data and are numeric.
• The group variable exists in the formula’s group factors.
• No CRE mean terms appear in random-slope blocks (would cause double-counting).

Identification warnings

warn_cre_identification() checks two conditions after CRE setup:

1. More CRE variables than groups. If length(vars) > n_groups, between-effect estimates may be weakly identified. The function emits a warning.

2. Near-zero within-group variation. For each CRE variable, the within-group residual ($x_{gt} - \bar{x}_g$) standard deviation is checked. If it is effectively zero, within-effect identification is weak. The function emits a per-variable warning.

Zero-variance CRE mean terms

If a CRE mean term has zero variance across all observations (possible when the underlying variable has identical group means), calculate_scaling_terms() in R/scale.R will abort when scale=TRUE. The error message identifies the constant CRE columns and suggests using model.type: re (without CRE) or model.scale: false as workarounds.

Panel assumptions

• Balanced panels are not required. apply_cre_data() computes group means using dplyr::group_by() and mean(), which handles unequal group sizes.
• Missing values in CRE variables are excluded from the group-mean calculation (na.rm = TRUE).
• Group-mean recomputation. CRE mean columns are recomputed each time apply_cre_data() is called, including during prep_data_for_fit.hierarchical(). Existing CRE mean columns are dropped and regenerated to prevent stale values.

Decomposition and reporting

CRE mean terms appear as ordinary fixed-effect terms in the population formula. This means:

• Posterior summary includes CRE mean-term coefficients alongside other population coefficients.
• Response decomposition via decomp() attributes fitted-value contributions to CRE mean terms separately from their within-group counterparts.
• Plots (posterior forest, prior-vs-posterior) include CRE mean terms.

Interpretation note: the CRE mean-term coefficient represents the between-group effect conditional on the within-group variation. It does not represent the total effect of the underlying variable.

Cross-references

• Model Classes — hierarchical class construction
• Priors and Boundaries — prior schema for CRE terms
• Config Schema — model.type: cre and hierarchy.* YAML keys
• Diagnostics Gates — within-group variation check

Time Components

Purpose

DSAMbayes provides managed time-component generation through the effects.holidays config section. When enabled, the runner deterministically generates holiday feature columns from a calendar file and appends them to the compiled model formula. This page defines the configuration contract, generation logic, naming conventions, and audit properties.

Overview

Time components in DSAMbayes cover:

• Holidays — deterministic weekly indicator features derived from an external calendar file.
• Trend and seasonality — specified directly in the model formula (e.g. t_scaled, sin52_1, cos52_1). These are not generated by the time-components system; they are user-supplied columns in the data.

The managed-effects system is responsible only for holiday feature generation.

YAML configuration

effects:
  holidays:
    enabled: true
    path: ../data/holidays.csv
    date_col: null
    label_col: holiday
    country: gb
    country_col: country
    date_format: null
    week_start: monday
    timezone: UTC
    prefix: holiday_
    window_before: 0
    window_after: 0
    aggregation_rule: count
    overlap_policy: count_all
    overwrite_existing: false

Key definitions

Calendar file contract

The holiday calendar is a CSV (or data frame) with at minimum:

Date column detection

If date_col is null, the system tries column names in order: date, ds, event_date. If none is found, validation aborts.

Label normalisation

Holiday labels are normalised to lowercase, alphanumeric-plus-underscore form via normalise_holiday_label(). For example:

• Black Friday → black_friday
• New Year's Day → new_year_s_day
• Empty labels → unnamed

The generated feature column name is {prefix}{normalised_label}, e.g. holiday_black_friday.

Generation pipeline

The runner calls build_weekly_holiday_features() with the following steps:

1. Parse and validate the calendar. validate_holiday_calendar() checks column presence, date parsing, and label completeness.

2. Expand holiday windows. expand_holiday_windows() replicates each event row across the [event_date - window_before, event_date + window_after] range.

3. Align to weekly index. Each expanded event-day is mapped to its containing week using week_floor_date() with the configured week_start.

4. Aggregate per week. Events are counted per week per feature. Under aggregation_rule: any, counts are collapsed to binary (0/1). Under overlap_policy: dedupe_label_date, duplicate label-date pairs within a week are removed before counting.

5. Join to model data. The generated feature matrix is left-joined to the model data by the date column. Weeks with no events receive zero.

6. Append to formula. Generated feature columns are appended as additive terms to the compiled population formula.

Weekly anchoring

All weekly alignment uses week_floor_date(), which computes the most recent occurrence of week_start on or before each date. The model data’s date column must contain week-start-aligned dates; normalise_weekly_index() validates this and aborts if dates are not aligned.

Supported week-start values

monday, tuesday, wednesday, thursday, friday, saturday, sunday.

Timezone handling

• Calendar dates are parsed using the configured timezone (default UTC).
• If the calendar contains POSIXt values, they are coerced to Date in the configured timezone.
• Character dates are parsed as ISO 8601 by default, or using date_format if specified.