Modelling — DSAMbayes Documentation

Model Classes

Mon, 01 Jan 0001 00:00:00 +0000

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 Class S3 class chain Constructor Data structure Grouping Typical use case BLM blm blm(formula, data) Single market/brand None One-market regression with full prior and boundary control Hierarchical hierarchical, blm blm(formula, data) with (term | group) syntax Panel (long format) Random effects by group Multi-market models sharing strength across groups Pooled pooled, blm pool(blm_obj, grouping_vars, map) Single market Structured coefficient pooling via dimension map Single-market models with media coefficients pooled across labelled dimensions 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.

Model Object Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

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 State Entry point Fields populated Created blm(), blm.formula(), blm.lm(), as_bayes_lm_updater() .formula, .original_data, .prior, .boundaries, .response_transform, .response_scale Configured set_prior(), set_boundary(), set_date() Mutates .prior, .boundaries, .date_var Pooled pool(obj, grouping_vars, map) Adds .pooling_vars, .pooling_map; resets .prior, .boundaries; class becomes pooled Compiled compile_model(obj) .stan_model Pre-flighted pre_flight_checks(obj, data) .response_transform, .response_scale; auto-sets .stan_model, .date_var if missing Fitted fit(obj) / fit_map(obj) .stan_data, .date_val, .posterior Post-fit accessors These functions require a fitted model (.posterior is not NULL):

Priors and Boundaries

Mon, 01 Jan 0001 00:00:00 +0000

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:

Minimal-Prior Policy

Mon, 01 Jan 0001 00:00:00 +0000

Purpose Use a principled but low-friction prior setup that avoids specification-hunting while preserving identifiability in short, collinear MMM datasets. Policy Default-first: keep priors.use_defaults: true. Sparse overrides: only add priors.overrides for high-conviction terms. Selective bounds: add boundaries.overrides only for structural signs. No blanket constraints: do not force all controls/media to one sign by default. 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

Mon, 01 Jan 0001 00:00:00 +0000

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:

CRE / Mundlak

Mon, 01 Jan 0001 00:00:00 +0000

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:

Time Components

Mon, 01 Jan 0001 00:00:00 +0000

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:

Diagnostics Gates

Mon, 01 Jan 0001 00:00:00 +0000

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:

Budget Optimisation

Mon, 01 Jan 0001 00:00:00 +0000

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: