Skip to content

Close the natural-history plan: quarantine exemption by tool name, plain diagrams, NH-5 next - #370

Merged
gvegayon merged 1 commit into
v1-layersfrom
nh-close
Nov 10, 2026
Merged

gvegayon merged 1 commit into
v1-layersfrom
nh-close

Conversation

@gvegayon

@gvegayon gvegayon commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Closes the natural-history plan after NH-4 (all four wrappers merged on fe2385a) with the decisions of 2026-11-09, makes the policy change they call for, and simplifies the model diagrams.

Decisions recorded (natural-history.md, 16-21)

  • 16. rule() and the deadline calendar are deferred. No model needs either, and adding them later breaks nothing; the calendar joins Replace the queuing system with an index-driven scheduler #265.
  • 17. Accessors by margin (Margin::pair | stage | status, get_agents_stages() / get_agents_statuses(), transitions per strain) replace the ones that still expose the engine's cells. Built in NH-5, with the database's split by disease.
  • 18. Measles quarantine exemption by tool name (open question 1). Implemented here (below).
  • 19. PEP acts on the current episode (open question 3), and its tool stays. PEP's nested events_run() stays too: it attaches the tool PEP just gave before the efficacy draw.
  • 20. Rash onset stays the measles landmark (open question 2). The names stay NaturalHistory and Statuses (open question 4).
  • 21. Several diseases per model, one infection per agent, in 1.0.0 (NH-5, before Phase 4). Its plan is the next PR. Settled so far: a stage per disease per agent and one status; one database with histories kept per disease (long tables carry a disease column; matrices and per-agent stages need the disease when there are several); an explicit strain(); tools and stage references name their disease when there are several; pull only with several diseases; a removal in one disease is a built-in "Removed (other disease)" stage in the others.

Code

  • ModelMeasles::set_quarantine_exempt_tools() / get_quarantine_exempt_tools(), default {"MMR", "PEP MMR"}. The three measles models exempt a traced or exposed contact only if they hold one of these tools, whether or not it protects them: documented MMR, routine or as PEP, is presumptive evidence of immunity, and immunoglobulin is not (CDC). Before this, holding any tool exempted a contact, IG recipients included. Results change for runs in which agents hold tools other than MMR (PEP with IG, or tools the user adds). ModelSEIRQuarantine keeps "any tool".
  • Diagrams without transition details. NaturalHistory::draw_mermaid() (and so Model::draw_natural_history() and make diagrams) draws one unlabeled arrow per pair of stages or statuses that some transition joins. Kinds, values and names are left out: they are the model's parameters. draw_mermaid() loses its second argument. All .mmd files are regenerated.
  • The render targets (include/measles/Makefile, include/epiworld/models/Makefile) no longer use xargs (macOS refuses the long command line) or base64 -w0, fail on an HTTP error instead of saving it as a PNG (how the 19-byte measlesmixing.png got into NH-3: docs, and model diagrams drawn from the declarations #366), retry, and pause between requests.
  • add_virus()'s error for a second natural history now points to NH-5.

Tests

  • New 18k-measles-mixing-quarantine-exempt.cpp: with default settings, contacts holding a tool that is not on the list are quarantined; once their tool joins the list, nobody is.
  • 12-diagrams.cpp rewritten for the unlabeled arrows (two transitions between the same statuses draw one arrow).
  • make test WITH_OPENMP=0 in the devcontainer: every suite passes. The two tests above were also built standalone with -DEPI_DEBUG.

Runbook (contact-layers.md)

Left for the maintainer

  • The pictures in docs/assets/img are stale. measlesmixing.png here is a real image again, but it was rendered from the labeled diagram, as were the others; surv.png was never rendered. Rendering sends the diagrams to mermaid.ink, which the agent's session was not allowed to do: run make -C include/measles all and make -C include/epiworld/models all, and commit the PNGs.

Wrappers

  • measles and epiworldjs bind set_quarantine_exempt_tools() in their next port.
  • The downstream jobs for epiworldR and epiworldpy fail, as expected from the diagram change (one test each; a port fixes both, no C++ API change needed):
    • epiworldR test-model-diagram.R:197 expects s1 ==> (the arrow durations had); every arrow is now -->.
    • epiworldpy test_natural_history.py:133 expects the transition name "Vaccination" in the diagram; names are no longer drawn.
  • measles and epiworldjs pass.

🤖 Generated with Claude Code

…ain diagrams, NH-5 next

- Measles: who skips quarantine is set by tool name
  (ModelMeasles::set_quarantine_exempt_tools(), default {"MMR", "PEP MMR"});
  holding any tool no longer exempts (immunoglobulin recipients are
  quarantined).
- Diagrams drawn from the declarations show one unlabeled arrow per pair of
  stages (or statuses) a transition joins; kinds and values are left out.
- The render targets work on macOS (no xargs, no base64 -w0), fail on an
  HTTP error instead of saving it as a PNG, retry, and pause between
  requests.
- natural-history.md: decisions 16-21 (rule() and the calendar deferred, the
  open questions settled, several diseases per model as NH-5).
- contact-layers.md: runbook status, next steps, and the measles release
  item.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Thank you for your contribution @gvegayon 🚀! Your documentation-site-pr-370 is ready for download 👉 here 👈!
(The artifact expires on 2027-02-08T02:47:30Z. You can re-generate it by re-running the workflow here.)

@codecov

codecov Bot commented Nov 10, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v1-layers@fe2385a). Learn more about missing BASE report.

Files with missing lines Patch % Lines
include/epiworld/naturalhistory-meat.hpp 91.66% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##             v1-layers     #370   +/-   ##
============================================
  Coverage             ?   77.48%           
============================================
  Files                ?       70           
  Lines                ?     7996           
  Branches             ?     1567           
============================================
  Hits                 ?     6196           
  Misses               ?     1310           
  Partials             ?      490           
Flag Coverage Δ
unittests 77.48% <93.33%> (?)

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

☔ View full report in Codecov by Harness.
📢 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.

@gvegayon
gvegayon merged commit 71124a9 into v1-layers Nov 10, 2026
14 of 16 checks passed
@gvegayon
gvegayon deleted the nh-close branch November 10, 2026 03:22
gvegayon added a commit to UofUEpiBio/epiworldR that referenced this pull request Nov 10, 2026
…o/epiworld#370) (#232)

Vendors 71124a95. draw_natural_history() now draws one unlabeled arrow per
pair of stages a transition joins; the test and the help follow.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
gvegayon added a commit to UofUEpiBio/epiworldpy that referenced this pull request Nov 10, 2026
Ports UofUEpiBio/epiworld#370; vendors
71124a959146eccf0fb801bcdc0866e3ed23a2e3.

- **Diagrams without transition labels.** `Model.draw_natural_history()`
now returns one unlabeled arrow per pair of stages (or statuses) that
some transition joins; names, kinds and values are no longer drawn. The
test that looked for the transition's name in the diagram now checks the
arrow and that there are no labels; the docstring says so.
- Nothing else to bind: the quarantine exemption by tool name is in the
measles models, which epiworldpy does not bind.

**Checks:** built and installed in the container; `pytest`: 155 passed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
gvegayon added a commit to UofUEpiBio/epiworldjs that referenced this pull request Nov 10, 2026
Ports UofUEpiBio/epiworld#370; vendors
71124a959146eccf0fb801bcdc0866e3ed23a2e3.

Re-vendor only:
- **Quarantine exemption by tool name** (measles models): not bound.
epiworldjs adds no tools and runs no PEP, so the only tool is the
models' MMR vaccine, and the default list (`MMR`, `PEP MMR`) exempts
exactly who "any tool" did. The golden outputs are unchanged.
- **Diagrams without labels**: epiworldjs does not bind
`draw_natural_history()`.

**Checks:** `make check-version test` in the container: 88 tests pass,
and the native and WASM golden outputs are identical. Playwright was not
run (release-time check).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
gvegayon added a commit to UofUEpiBio/measles that referenced this pull request Nov 10, 2026
…/epiworld#370) (#73)

Vendors 71124a95. Binds set_quarantine_exempt_tools() and
get_quarantine_exempt_tools(); the default is MMR and PEP MMR, so
immunoglobulin recipients are now quarantined.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
gvegayon added a commit that referenced this pull request Nov 10, 2026
A plan only, for review before any code: `several-diseases.md`. It
carries out decision 21 of `natural-history.md` (#370). No source
changes.

## The design in short

- **A disease is a natural history; a model has one or more.** Every
agent has a stage in every disease and one status, so it can be
Recovered from influenza and Susceptible to measles. At most one of its
diseases is in a carrier stage: one infection per agent, which is the
rule the engine already has (one virus slot).
- **Infection is one draw across diseases.** An agent is exposed only by
contacts whose virus belongs to a disease it can be infected by; one
draw picks at most one virus. With several diseases, infections are
pulled, not pushed.
- **One database**, with its histories kept per disease. Tables return
every disease with a `disease` column (never "the first one"); what is
shaped by one disease's stages (a transition matrix, the agents' stages)
needs the disease when there are several.
- **Explicit, not guessed.** A strain is made with
`Virus::strain(name)`; a virus built from scratch is a new disease. With
several diseases, references to stages take `.of(disease)` and tools
must have targets, or the run stops with an error that says how to fix
it.
- **A removal in one disease** is a built-in "Removed (other disease)"
stage in the others, so each disease's counts add up to the population.
- **The engine:** each disease gets a *track*, today's machinery for one
natural history; the status is shared.
- **Accessors by margin** (decision 17) are built here:
`get_transition_probability(Margin, disease, strain)`,
`get_agents_stages(disease)`, `get_agents_statuses()`.

## Phases

- **NH-5a:** the engine on tracks, with one disease. Gate: identical
histories for every model, benchmark within 10%.
- **NH-5b:** several diseases, the database per disease, the accessors
by margin, the savers; a two-disease benchmark scenario.
- **NH-5c:** the wrapper ports.

## For the reviewer: open questions (Section 11)

1. Tool targets: keep the existing lineage targets and only require them
with several diseases, or add a target by disease?
2. The `disease` column also with one disease (proposed: always)?
3. A second disease next to a custom sampler (the measles models):
diseases tried in a random order each day. Acceptable?
4. The name "Removed (other disease)".

## Also

- Runbook (`contact-layers.md` §11.6): the ports of #370 (epiworldR
#232, epiworldpy #45, epiworldjs #31 merged; measles #73 open) and the
NH-5 row.
- `AGENTS.md` points to `natural-history.md` and `several-diseases.md`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant