Model builder, latent infection process components and tutorials

[cdc-mitzimorris]

Adds infrastructure for modeling infections across multiple subpopulations with hierarchical Rt structure, plus a builder pattern for composing multi-signal renewal models.

Key additions:

• HierarchicalInfections: Latent process with shared baseline Rt and subpopulation-specific deviations
• TemporalProcess protocol with AR1, DifferencedAR1, RandomWalk implementations
• ModelBuilder + MultiSignalModel for composing latent + observation processes
• Hierarchical priors (HierarchicalNormalPrior, GammaGroupSdPrior)
• Sample datasets (NHSN hospital admissions, fake NWSS wastewater)
• Two tutorials demonstrating the API

---

Architecture

Latent layer:

• TemporalProcess (protocol)
  • AR1, DifferencedAR1, RandomWalk (implementations)
  • Used by HierarchicalInfections for baseline Rt and subpopulation deviations
• HierarchicalNormalPrior, GammaGroupSdPrior
  • Used by HierarchicalInfections for I0 and other group-level effects
• BaseLatentInfectionProcess → HierarchicalInfections
  • Outputs LatentSample: (aggregate, all_subpops, observed, unobserved)

Model layer:

• ModelBuilder
  • Configures latent process + observation processes
  • Computes n_initialization_points from all delay PMFs
  • Builds MultiSignalModel
• MultiSignalModel
  • Routes infections to observations based on infection_resolution()
  • "aggregate" → summed infections
  • "subpop" → per-subpopulation infections

---

Suggested Review Order

1. latent/temporal_processes.py — TemporalProcess protocol and implementations (AR1, DifferencedAR1, RandomWalk). Module docstring explains relationship to pyrenew.process.
2. latent/base.py — BaseLatentInfectionProcess base class defining the LatentSample output structure
3. latent/hierarchical_infections.py — HierarchicalInfections implementation
4. model/multisignal_model.py → model/model_builder.py — Composition layer
5. Tutorials — Demonstrate the API in action:
   - latent_hierarchical_infections.qmd: temporal process choices
   - building_multisignal_models.qmd: full inference workflow
6. Tests and datasets — Can skim; mostly mechanical

---

Review Scope

Feedback requested on:

• API design: Are the interfaces intuitive? Would you change any method signatures?
• Correctness: Does the hierarchical Rt decomposition and sum-to-zero constraint make epidemiological sense?

Deferred to follow-up PRs:

• Module organization (e.g., whether temporal_processes.py belongs in latent/ vs process/) — tracked in Make noise a module rather than a submodule of observation #656, makes sense to address both locations consistently
• Performance optimization
• Additional temporal process types (periodic effects, etc.)

---

Known Limitations / Future Work

• TemporalProcess implementations don't yet support periodic effects (available in pyrenew.process)
• Tested with synthetic data; real-data validation ongoing
• ModelBuilder API may evolve based on user feedback

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.12%. Comparing base (247baba) to head (0c9ad50).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #650      +/-   ##
==========================================
+ Coverage   97.18%   98.12%   +0.94%     
==========================================
  Files          47       55       +8     
  Lines        1277     1761     +484     
==========================================
+ Hits         1241     1728     +487     
+ Misses         36       33       -3     

Flag	Coverage Δ
unittests	98.12% <100.00%> (+0.94%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Thank you for your contribution @cdc-mitzimorris 🚀! Your github-pages is ready for download 👉 here 👈!
_{(The artifact expires on 2026-02-06T03:44:50Z. You can re-generate it by re-running the workflow here.)}