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 formula-term contributions. Unavailable for probabilistic adstock/Hill media-transform models until a posterior-aware transformed-response method exists. 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 / optimisation MAP optimisation path (fit.method: optimise). R/blm.R, R/hierarchy.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-8 Canonical release quality gates for lint, style, tests, Stan release evidence, 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. DSAMbayes does not add automatic warm-up or synthetic pre-history, so carry-over starts from the observed window (and resets at hierarchical panel boundaries). Formula transforms
lognormal mean Bias-corrected back-transform for log-response models: exp(mu + sigma^2/2). Default in v1.2.2 for fitted_kpi(); the conversion_method value written to fitted_kpi.csv is lognormal_mean. 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/hierarchy_diagnostics.R, R/hierarchy_posterior.R, R/pooled.R, R/model_schema.R, R/blm_compiled.R, R/map_optimisation.R
Fixed-effects estimator Coefficient-only FE model class: construction, guards, estimability, Stan-data prep, prior resolution, posterior extraction, and public API surface R/fixed_effects.R, R/fixed_effects_api.R, R/fixed_effects_estimability.R, R/fixed_effects_fit.R, R/fixed_effects_guards.R, R/fixed_effects_posterior.R, R/fixed_effects_prior.R, R/fixed_effects_stan_prep.R
Estimator design and contract Cross-estimator structural-failure contract, design-diagnostic policy (rank, VIF, condition number, group support), and estimation-frame reconciliation shared by RE/CRE/FE R/estimator_contract.R, R/estimator_design.R, R/estimation_frame.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, thresholds, split design/posterior/residual checks, model-selection scoring, LOO/WAIC, cross-validation, posterior predictive and metrics R/diagnostics.R, R/diagnostics_report.R, R/diagnostics_thresholds.R, R/diagnostics_checks.R, R/diagnostics_checks_design.R, R/diagnostics_checks_posterior.R, R/diagnostics_checks_residuals.R, R/diagnostics_model_selection.R, R/loo_waic.R, R/crossval.R, R/time_series_cv.R, R/post_pred.R, R/stats.R, R/compare_runs.R
Posterior scenario evaluation Draw-wise fitted responses, aligned scenario/reference contrasts and posterior aggregation R/counterfactual_response.R, R/counterfactual_response_aggregate.R
Decomposition and extraction Decomposition APIs, native decomposition, deployment artefacts, causal-assumption checklist, slim/lean serialisation, and extraction helpers R/decomp.R, R/decomp_prep.R, R/decomp_native.R, R/deployment_artifact.R, R/causal_checklist.R, R/slim.R, R/extract.R, R/fitted.R
Runner config and orchestration YAML defaults/coercion/validation (v1 and v2 authored schema), 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_config_validators.R, R/run_config_v2.R, R/run_config_v2_compile.R, R/run_config_v2_helpers.R, R/run_config_v2_overrides.R, R/run_config_v2_validators.R, R/run_orchestrator.R, R/run_from_yaml.R
Runner artefacts and reporting Stage mapping and artefact writers for metadata, diagnostics, enrichment, decomposition, fixed-effects, and scenario analysis; CLI adapter and typed runner result R/run_artifacts.R, R/run_artifacts_diagnostics.R, R/run_artifacts_enrichment.R, R/run_artifacts_decomposition.R, R/run_artifacts_fixed_effects.R, R/run_artifacts_scenario_analysis.R, R/run_scenario_analysis.R, R/runner_fit_plots.R, R/runner_cli_adapter.R, R/runner_result.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 (helpers, scoring, results assembly) and plotting APIs R/optimise_budget.R, R/optimise_budget_helpers.R, R/optimise_budget_scoring.R, R/optimise_budget_results.R, R/optimise_budget_plots.R, R/plot_theme_wpp.R
Package infrastructure and utilities Package lifecycle hooks, typed error conditions, utility helpers, package metadata helpers, bundled ASCII art R/zzz.R, R/package.R, R/errors.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_config_v2_validators.R Cross-field validation for the current authored schema_version: 2 contract, including model-type-specific rules (fe, re, cre, pooled).
R/run_artifacts.R Artefact pathing and stage contract used by docs, local runner workflows, and release evidence capture.
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.
R/estimator_contract.R Shared structural-failure contract consumed by RE, CRE, and FE preparation paths; changes here affect all three estimators simultaneously.
R/fixed_effects_guards.R Enforces the FE capability boundary by rejecting unsupported generic operations (MAP, decomposition, optimisation, etc.); central to the FE implemented_not_qualified contract.

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 currently has two documentation layers with distinct purposes:

1. Package reference inputs

Package reference content is generated from:

  • roxygen comments in R/
  • vignettes in vignettes/
  • generated man/*.Rd files

This material supports package help pages and package-check workflows. It is not the deployed public docs site.

2. Public documentation site

The public docs site is built from hand-authored Markdown under docs/ plus the Hugo/Relearn wrapper under docs-site/.

Build locally:

python3 docs-site/build_content.py
(cd docs-site && hugo --cleanDestinationDir)

Build flow:

  1. docs/ is the source of truth.
  2. docs-site/build_content.py mirrors and normalizes content into docs-site/content/.
  3. Hugo renders the final site into docs-site/public/ and cleans removed pages from prior builds.

There is no canonical automated deployment pipeline for the public docs site. Build and publish manually if you choose to host updated docs.

Preview locally:

  • open Markdown files directly for quick edits, or
  • serve/build the Hugo site for full navigation and theme rendering

If you maintain an external published mirror such as https://dsambayes.docs.wppma.space/, treat it as a manual distribution channel that may lag the repository. Verify freshness before linking to it in release communication.

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.