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. Create repo-local library and cache directories
mkdir -p .Rlib .cache

# 2. Set environment variables (add to .bashrc/.zshrc for persistence)
export R_LIBS_USER="$PWD/.Rlib"
export XDG_CACHE_HOME="$PWD/.cache"

# 3. Install DSAMbayes from the local checkout
R_LIBS_USER="$PWD/.Rlib" 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.

Verify the installation

1. Confirm DSAMbayes loads

R_LIBS_USER="$PWD/.Rlib" R -q -e 'library(DSAMbayes); cat("Version:", as.character(utils::packageVersion("DSAMbayes")), "\n")'

Expected: prints Version: 1.2.2 (or current version).

2. Confirm the runner works

R_LIBS_USER="$PWD/.Rlib" Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml

Expected: validation completes without errors.

3. (Optional) Run the test suite

R_LIBS_USER="$PWD/.Rlib" 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.2.2 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

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml

2. Execute a full run

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.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 .Rlib exists and is writable: ls -la .Rlib.
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 (or leave default false — v1.2.2 auto-detects stale caches).

Permission issues

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

Actions:

1. Ensure .Rlib, .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

What is DSAMbayes?

DSAMbayes is an R package that fits Bayesian marketing mix models (MMM) using Stan. It provides a familiar lm()-style interface for specifying models, adds prior and boundary controls, and delegates estimation to Stan’s Hamiltonian Monte Carlo (HMC) sampler. The result is a full posterior distribution over model parameters — not just point estimates — enabling rigorous uncertainty quantification for media contribution and budget allocation decisions.

Why Bayesian MMM?

Classical OLS regression gives point estimates and confidence intervals that assume the model is correctly specified. In MMM, where media variables are collinear, sample sizes are small (often 100–200 weeks), and the functional form is uncertain, these assumptions are routinely violated.

Bayesian estimation addresses this by:

• Regularisation through priors — weakly informative priors stabilise estimates when the data alone cannot separate correlated effects. This is particularly valuable for media channels with overlapping campaign timing.
• Hard parameter constraints — boundary constraints (e.g. media coefficients must be non-negative) are enforced directly in the posterior, rather than post-hoc.
• Full uncertainty propagation — every downstream output (fitted values, decomposition, budget allocation) carries the full posterior uncertainty, not just a point estimate ± standard error.
• Principled model comparison — leave-one-out cross-validation (LOO-CV) via Pareto-smoothed importance sampling provides predictive model comparison without refitting.

Model classes

DSAMbayes supports three model classes, all sharing the same post-fit interface:

BLM (Bayesian Linear Model)

The simplest class. One market, one response variable, one set of predictors. Equivalent to lm() but with Bayesian estimation.

kpi ~ trend + seasonality + holidays + media_channels

Use when: single-market modelling with sufficient data (typically 100+ weeks).

Hierarchical

Panel data with multiple groups (e.g. markets, regions, brands). Random effects allow each group to deviate from the population average while sharing information across groups (partial pooling).

kpi ~ population_terms + (varying_terms | group)

Use when: multi-market data where you want to borrow strength across markets while allowing market-specific effects.

Pooled

Single-market data where media variables have a nested structure (e.g. campaign > channel > platform). Coefficients are pooled across labelled dimensions.

blm(formula, data) %>% pool(grouping_vars, variable_map)

Use when: single-market data with structured media hierarchies.

The estimation pipeline

Every DSAMbayes model follows the same lifecycle:

1. Construct — blm() creates an unfitted model object with default priors and boundaries.
2. Configure — set_prior(), set_boundary(), set_cre() adjust the specification.
3. Fit — fit() (MCMC) or optimise() (MAP) estimates the posterior.
4. Extract — get_posterior(), fitted(), decomp() retrieve results.
5. Decide — optimise_budget() translates estimates into budget allocation recommendations.

Key concepts for practitioners

Priors

A prior distribution encodes what you believe about a parameter before seeing the data. In DSAMbayes:

• Default priors are normal(0, 5) — weakly informative, centred at zero.
• Informative priors can be set when domain knowledge justifies it (e.g. price_index ~ normal(-0.2, 0.1) if you know price has a small negative effect).
• Priors are specified using formula notation: set_prior(model, m_tv ~ normal(0, 10)).

Boundaries

Hard constraints on parameter values. The posterior density is zero outside the boundary:

• set_boundary(model, m_tv > 0) forces the TV coefficient to be non-negative.
• Default boundaries are unconstrained (-Inf, Inf).

MCMC vs MAP

• MCMC (fit()) draws samples from the full posterior distribution. Slower but gives complete uncertainty quantification. Use for final reporting.
• MAP (optimise()) finds the single most probable parameter vector. Much faster but gives only a point estimate. Use for rapid iteration during model development.

Response scale

Models can operate on the original KPI scale (identity response) or the log scale:

• Identity: kpi ~ ... — coefficients represent unit changes in KPI.
• Log: log(kpi) ~ ... — coefficients represent approximate percentage changes.

Log-response models require careful back-transformation to the KPI scale. DSAMbayes handles this automatically via fitted_kpi(). See Response Scale Semantics.

Diagnostics

After fitting, DSAMbayes runs a battery of diagnostic checks:

• Sampler quality — Rhat, effective sample size, divergences.
• Residual behaviour — autocorrelation, normality, Ljung-Box test.
• Identifiability — baseline-media correlation.
• Boundary monitoring — share of draws hitting constraints.

Each check produces a pass, warn, or fail status. See Diagnostics Gates.

The YAML runner

For reproducible, configuration-driven runs, DSAMbayes provides a CLI runner:

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

The runner reads a YAML file specifying the data, formula, priors, boundaries, fit settings, diagnostics policy, and optional budget optimisation. It writes structured artefacts (CSVs, plots, model objects) to a timestamped directory under results/. See CLI Usage and Config Schema.

Further reading

• Your First BLM Model — hands-on R API walkthrough
• Model Classes — detailed class comparison
• Priors and Boundaries — prior schema and scaling behaviour
• Budget Optimisation — decision-layer API

Your First BLM Model

Goal

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

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

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 %>% optimise(n_runs = 10)
get_posterior(map_model)

Use MCMC for final reporting; MAP for formula iteration.

Common pitfalls

Next steps

• Run via YAML for reproducible runs: Run from YAML
• Interpret diagnostics: Interpret Diagnostics
• 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.

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

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:

mkdir -p .Rlib .cache
export R_LIBS_USER="$PWD/.Rlib"
export XDG_CACHE_HOME="$PWD/.cache"

2. Validate the configuration (dry run)

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml

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

3. Execute the full run

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.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.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 — each row is one diagnostic check:

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

• pass — no action needed.
• warn — review recommended; see Interpret Diagnostics.
• fail — remediate before using results for decisions.

8. Bootstrap a new config

Generate a template for your own data:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R init --template blm --out config/my_model.yaml

Edit config/my_model.yaml to point to your data and formula, then validate and run.

If the quickstart fails

• Re-run validate before run to catch config errors early.
• Check the error message — DSAMbayes uses cli::cli_abort() with descriptive context.
• Inspect 00_run_metadata/config.resolved.yaml to see what defaults were applied.
• See Debug Run Failures for common failure modes.

Next steps

• Your First BLM Model — interactive R API walkthrough
• Config Schema — full YAML reference
• Output Artefacts — what each file means
• Plot Catalogue — how to interpret every plot

FAQ

Installation and setup

How long does the first Stan compilation take?

1–3 minutes on most machines. Subsequent runs use a cached binary and start sampling immediately. If compilation seems stuck, check your C++ toolchain — see Install and Setup.

Do I need to set R_LIBS_USER every time?

Yes, unless you add it to your shell profile (.bashrc, .zshrc, or equivalent). The repo-local .Rlib path keeps DSAMbayes and its dependencies isolated from your system R library.

Can I use renv instead of .Rlib?

Yes. The repository includes a renv.lock file. Run renv::restore() to install exact dependency versions. See the renv section in Install and Setup.

Modelling

How many weeks of data do I need?

There is no hard minimum, but as a rough guide:

• BLM: 100+ weeks for a model with 10–15 predictors. Below 80 weeks, most media effects will be prior-driven.
• Hierarchical: 80+ weeks per group, ideally with 4+ groups for meaningful partial pooling.

More data is always better. Short series with many predictors will lean heavily on priors.

Should I use identity or log response?

• Identity (kpi ~ ...) when the KPI is naturally additive and variance is roughly constant across levels. Coefficients represent absolute unit changes.
• Log (log(kpi) ~ ...) when the KPI is strictly positive, variance scales with level, or you want multiplicative (percentage) effects. Common for revenue and sales.

If unsure, fit both and compare diagnostics.

How many MCMC iterations do I need?

The defaults (iter = 2000, warmup = 1000, chains = 4) are a reasonable starting point. Check diagnostics after fitting:

• Rhat < 1.01 and ESS > 400 → iterations are sufficient.
• Rhat > 1.05 or ESS < 200 → increase iter and warmup (e.g. double both).
• Divergences > 0 → increase adapt_delta (e.g. 0.95 → 0.99) before increasing iterations.

For rapid iteration during development, use MAP estimation (optimise()) instead of MCMC.

When should I set boundaries on media coefficients?

Set m_channel > 0 when you are confident that additional media exposure cannot decrease the KPI. This is the most common boundary specification in MMM. Do not set boundaries on control variables (trend, seasonality, price) unless you have a clear structural reason — see the Minimal-Prior Policy.

When should I use CRE (Mundlak)?

Use CRE when fitting a hierarchical model where:

1. Time-varying regressors (e.g. media spend) have group-level means correlated with unobserved group heterogeneity.
2. You want to separate within-group (temporal) effects from between-group (cross-sectional) effects.

CRE adds group-mean terms to the population formula. See CRE / Mundlak.

What does scale = TRUE do?

It standardises the response and predictors (centre and divide by SD) before passing them to Stan. This improves sampler efficiency by putting all coefficients on a comparable scale. Post-fit, get_posterior() back-transforms coefficients to the original data scale automatically. Leave it on (the default) unless you have a specific reason to disable it.

Runner and outputs

How long does a typical run take?

First-time Stan compilation adds 1–3 minutes.

What is the difference between validate and run?

• validate checks config structure, data paths, formula validity, and cross-field constraints — without compiling or fitting Stan models. Use it as a pre-run gate.
• run does everything validate does, then compiles, fits, runs diagnostics, and writes artefacts.

Always validate before run when you change config or data.

Where do outputs go?

By default, under results/<timestamp>_<model_name>/ with numbered stage folders. See Output Artefacts for the full contract.

How do I compare two model runs?

Use compare_runs() in R or compare 50_model_selection/loo_summary.csv files manually. See Compare Runs.

Diagnostics

What does “Pareto-k > 0.7” mean?

It means the PSIS-LOO approximation is unreliable for that observation — the observation is highly influential. A few amber (0.5–0.7) points are normal. Red (> 0.7) points warrant investigation. See Model Selection Plots.

My diagnostics say “warn” — should I worry?

It depends on the policy mode:

• explore — warnings are expected during development. Continue iterating.
• publish — review warnings before sharing results. Most warns are acceptable if you understand the cause.
• strict — warnings require documented justification.

See Diagnostics Gates for threshold details.

Budget optimisation

How does the allocator work?

It generates feasible spend allocations within channel bounds, evaluates each against the posterior, and selects the allocation that maximises the chosen objective (KPI uplift or profit). It is a Monte Carlo search, not an analytical optimiser. See Budget Optimisation.

Can I use budget optimisation with MAP-fitted models?

Yes, but the results will be based on a single point estimate rather than the full posterior distribution. Uncertainty intervals will not be meaningful.

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 and available in R_LIBS_USER.

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)

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/blm_synthetic_mcmc.yaml

Expected outcome: validation completes without fitting Stan models.

Validate with explicit run directory

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate \
    --config config/blm_synthetic_mcmc.yaml \
    --run-dir results/quickstart_validate

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

Execute full run

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/blm_synthetic_mcmc.yaml

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

Execute full run with explicit run directory

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run \
    --config config/blm_synthetic_mcmc.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

• Success exits with status 0.
• CLI argument or runtime errors exit with status 2.
• 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 defines the YAML contract used by:

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

It documents defaults, allowed values, and cross-field constraints enforced by the runner.

Schema processing order

The runner processes config in this order:

1. Parse YAML.
2. Coerce YAML infinity tokens (.Inf, -.Inf).
3. Apply defaults (resolve_config_defaults()).
4. Resolve relative paths against the config file directory (resolve_config_paths()).
5. Validate values and cross-field constraints (validate_config()).
6. Validate formula safety unless security.allow_unsafe_formula: true.

Root sections

Minimal valid config

schema_version: 1

data:
  path: data/your_data.csv
  format: csv

model:
  formula: y ~ x1 + x2

Expected outcome: this resolves with defaults for all omitted sections and passes schema validation if the file exists and formula variables exist in data.

Section reference

schema_version

data

Long-format-specific rules:

• data.long_id_col, data.long_variable_col, data.long_value_col, and data.date_var must all be set.
• These four column names must be distinct.
• Long data is reshaped wide before modelling and duplicate key rows are rejected.

model

Model type resolution rules:

• auto resolves to pooled if pooling.enabled: true.
• auto resolves to cre if cre.enabled: true.
• auto resolves to re if formula contains bar terms (for example (1 | group)).
• auto resolves to blm otherwise.
• re or cre requires bar terms in formula.
• blm or pooled cannot be used with bar terms.

cre

pooling

Pooling map requirements at model-build time:

• Must include a variable column.
• Must include every column named in pooling.grouping_vars.
• variable values must be unique.

transforms

Each sensitivity scenario requires:

• name (unique, non-empty, not base)
• formula (safe formula string unless unsafe mode is enabled)

priors

Prior override row contract:

• parameter (string, must exist in model prior table)
• family (normal or lognormal_ms, default normal)
• mean (numeric)
• sd (numeric, > 0)

lognormal_ms extra constraints:

• mean > 0
• allowed only for noise_sd and parameters matching sd_<index>[<term>]

boundaries

Boundary override row contract:

• parameter (string, must exist in model boundary table)
• lower (numeric, default -Inf)
• upper (numeric, default Inf)

time_components

fit

Allowed keys under fit.optimise:

• n_runs, iter, seed, init, algorithm, hessian, as_vector

Allowed keys under fit.mcmc:

• chains, iter, warmup, thin, cores, refresh, seed, init, control, parameterization

Allowed keys under fit.mcmc.parameterization:

• positive_priors

allocation

Channel row contract (allocation.channels[]):

• term required, scalar string, unique across channels.
• name optional, defaults to term, must be unique.
• spend_col optional, defaults to name.
• bounds.min optional, defaults 0, must be finite and >= 0.
• bounds.max optional, defaults Inf, but operationally must be finite and >= bounds.min.
• currency_col optional.
• response optional mapping:
  • type: identity (default)
  • type: atan requires positive scale
  • type: log1p requires positive scale
  • type: hill requires positive k and positive n

Log-response runtime rules:

• scenario: target_efficiency requires allocation.objective.kpi_baseline.
• Other scenarios require kpi_baseline unless allow_relative_log_uplift: true.

outputs

Path keys:

Save toggles (all booleans):

Run directory precedence:

1. CLI --run-dir / run_from_yaml(..., run_dir=...)
2. outputs.run_dir
3. Timestamped directory under outputs.root_dir

forecast

diagnostics

diagnostics.model_selection:

diagnostics.time_series_selection:

Time-series selection constraints:

• Requires fit.method: mcmc.
• Not supported for pooled runs.
• Requires data.date_var set and present in data.

diagnostics.identifiability:

security

Safe formula calls when unsafe mode is disabled:

• Operators: ~, +, -, *, /, ^, :, |, (
• Functions: log, exp, sqrt, atan, sin, cos, tan, I, offset, pmax, pmin, abs
• Namespaced calls: dplyr::lag, dplyr::lead

Recommended authoring workflow

1. Generate a template:

Rscript scripts/dsambayes.R init --template master --out config/my_run.yaml

2. Validate before running:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R validate --config config/my_run.yaml

3. Execute:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript scripts/dsambayes.R run --config config/my_run.yaml

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 (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 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

Implementation note:

• decomp_predictor_impact.csv, decomp_predictor_impact.png, decomp_timeseries.csv, and decomp_timeseries.png are present in stage mapping and config flags, but are not currently invoked by write_run_artifacts() in the active pipeline.

40_diagnostics

50_model_selection

60_optimisation

70_forecast

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 = point_exp for fit.method: optimise.
• fitted_kpi.csv uses conversion_method = drawwise_exp for fit.method: mcmc.

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.

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. 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 not supported for pooled models (rejected by config validation).

Class selection guide

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.

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

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.

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

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.

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.

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.

When use_defaults: false, the default prior table is not generated. This is not recommended for typical use.

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

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?

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.

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.
• 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 — model.formula 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:

cre:
  enabled: true
  vars: [m_tv, m_search, m_social]
  group: market
  prefix: cre_mean_

The runner calls set_cre() during model construction if cre.enabled: true.

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 — cre.* YAML keys
• Diagnostics Gates — within-group variation check

Time Components

Purpose

DSAMbayes provides managed time-component generation through the time_components config section. When enabled, the runner deterministically generates holiday feature columns from a calendar file and optionally appends them to the 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 time_components system is responsible only for holiday feature generation.

YAML configuration

time_components:
  enabled: true
  holidays:
    enabled: true
    calendar_path: data/holidays.csv
    date_col: null          # auto-detected: date, ds, or event_date
    label_col: holiday
    date_format: null       # null = ISO 8601; or e.g. "%d/%m/%Y"
    week_start: monday
    timezone: UTC
    prefix: holiday_
    window_before: 0
    window_after: 0
    aggregation_rule: count # count | any
    overlap_policy: count_all # count_all | dedupe_label_date
    add_to_formula: true
    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. If add_to_formula: true, generated feature columns are appended as additive terms to the 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.

Generated-term audit contract

Generated holiday terms are tracked for downstream diagnostics and reporting:

• The list of generated term names is stored in model$.runner_time_components$generated_terms.
• The identifiability gate in R/diagnostics_report.R uses this list to auto-detect baseline terms (via detect_baseline_terms()), so generated holiday terms are included in baseline-media correlation checks without requiring explicit configuration.

Feature naming collision

If two different holiday labels normalise to the same feature name, build_weekly_holiday_features() aborts with a collision error. Ensure calendar labels are distinct after normalisation.

Interaction with existing data columns

• If overwrite_existing: false (default), the runner aborts if any generated column name already exists in the data.
• If overwrite_existing: true, existing columns with matching names are replaced by the generated features.

Practical guidance

• Start with aggregation_rule: count to capture multi-day holiday effects (e.g. a holiday spanning two days in one week produces a count of 2).
• Use window_before and window_after for events with known anticipation or lingering effects (e.g. window_before: 7 for pre-Christmas shopping).
• Use aggregation_rule: any when you want binary holiday indicators regardless of how many event-days fall in a week.
• Check generated terms in the resolved config (config.resolved.yaml) and posterior summary to confirm which holidays entered the model.

Cross-references

• Config Schema — time_components.* YAML keys
• Diagnostics Gates — identifiability gate uses generated terms
• Priors and Boundaries — priors for generated holiday terms follow default schema
• Output Artefacts — resolved config records generated terms

Diagnostics Gates

Purpose

DSAMbayes runs a deterministic diagnostics framework after model fitting. Each diagnostic check produces a pass, warn, or fail status. The policy mode controls how lenient or strict the thresholds are. This page defines the check taxonomy, threshold tables, policy modes, identifiability gate, and the overall status aggregation rule.

Policy modes

The diagnostics framework supports three policy modes, configured via diagnostics.policy_mode in YAML:

The mode is resolved by diagnostics_policy_thresholds(mode) in R/diagnostics_report.R.

Check taxonomy

Checks are organised into phases:

Each check row includes:

P0 design checks

Condition number thresholds by mode

P1 sampler checks (MCMC only)

Mode adjustments for sampler checks

In explore mode, fail thresholds are substantially relaxed (e.g. rhat_fail = 1.10, ess_bulk_fail = 50). In strict mode, warn thresholds match publish fail thresholds.

P1 residual checks

Mode adjustments for residual checks

P1 boundary hit check

In explore mode, boundary hits cannot fail. In strict mode, thresholds tighten to warn > 0.02, fail > 0.10.

P1 within-group variation check

This check applies to hierarchical models and flags groups where within-group variation is extremely low relative to between-group variation. In explore mode, the fail threshold is zero (cannot fail).

Identifiability gate

The identifiability gate measures the maximum absolute correlation between baseline terms and media terms in the design matrix. It is configured via diagnostics.identifiability in YAML:

diagnostics:
  identifiability:
    enabled: true
    media_terms: [m_tv, m_search, m_social]
    baseline_terms: [trend, seasonality]
    baseline_regex: ["^h_", "^sin", "^cos"]
    abs_corr_warn: 0.80
    abs_corr_fail: 0.95

Term detection

• Media terms: explicitly listed in media_terms.
• Baseline terms: union of baseline_terms, generated time-component terms, and matches from baseline_regex patterns.
• Both sets are intersected with actual design-matrix columns and filtered to remove constant columns.

Thresholds by mode

Skip conditions

The identifiability gate reports skipped when:

• identifiability.enabled: false
• No configured media terms found in the design matrix
• No baseline terms detected from configured terms/regex
• All resolved baseline or media terms are constant

Overall status aggregation

The overall diagnostics status is determined by diagnostics_overall_status():

1. If any check has status == "fail" → overall status is fail.
2. If any check has status == "warn" (and none fail) → overall status is warn.
3. Otherwise → overall status is pass.

Checks with status == "skipped" do not affect the overall status.

Runner artefact output

The diagnostics framework produces:

Interpretation guidance

• pass — no remediation needed; model is suitable for the configured policy mode.
• warn — review recommended; the model may have quality concerns but does not block the configured policy.
• fail — remediation required before the model can be considered production-ready under the configured policy.

Common remediation actions

Cross-references

• Model Classes — which diagnostics apply to each class
• Response Scale Semantics — residuals are computed on model scale
• Config Schema — diagnostics.* YAML keys
• Output Artefacts — diagnostics artefact paths
• Diagnostics Plots — visual diagnostic outputs

Budget Optimisation

Purpose

DSAMbayes provides a decision-layer budget optimisation engine that operates on fitted model posteriors. Given a channel scenario with spend bounds, response-transform specifications, and an objective function, the engine searches for the allocation that maximises the chosen objective while respecting channel-level constraints. This page defines the inputs, objectives, risk scoring, response-scale handling, and output structure.

Overview

Budget optimisation is separate from parameter estimation. It takes a fitted model and a scenario specification, then:

1. Extracts posterior coefficient draws for the scenario’s channel terms.
2. Generates feasible candidate allocations within channel bounds that sum to the total budget.
3. Evaluates each candidate across all posterior draws to obtain a distribution of KPI outcomes.
4. Ranks candidates by the configured objective and risk scoring function.
5. Returns the best allocation, channel-level summaries, response curves, and impact breakdowns.

Entry point

result <- optimise_budget(model, scenario, n_candidates = 2000L, seed = 123L)

The optimize_budget() alias is also available for American English convention.

Scenario specification

The scenario is a structured list with the following top-level keys:

channels

A list of channel definitions, each containing:

Channel names and terms must be unique across the scenario.

budget_total

Total budget to allocate across all channels. All feasible allocations sum to this value.

reference_spend

Optional named list of per-channel reference spend values. If not provided, reference spend is estimated from the mean of the spend_col in the model’s original data.

objective

Defines the optimisation target and risk scoring:

Response transforms

Each channel can specify a response transform that maps raw spend to the transformed value used in the linear predictor. Supported types:

The response transform is applied within response_transform_value() and determines the shape of the channel’s response curve.

Objective functions

kpi_uplift

Maximises the expected change in KPI relative to the reference allocation. The metric for each candidate is:

evaluated across posterior draws $d$.

profit

Maximises expected profit, defined as:

where $\Delta\text{spend} = \text{candidate total} - \text{reference total}$.

Risk-aware scoring

The risk scoring function determines how the distribution of objective draws is summarised into a single score for ranking candidates: