matiasmolinas/dental-analysis/histora-mechanistic-pipeline

HISTORA mechanistic pipeline (the deterministic engine)

Use this skill when a case needs numbers, not just framing — the calibrated mechanistic predictions, uncertainty ranges, counterfactuals, the genetic causal probe, or the comparative benchmark. It complements the reasoning skills (oral-systemic-analysis, periodontal-staging, non-diagnostic-guardrail): those reason; this one computes, from versioned code, so the same case always yields the same ranges.

When to use

• "What does the engine predict for this case?" → run the pipeline on the structural stratum.
• "How much does periodontal therapy change CRP / HbA1c?" → the counterfactual levers.
• "Is the shared inflammatory proxy causal?" → the Mendelian-randomization probe (--mr).
• "Is the integrated harness better than separate models / bare Claude?" → the benchmark (--benchmark).

How to run

The engine is the pinned histora package (pure-python, dependency-free core). Install it once, then run:

# public repo: plain install. Private repo: embed the connected GitHub token so the clone authenticates.
pip install "git+https://github.com/matiasmolinas/dental-analysis@main"                       # when public
pip install "git+https://x-access-token:${GITHUB_TOKEN}@github.com/matiasmolinas/dental-analysis@main"  # while private
# (run_pipeline.py's auto-install fallback does this token substitution for you; add matplotlib for figures)
python run_pipeline.py --case case.json      # → predictions.json  (mechanistic ranges + counterfactuals)
python run_pipeline.py --mr                   # → mr_report.json (illustrative literature-directional panels)
python run_pipeline.py --mr --real            # → mr_report.json from REAL OpenGWAS summary stats
python run_pipeline.py --cis                   # → cis_mr_report.json: LD-aware IL-6R cis probe (real)
python run_pipeline.py --benchmark            # → benchmark_report.json
python plot_pipeline.py predictions.json --mr mr_report.json --benchmark benchmark_report.json

LD-aware IL-6R cis probe (`--cis`) runs the strong causal test — IL-6R signalling → coronary disease (the tocilizumab-mimicking instrument) — correctly: the cis SNPs are in linkage disequilibrium, so it uses correlated IVW (GLS with the OpenGWAS LD matrix, sign-aligned to the effect alleles), not naive IVW. Needs OPENGWAS_JWT; reports the correlated estimate as primary and the naive IVW only to show the difference. See histora.cis_mr.

Real MR (`--real`) replaces the illustrative panels with real public GWAS summary statistics via the OpenGWAS API. It needs a free token in the OPENGWAS_JWT environment variable (get one at https://api.opengwas.io; in Claude Science, add it as a credential — the pipeline inherits it and never stores it). Modal is optional — a single MR is laptop-light; Modal/HPC only helps to scale to many exposure–outcome pairs. The OpenGWAS study IDs in histora.real_mr.DEFAULT_CONFIG are versioned — verify them on OpenGWAS before quoting a result; the estimator is exact and unit-tested, the study choice is yours.

run_pipeline.py finds the engine automatically (installed → local repo src/ → pip-install at a pinned ref). case.json is a structural record: periodontal (bop_pct, diagnosis/stage, mean_ppd_mm), shared_risk (type2_diabetes, smoking_active, hba1c), medical_cv (hs_crp) — bands and flags only.

What it returns

• `predictions.json` — systemic (IL-6/CRP), the CV / metabolic / neuro axes, the periodontal-therapy

and IL-6-blockade counterfactuals, and `ranges_over_uncertainty` (a 90% ensemble band per output) with the dominant uncertainty parameter per output.

• `mr_report.json` — the two-sample MR (IVW + MR-Egger + weighted-median) causal probe.
• `benchmark_report.json` — the S-vs-H comparative scorecard.
• Figures (via plot_pipeline.py, needs matplotlib): fig_envelopes.png (ranges, not points),

fig_sensitivity.png (tornado), fig_mr.png (β-scatter + IVW slope), fig_benchmark.png (grouped bars).

Stage-3 deepened physiology (all mechanisms)

For the full mechanistic depth — the multi-cytokine inflammatory core (acute-vs-chronic bistability), the atherosclerosis foam-cell ODE, the Bergman glucose–insulin dynamics, the closed diabetes↔periodontitis loop, the keystone-dysbiosis microbiome, and the amyloid+tau (A/T) neuro axis with APOE4/age modifiers — run the integrative entrypoint, which also foregrounds the "one lever, many axes" therapy response:

python ../../src/run_physiology.py --case case.json --plot   # → physiology_report.json + Stage-3 figures

Figures (via plot_pipeline.plot_stage3, needs matplotlib): fig_stage3_cv_plaque.png (foam-cell process), fig_stage3_glucose.png (Bergman meal response), fig_stage3_inflammation_phase.png (the two-basin phase portrait — acute vs chronic), fig_stage3_tau_front.png (the tau front on the Braak chain, flagged EXPLORATORY), fig_stage3_perio_loop.png (the diabetes↔periodontitis fixed-point cobweb), fig_stage3_proteins.png (the IL-6→IL-6Rα/gp130→CRP signaling axis with UniProt/PDB IDs + the tocilizumab blockade node — the connector layer, histora.proteins), and fig_stage3_one_lever.png (coherent multi-axis therapy response — the calibrated CV/metabolic axes kept visually separate from the EXPLORATORY neuro axis, so the tiers can't be conflated). In Claude Science the same data renders as native interactive/animated figures, with the UniProt/PDB connector grounding the proteins (IL-6/IL-6R/CRP structures) and OpenGWAS grounding the causal probe.

Guardrail (hard)

Non-diagnostic. The input is a structural stratum (bands/flags), the output is population/parameter- level ranges — never a patient value, never an imputed datum (a missing mediator is a collection flag). The numbers are produced by the pinned, unit-tested histora code; the model orchestrates and renders, it does not invent the math. Reported flags (e.g. the failed atuzaginstat/GAIN trial for the neuro axis) must be surfaced, not dropped.