Tutorials on building PyRenew multisignal models

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
     hooks:
       - id: detect-secrets
         args: [ "--baseline", ".secrets.baseline" ]
-        exclude: package.lock.json
+        exclude: ^(package\.lock\.json|docs/tutorials/data/multisignal_he/)
   ####
   # Typos
   - repo: https://github.com/crate-ci/typos

docs/tutorials/.gitignore

@@ -8,3 +8,9 @@ _compiled
 *.ipynb
 *.py
 *.md
+!data/
+!data/multisignal_he/
+!data/multisignal_he/README.md
+!data/multisignal_he/*.csv
+!data/multisignal_he/*.json
+!data/multisignal_he/*.npz

docs/tutorials/.pages

@@ -8,3 +8,4 @@ nav:
   - right_truncation.md
   - day_of_week_effects.md
   - ascertainment.md
+  - multisignal_H_E_model.md

docs/tutorials/ascertainment.qmd

@@ -99,8 +99,13 @@ independent_iedr = dist.Beta(2, 98).sample(key_iedr, (n_draws,))
 
 ## Model-level ascertainment
 
-To share ascertainment structure across count signals, define an ascertainment model once and register it with the builder.
-Each observation process receives the appropriate signal-specific accessor from `for_signal()`.
+To share ascertainment structure across count signals, define an `AscertainmentModel` object and register it with the builder.
+Each observation process receives the appropriate signal-specific accessor via the object's `for_signal()` method.
+
+All all `AscertainmentModel` objects are specified with arguments `name` which identified this component in larger multisignal model and `signals` which is a list of unique signal names.
+
+The `JointAscertainment` model is the joint prior for scalar ascertainment rates across multiple signals.
+It samples from a logit multivariate normal vector given natural-scale baseline ascertainment rates and a covariance structure on the logit scale which can be specified either as a lower-triangular scale matrix, a covariance matrix, or a precision matrix.
 
 ```python
 builder = PyrenewBuilder()

docs/tutorials/building_multisignal_models.qmd

@@ -4,6 +4,8 @@ format:
   gfm:
     code-fold: true
 engine: jupyter
+execute:
+  eval: false
 jupyter:
   jupytext:
     text_representation:

docs/tutorials/data/multisignal_he/README.md

@@ -0,0 +1,13 @@
+# Multisignal H+E tutorial artifacts
+
+This directory stores precomputed fit artifacts for `docs/tutorials/multisignal_H_E_model.qmd`.
+
+Regenerate the artifacts from the repository root with:
+
+```bash
+uv run python docs_scripts/generate_multisignal_he_artifacts.py
+```
+
+The generator must be run on a machine that can fit the PyRenew tutorial models, including the linked-ascertainment variant, and the custom NumPyro H+E model.
+The documentation build reads the generated `npz`, `csv`, and `json` files from this directory instead of running the fits during Quarto rendering.
+The custom-H-E artifacts include reduced scalar draws and latent infection draws for plotting posterior infection uncertainty.

docs/tutorials/data/multisignal_he/metadata.json

@@ -0,0 +1,6 @@
+{
+  "generated_at": "2026-05-15T17:42:23.770328+00:00",
+  "pyrenew_sha": "7b76267c40aa3170d7a1a704aca8cca91f051ec6",
+  "pyrenew_multisignal_sha": "362cd6038060599859cc6104fd97321146952499",
+  "cfa_stf_sha": "cf46267785c213c2a6e6b36ed3595cd798660a03"
+}

docs/tutorials/data/multisignal_he/timings.json

@@ -0,0 +1,23 @@
+{
+  "pyrenew-H-E": {
+    "elapsed_seconds": 65.24473595619202,
+    "num_warmup": 500,
+    "num_samples": 500,
+    "num_chains": 4,
+    "rng_key": 42
+  },
+  "custom-H-E": {
+    "elapsed_seconds": 67.23963212966919,
+    "num_warmup": 500,
+    "num_samples": 500,
+    "num_chains": 4,
+    "rng_key": 42
+  },
+  "linked-pyrenew-H-E": {
+    "elapsed_seconds": 70.60192012786865,
+    "num_warmup": 500,
+    "num_samples": 500,
+    "num_chains": 4,
+    "rng_key": 42
+  }
+}