Appendices

Purpose

Provide reference material that supports core user guidance without duplicating operational instructions.

Audience

  • Readers needing precise terminology definitions
  • Engineers orienting themselves in R/ source modules
  • Reviewers validating implementation traceability

Pages

Usage rules

  1. Use appendices as reference pages, not primary process documentation.
  2. Keep operational runbooks in docs/getting-started/, docs/runner/, and docs/internal/.
  3. Prefer links to authoritative sources instead of duplicating constraints or commands.

Subsections of Appendices

Glossary

Purpose

Define canonical terms used across DSAMbayes modelling, runner, diagnostics, and release documentation.

How to use this glossary

  1. Use these definitions when writing or reviewing DSAMbayes documentation.
  2. Keep term usage consistent across docs/modelling/, docs/runner/, and docs/internal/.
  3. If a term changes behaviour in code, update this page in the same change.

Terms

Term Definition Primary location
adstock Media carry-over transform that spreads spend effect over subsequent periods. Stan media-transform templates and modelling docs
allocation Post-fit budget optimisation stage (allocation.* in YAML). docs/runner/config-schema.md
artefact File written by runner validate/run workflows. docs/runner/output-artifacts.md
baseline term Non-media explanatory term (for example trend, seasonality, holiday controls). docs/modelling/diagnostics-gates.md
blm Base DSAMbayes model class for non-pooled regression workflows. R/blm.R
blocked CV Expanding-window time-series cross-validation used for model selection. R/time_series_cv.R
boundary Lower and upper constraints on model parameters. docs/modelling/priors-and-boundaries.md
chain diagnostics MCMC quality diagnostics such as Rhat, ESS, and divergence indicators. R/diagnostics.R
config resolution Process of applying defaults, coercions, path normalisation, and validation to YAML. R/run_config_*.R
CRE Correlated random effects approach using Mundlak-style within and between variation terms. R/cre_mundlak.R
decomp Post-fit decomposition of fitted response into predictor-level contributions. R/decomp.R
diagnostics gate Thresholded pass/warn/fail policy checks over model diagnostics. R/diagnostics_report.R
divergence Stan sampler warning indicating problematic Hamiltonian trajectories. MCMC diagnostics outputs
dry run Runner mode that validates config and data without Stan fitting (validate). scripts/dsambayes.R
ELPD Expected log predictive density, used for predictive model comparison. R/compare_runs.R
ESS Effective sample size for MCMC draws. Higher is generally better. Chain diagnostics outputs
fit MCMC fitting path (fit.method: mcmc). R/run_from_yaml.R
fit_map / optimise MAP optimisation path (fit.method: optimise). R/blm.R, R/hierarchy.R, R/pooled.R
hierarchical Model class with grouped random effects (`(term group)` syntax).
identifiability check Diagnostic check for baseline and media term correlation risk. R/diagnostics_report.R
kpi scale Business-outcome scale used for reporting. For log-response models this is back-transformed from model scale. docs/modelling/response-scale-semantics.md
lognormal_ms Positive-support prior family parameterised by mean and standard deviation on the original scale. R/prior_schema.R
MAP Maximum a posteriori point estimate from optimisation. Not a posterior mean. fit_map paths
MCMC Markov chain Monte Carlo posterior sampling. rstan::sampling paths
Pareto-k PSIS-LOO reliability diagnostic for influence of observations. loo_summary.csv outputs
pooled Model class with structured pooling over configured grouping variables. R/pooled.R
posterior draw One sampled value from the posterior distribution. get_posterior() outputs
pre-flight checks Guardrails and model/data compatibility checks run before fitting. R/pre_flight.R
prior_only Fit mode sampling only from priors, excluding likelihood learning. prep_data_for_fit.* interfaces
PSIS-LOO Pareto-smoothed importance-sampling leave-one-out approximation. R/diagnostics_report.R
QG-1 to QG-7 Canonical release quality gates for lint, style, tests, package check, runner smoke, and docs build. docs/internal/quality-gates.md
response scale Scale used inside the fitted model (identity or log). docs/modelling/response-scale-semantics.md
Rhat Convergence diagnostic comparing within- and between-chain variance. Chain diagnostics outputs
runner YAML/CLI execution layer around core DSAMbayes APIs. scripts/dsambayes.R, R/run_from_yaml.R
run_dir Output directory used by a runner validate/run execution. docs/runner/output-artifacts.md
staged layout Structured artefact layout with numbered folders (00_ to 70_). docs/runner/output-artifacts.md
Stan cache Compiled model cache location, typically under XDG_CACHE_HOME. install/setup docs
SMAPE Symmetric mean absolute percentage error metric used in fit summaries. R/stats.R
time-components Managed time control features, including holiday-derived regressors. R/holiday_calendar.R
tscv Time-series selection artefact prefix for blocked CV outputs. 50_model_selection/tscv_*.csv
warmup Initial MCMC iterations used for adaptation and excluded from posterior draws. fit.mcmc.warmup
Hill transform Saturation function spend^n / (spend^n + k^n) used in budget optimisation response curves. k is the half-saturation point, n is the shape parameter. R/optimise_budget.R
atan transform Saturation function atan(spend / scale) mapping spend to a bounded response. R/optimise_budget.R
log1p transform Saturation function log(1 + spend / scale) providing diminishing-returns concavity. R/optimise_budget.R
adstock Media carry-over transform that spreads a spend effect over subsequent periods via geometric decay. Applied as a pre-transform in the data, not estimated within DSAMbayes. Formula transforms
conditional mean Bias-corrected back-transform for log-response models: exp(mu + sigma^2/2). Default in v1.2.2 for fitted_kpi(). R/fitted.R
Jensen's inequality Mathematical property that E[exp(X)] != exp(E[X]) when X has non-zero variance. DSAMbayes avoids this bias by applying exp() draw-wise before summarising. docs/modelling/response-scale-semantics.md

R Module Index

Purpose

Provide a maintainable orientation map for R/ while preserving the flat R package layout.

Layout rule

DSAMbayes keeps a flat R/ directory. Modules are logical groupings, not folder boundaries.

Module map

Module Responsibility Primary files
Model objects and fit engines Class constructors, fit and MAP pathways, class-specific data preparation R/blm.R, R/hierarchy.R, R/pooled.R, R/model_schema.R, R/blm_compiled.R
Stan media transform support Media-transform config parsing and Stan data wiring R/media_transform_config.R
Priors, boundaries, scaling, transforms Prior parsing, boundary handling, scaling contracts, transform helpers, offsets R/prior.R, R/prior_schema.R, R/scale.R, R/scale_prior_sd.R, R/transformations.R, R/transform_sensitivity.R, R/offset.R
Formula and pre-flight validation Formula parsing/safety, data/date checks, pre-fit guardrails R/formula.R, R/formula_safety.R, R/pre_flight.R, R/date.R, R/variable.R
Diagnostics and model selection Fit diagnostics, gate logic, cross-validation, posterior predictive and metrics R/diagnostics.R, R/diagnostics_report.R, R/crossval.R, R/time_series_cv.R, R/post_pred.R, R/stats.R, R/compare_runs.R
Decomposition and extraction Decomposition APIs and extraction helpers R/decomp.R, R/decomp_prep.R, R/extract.R, R/fitted.R
Runner config and orchestration YAML defaults/coercion/validation, model orchestration, run execution R/run_config.R, R/run_config_helpers.R, R/run_config_defaults.R, R/run_config_validation.R, R/run_orchestrator.R, R/run_from_yaml.R
Runner artefacts and reporting Stage mapping and artefact writers for metadata, diagnostics, enrichment R/run_artifacts.R, R/run_artifacts_diagnostics.R, R/run_artifacts_enrichment.R, R/runner_fit_plots.R
Time components and CRE support Holiday feature engineering and CRE/Mundlak model support R/holiday_calendar.R, R/cre_mundlak.R
Budget optimisation and visual outputs Decision-layer optimisation engine and plotting APIs R/optimise_budget.R, R/optimise_budget_plots.R, R/plot_theme_wpp.R
Package infrastructure and utilities Package lifecycle hooks, utility helpers, package metadata helpers, bundled ASCII art R/zzz.R, R/utils.R, R/utils-pipe.R, R/sitrep_.R, R/data.R, R/ascii.txt

High-coupling files to review carefully

File Why it is high-coupling
R/run_from_yaml.R Central runner execution path connecting config, model build, fit, diagnostics, and artefact writing.
R/run_config_validation.R Cross-field validation rules with direct impact on runner safety and allowed contracts.
R/run_artifacts.R Artefact pathing and stage contract used by docs, CI, and release evidence workflows.
R/hierarchy.R Large class-specific fit, posterior, and scaling logic with multiple behavioural branches.
R/blm.R Base class implementation used across many tests and runner pathways.

Placement guide for new code

  1. Put new logic in the closest logical module listed above.
  2. If touching legacy compatibility files (R/run_config.R, R/run_artifacts.R), prefer adding new logic to their split companion files where possible.
  3. Keep exported function names stable unless there is an explicit API migration plan.
  4. Add or update test coverage in tests/testthat/ for any behavioural change.

Traceability Map

Purpose

Provide a traceability reference that maps DSAMbayes issues and recommendations to implementation status and evidence.

Authoritative data source

The single source of truth for all issue and recommendation status is:

  • code_review/audit_report/issue_register.csv

This register contains every ENG, INF, and GOV issue and recommendation with columns for status, severity, owner, linked IDs, notes, and a long-form explanation field.

Two stakeholder-facing summary CSVs are published alongside this page under docs/appendices/traceability-data/:

These files are derived snapshots. Where they conflict with issue_register.csv, the register takes precedence.

Snapshot metrics (as of 2026-02-28)

Non-GOV issues and recommendations

  • All ENG and INF issues: closed (including backlog items accepted and closed 2026-02-28)
  • All ENG and INF recommendations: closed / implemented

GOV issues

  • GOV-ISSUE-001 through GOV-ISSUE-004: open (governance items; resolution deferred to management review cycle)

How to use this map

  1. Start with an issue ID or recommendation ID.
  2. Open code_review/audit_report/issue_register.csv.
  3. Confirm status in the status column and review linked IDs in linked_ids.
  4. Follow evidence paths referenced in the notes column to code files, tests, and review records.
  5. Use internal engineering documentation for release decision criteria.

Representative mappings

ID Type Status Evidence anchors
ENG-ISSUE-014 Issue closed R/scale.R, tests/testthat/test-scale-guardrails.R
INF-ISSUE-006 Issue closed R/diagnostics_report.R, tests/testthat/test-diagnostics-report.R
INF-REC-004 Recommendation closed Holiday/time-components implementation and review references
ENG-REC-003 Recommendation closed Pooled RMSE and scale wiring closure references

Traceability and release approval

Traceability status alone does not authorise a release. Release sign-off still requires:

  1. Mandatory quality gates passed.
  2. Required release evidence bundle complete.
  3. Final decision recorded in sign-off template.

Docs Build and Deploy

Purpose

Describe how the DSAMbayes documentation site is built, previewed, and deployed.

Documentation layers

DSAMbayes has two documentation systems:

1. pkgdown site (R package documentation)

Generated from roxygen comments in R/ source files and vignettes in vignettes/.

Build locally:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript -e 'pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)'

CI deployment: .github/workflows/pkgdown.yaml builds and deploys to gh-pages on push to main or release events.

Output: generated site under docs/ (pkgdown output, not the Markdown docs).

2. Markdown documentation site (this site)

The docs/ directory contains hand-authored Markdown files organised into sections (Getting Started, Runner, Modelling, Plots, How-To, Appendices). These are configured via docs/docs-config.json.

Site generator: the configuration structure (docs-config.json with navigation, branding, and search settings) is designed for a static site generator. The specific generator and hosting are configured in the deployment environment.

Preview locally: open Markdown files directly, or use any Markdown preview tool. The inter-page links use root-relative paths (e.g. /getting-started/install-and-setup).

Deploy target: https://dsambayes.docs.wppma.space/ (as referenced in README.md).

Configuration

docs/docs-config.json defines:

  • metadata — site name, description, version.
  • branding — logo, favicon, primary colour.
  • navigation — navbar links and sidebar structure.
  • features — math rendering (enabled), search (local).

Adding a new page

  1. Create the Markdown file in the appropriate section directory (e.g. docs/modelling/new-page.md).
  2. Add a sidebar entry in docs/docs-config.json under the appropriate section.
  3. Add a row to the section’s index.md page table.
  4. Update docs/_plan/content-map.md if tracking authoring status.