Part III Computational Architecture

← Part II — Mathematical Foundations · gdpar Wiki Home · Part IV — Exhaustive Function Reference (1/7) →

---

Part III — Computational Architecture

This part is the map of how a model flows from a user call to posterior summaries. Every function named here is documented in full in Part IV; the Stan templates in Part V.

III.1 The fitting pipeline

A call to gdpar(formula, family, amm, data, group = NULL, path = "bayesian", ...) proceeds through:

1. Specification resolution. The response/formula is parsed; the AMM design is built. The user may supply the AMM three ways: a single amm_spec() (scalar/coord-wise), a named list of specs, or a gdpar_formula_set() / gdpar_bf() (a brms-like multi-slot formula DSL parsed by .gdpar_parse_amm_formula). dims_spec (dimwise/override/resolve_dims_spec) declares per-coordinate ($p>1$) component formulas. The family is resolved (gdpar_family/gdpar_family_multi/heterogeneous) into the per-slot gdpar_param_spec list, and the resolved $(K,p)$ pair determines the path regime.
2. Design construction. build_amm_design (and .build_amm_design_multi, .build_amm_design_K) assemble the centered design matrices $Z_a,Z_b$ (enforcing (C2)/(C3) by column-centering) and the modulating design $X$ with the W basis materialized.
3. Identifiability pre-flight. gdpar_check_identifiability() runs the Gram-matrix check (Prop. 1C), the C4-bis cross-component check for $p>1$ (check_C4_bis_per_k), the per-slot checks for $K>1$, and — when group is set — the C7 anti-aliasing check (.check_group_aliasing_c7). Failure aborts with gdpar_identifiability_error unless skip_id_check = TRUE.
4. Parametrization pre-flight. The CP/NCP/(linear) decision is taken data-drivenly (§II.6) via preflight_parametrization* → resolve_parametrization*.
5. Code generation. R/stan_codegen.R assembles the Stan program string for the resolved $(K,p,\text{family},W,\text{parametrization},\text{group})$ from the canonical Stan pieces, then compiles via cmdstanr.
6. Sampling. HMC runs (optionally through the geometry engine, §II.9). For $K=1,p=1$ the path is gdpar() proper; $p>1$ dispatches to .gdpar_multi, $K>1$ to .gdpar_K/.gdpar_K_build.
7. Diagnostics + packaging. compute_diagnostics collects $\widehat R$, ESS, divergences (with the all-NA $\to-\infty$+warning guard of D77); diagnostics() exposes them; the result is a gdpar_fit object.

gdpar_eb() replaces steps 5–7 with the three-step EB recipe (§II.3): Laplace marginal-likelihood maximization for $\widehat\theta_{\text{ref}}^{\text{EB}}$ (multi-start + Levenberg–Marquardt ridge + condition-number guard), plug-in as data, conditional sampling — across the four regimes (Base/A/B/C) and their marginal+conditional template pairs.

III.2 The code generator

R/stan_codegen.R is a string-assembly compiler: it does not ship one monolithic Stan file per case but composes a program from canonical pieces under inst/stan/_canonical_pieces/ (helpers, the $p=1$ and $p\ge1$ AMM blocks, the EB marginal/conditional blocks, the distributional-$K$ block) plus the dispatched family likelihood branch (selected by stan_id), the chosen W evaluation (W_type_id: polynomial / Stan-side Cox–de Boor B-spline / differenced anchoring), the parametrization toggle (CP/NCP/linear $c_b$), and the optional per-group anchor block. The unification of the $p=1$ and $p\ge1$ templates is the standing "deuda 8.4". Marker-based codegen also produces the MAP/MLE variants (strip-and-mark) used by the EB Laplace step.

III.3 The fitting engines

• R/gdpar.R — the orchestrator: gdpar() (entry), .gdpar_multi ($p>1$), .gdpar_K / .gdpar_K_build ($K>1$), anchor resolution, compute_diagnostics, dedup_message_blocks (clean console output).
• R/eb.R — the Empirical-Bayes engine (largest file, 3196 lines): the four-regime marginal/conditional fit drivers, the Laplace anti-fragility machinery, the EB gdpar_eb_fit packaging.
• R/families.R — the family/codegen-facing layer: param-spec construction, link factory, per-slot scope promotion, heterogeneous-family resolution, inverse-link-id computation per slot.
• R/geometry_*.R — the geometry engine, orchestrator, suite, bridge, Laplace, diagnostic (§II.9).
• R/dependence_robust.R — the dependence-robust inference engine (§II.10).

III.4 The S3 method surface

The user-facing objects and their methods (full list in NAMESPACE; detail in Part IV):

• gdpar_fit: print, summary, predict (with the $p>1$ array path and $K>1$ per-slot inverse-link path, plus grouped/newdata variants), coef (→ gdpar_coef), residuals (Dunn–Smyth / deviance / quantile, with DHARMa integration), pp_check, gdpar_loo, gdpar_posterior_predict, gdpar_dharma_object.
• gdpar_eb_fit: print, summary, coef, predict.
• gdpar_coef: print, summary, format, as.data.frame.
• causal/comparison: gdpar_causal_bridge, gdpar_meta_learner_comparison, gdpar_eb_fb_comparison each with print/summary/predict as applicable.
• specs/reports: amm_spec, amm_builder, W_basis, dims_spec, gdpar_family(_multi), gdpar_formula_set, gdpar_param_spec, and the diagnostic reports (gdpar_identifiability_report, gdpar_preflight_report, gdpar_contraction_report, gdpar_bvm_report, gdpar_dependence_diagnostic, gdpar_spatial_dependence_*, gdpar_ksd_joint, gdpar_geometry_diagnostic, geometry certificates) all carry print (and where useful summary/format/as.data.frame).

III.5 Serialization, golden tests, validation utilities

• R/amm_serialize.R — amm_save_spec/amm_load_spec (a text round-trip of an AMM spec: formula/char/numeric/W-record (de)serializers); gdpar_snapshot_fit snapshots a fit.
• R/golden_compare.R, R/golden_helpers.R — the golden-regression machinery (manifest, roster, structural/discrete/continuous/sanity comparators, code-hash + toolchain-version stamping) underpinning the test tiers of §VI.3.
• R/ksd_joint.R — a kernelized Stein discrepancy joint diagnostic; R/bvm_check.R — the Bernstein–von Mises calibration check (§II.2.1); R/contraction_diagnostic.R — empirical contraction (§II.6.3); R/gdpar_loo.R — PSIS-LOO aggregation; R/preflight*.R — the parametrization pre-flight (§II.6); R/utils-*.R — condition system (gdpar_abort/warn/inform, require_suggested) and input validators (assert_*).

---

---

← Part II — Mathematical Foundations · gdpar Wiki Home · Part IV — Exhaustive Function Reference (1/7) →