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

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.