Changelog

Source: NEWS.md

imuGAP 0.3.0

Model Changes

• Hierarchical Tree Aggregation Solvers:
  • Introduced calculations to equate parent aggregate coverage to population-weighted sum of child probabilities under nonlinear links (logit, probit).
  • The added rootfinding approaches are newton, halley, builtin, along with a no-change direct. These translate an initial guess into a “solved” parent aggregation shift offsets. builtin does root-finding to exhaustion using the general purpose solver included in stan, newton and halley do limited-step root finding using those tailored numerical methods, and direct uses the guess-as-is.
  • The solver is currently selectable at run time, though the default solver option is compiled in an optimized model without branching.

User Interface Changes

• S3 Print Methods:
  • Added dedicated print.imugap_fit() providing a structured summary of the location hierarchy, observation data distribution, and key Stan parameters (beta_bs, sigma_layer, lambda_raw, and lp__).
  • Added print.imugap_predict() displaying target coverage metadata, location counts, and posterior prediction draw dimensions.
• Vignette Architecture & Documentation Overhaul:
  • Reorganized the vignette suite into focused modular articles: imuGAP (core workflow), example_data (input data schemas and structure), examining_fits (posterior diagnostics and inspection), and user_specified_layers (multi-layer and single-layer spatial partitions).
• Structured Input Conditions (#156):
  • Errors raised through stop_fmt_if() have class imugap_error; warnings from warn_fmt_if() have class imugap_warning. Both retain their base condition classes and carry a template id and raw values in fields. Front-ends can read these fields instead of parsing message text. Stan backend errors retain their own classes.
  • Canonicalizer column checks report the offending rows in a rows field (1-based indices into the table the caller passed), and name the caller’s table (observations, populations) instead of the internal dt.
  • canonicalize_locations() now rejects NA in loc_id, and canonicalize_observations() accepts an all-NA logical censored column (as read.csv() gives) as none censored. An NA in a subset-checked column is reported as a missing value, not as “missing NA”.

Engineering Changes

• Stan Modular Organization
  • Decoupled tree accumulation into modular Stan includes (functions/layer_offsets_static.stan, functions/layer_offsets_dispatch.stan), isolating solver dependencies from shared QR basis projection (functions/layer_offsets.stan).
  • Standardized top-level Stan model names under the convention <time>_<offsets>_<guess>_<solver>_<link>.stan (e.g. bspline_static_zero_halley2_logit.stan, bspline_static_zero_dispatch_probit.stan) and <time>_single_<link>.stan for unpartitioned models, reflecting the temporal basis, hierarchy offset structure, initial guesser, solver module, and link function.
• Automated Diagram Pipeline:
  • Added automated Mermaid diagram compilation pipeline (just diagrams) generating SVG and PDF visual assets with dark-mode compatibility.
• Synthetic Benchmark Suite:
  • Added a benchmarking suite (data-raw/benchmarks/) with Slurm HPC array execution to profile runtime, effective sample size, numerical accuracy, and calibration across solver alternatives and hierarchy depths.
• Stan Computation Optimization:
  • Optimized dose transitions, linear predictor broadcasting, and blocked QR orthonormal basis calculations.
  • Decoupled observation likelihood evaluation into uncensored, right-censored, and left-censored streams for vectorized evaluation.
  • Added population-scaled hierarchical layer offset shrinkage with standardized QR basis orientation.
  • Refactored Stan initial value generation into static helper make_init_fn().
• Build Organization
  • Streamlined developer and CI workflows via authoritative just recipes (just lint, just docs, just diagrams, just data-fit).
  • Decoupled lintr package execution from devtools in CI linting workflows.

imuGAP 0.2.0

CRAN release: 2026-09-02

Major Features

• Arbitrary Hierarchy Layer Depth:
  • sampling(), canonicalize_locations(), and underlying Stan models now support user-defined hierarchical location structures of arbitrary depth (e.g. 1-layer statewide, 2-layer state-county, 3-layer state-county-school, or deeper regional partitions).
  • Added assemble_layer_data() helper to construct and validate hierarchical metadata, bounds, and parent mappings.
  • Added dedicated single-layer model impute_school_coverage_process_v6_single_layer with automatic dispatch when single-layer inputs are supplied.
  • Added a new vignette (user_specified_layers) demonstrating 1-layer, 2-layer, and 3-layer model estimation and prediction workflows.
• Backend Abstraction via flexstanr:
  • Integrated flexstanr (>= 0.2.0) to provide uniform backend abstraction across rstan and cmdstanr MCMC engines.
  • Re-exported flexstanr::stan_options() for seamless sampler configuration.
• Modular Stan Architecture:
  • Refactored top-level Stan models into concise assembly skeletons utilizing modular #include directives (functions/, data/, transformed_data/, parameters/, model/).
  • Pruned legacy/vestigial Stan scripts to streamline code base maintenance.
• Data Pipeline & Target Generation:
  • Split target generation into fit-free constructor create_target() and validation function canonicalize_target().
  • Added bundled example fitted datasets for single-layer and 2-layer models (fit_sim_1layer, fit_sim_2layer, predict_sim_1layer, predict_sim_2layer, target_sim_1layer, target_sim_2layer).

Enhancements & Bug Fixes

• Location Hierarchy Invariant: Enforced structural validation ensuring location nodes have either 0 offspring (leaf) or $\ge 2$ offspring (preventing single-child degenerate chains).
• Error Handling & Assertions: Standardized assertion messages across all functions using module-level ERR_* format string constants and helper assertion functions stop_fmt_if() and warn_fmt_if().
• Validation: Added validation against NA weights in population and target specifications.
• Documentation Examples & Check Times: Applied combined @examplesIf interactive() and \donttest{} idiom to computationally heavy examples, enabling fast pkgdown builds (~35 seconds) while remaining CRAN --as-cran compliant.
• Vignette Dark Mode Compatibility: Enforced solid white backgrounds and high-contrast styling across all vignette plots for clean rendering in light/dark modes.

imuGAP 0.1.0

CRAN release: 2026-06-22

First public release. Initial feature set:

• sampling(): fits the imuGAP Bayesian hierarchical coverage model via rstan::sampling() and returns an imugap_fit object wrapping the underlying stanfit together with model settings and dataset metadata.
• predict.imugap_fit(): posterior-predicts coverage probabilities for a user-supplied target population grid using rstan::gqs().
• extract_imugap(): convenience wrapper around rstan::extract() for pulling out common imuGAP parameters (defaults to the state-level B-spline coefficients beta_bs).
• canonicalize_locations(), canonicalize_observations(), canonicalize_populations(): validate and convert user-supplied data into the canonical forms required by the sampler.
• imugap_options(): configures model-side settings (B-spline degrees of freedom, dose schedule, model object).
• stan_options(): configures Stan sampler settings (iter, chains, seed, etc.) with input validation.
• Bundled Stan models:
  • impute_school_coverage_process_v6 (adds county- and school-level random effects; current default).
• Bundled example datasets for end-to-end examples and tests: locations_sim, observations_sim, populations_sim, latent_params_sim, predict_sim, target_sim, and the reference fit_sim stanfit fixture.
• pkgdown documentation site published at https://accidda.github.io/imuGAP/.