/appendices/index.html 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 Glossary: canonical dsambayesplus terminology. R Module Index: logical map of package source files. Traceability Map: how to map issues and recommendations to implementation evidence. Usage rules Use appendices as reference pages, not primary process documentation. Keep operational runbooks in docs/getting-started/, docs/runner/, and docs/internal/. Prefer links to authoritative sources instead of duplicating constraints or commands. Related sections Getting Started Runner Modelling Internal (Engineering) Hugo en-gb /appendices/glossary/index.html Mon, 01 Jan 0001 00:00:00 +0000 /appendices/glossary/index.html Purpose Define canonical terms used across dsambayesplus modelling, runner, diagnostics, and release documentation. How to use this glossary Use these definitions when writing or reviewing dsambayesplus documentation. Keep term usage consistent across docs/modelling/, docs/runner/, and docs/internal/. If a term changes behaviour in code, update this page in the same change. Terms Term Definition Primary location 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 dsambayesplus 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 via decomp(). Unavailable for probabilistic adstock/Hill media-transform models. For draw-wise scenario evaluation with fitted transforms, use counterfactual_response(). 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/dsambayesplus.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 dsambayesplus APIs. scripts/dsambayesplus.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. Formula-level transforms are applied before fitting; probabilistic media-transform models estimate carry-over parameters. dsambayesplus 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 and Stan media-transform templates lognormal mean Bias-corrected back-transform for log-response models: exp(mu + sigma^2/2). It is the default 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. dsambayesplus avoids this bias by applying exp() draw-wise before summarising. docs/modelling/response-scale-semantics.md Related pages Config Schema Output Artefacts Model Object Lifecycle Quality Gates /appendices/module-index/index.html Mon, 01 Jan 0001 00:00:00 +0000 /appendices/module-index/index.html Purpose Provide a maintainable orientation map for R/ while preserving the flat R package layout. Layout rule dsambayesplus 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 FE model class: construction, retained-unit level reconstruction, 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_levels.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_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 Put new logic in the closest logical module listed above. If touching legacy compatibility files (R/run_config.R, R/run_artifacts.R), prefer adding new logic to their split companion files where possible. Keep exported function names stable unless there is an explicit API migration plan. Add or update test coverage in tests/testthat/ for any behavioural change. Related pages Runner Config Schema Runner Output Artefacts Model Object Lifecycle Traceability Map /appendices/traceability-map/index.html Mon, 01 Jan 0001 00:00:00 +0000 /appendices/traceability-map/index.html Purpose Provide a traceability reference that maps dsambayesplus issues and recommendations to implementation status and evidence. Tracked data source Two traceability CSVs are published alongside this page under docs/appendices/traceability-data/: issue_traceability.csv, per-issue status, severity, scope, and evidence anchors. recommendation_closure_matrix.csv, per-recommendation closure status and linked issues. These files are the repository’s tracked release reference. The fuller audit register is historical private material and may exist locally under .planning/archive/code_review/audit_report/; it is not available in every clone and does not override current source, tests, or these shipped snapshots. /appendices/docs-build/index.html Mon, 01 Jan 0001 00:00:00 +0000 /appendices/docs-build/index.html Purpose Describe how the dsambayesplus documentation site is built, previewed, and deployed. Documentation layers dsambayesplus currently has two documentation layers with distinct purposes: 1. Package reference inputs Package reference content is generated from: