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

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.