Skip to content

SeroEpi

Precision target selection, hierarchical Bayesian prevalence modelling, and multi-valent formulation design from genomic surveillance.

Built on scikit-learn, Polars, and JAX/NumPyro, SeroEpi transforms pathogen isolate collections and genotype calls into stratified prevalence estimates, spatial choropleths, and cross-validated multi-valent formulations.

Python 3.13+ JAX + NumPyro scikit-learn + Polars PyShiny Web App GPLv3 License

Open Embedded Web App Launch on Posit Connect Cloud ↗

Key Capabilities

  • Surveillance Cohort & Target Engineering (seroepi.dataset, seroepi.variables)

    Ingests Pathogenwatch isolate collections (PathogenwatchClient) and UN/World Bank demographic indicators (WorldBankClient), enforces typed Variable contracts (Spatial, Temporal, Trait, Target), and composes multi-variable Criterion targets.

  • Stratified Aggregation & Partial Pooling (seroepi.aggregate, seroepi.estimators)

    Aggregates isolate counts across geographic, temporal, and clinical strata (Aggregator) and fits Unpooled (Wilson/Clopper-Pearson/Jeffreys), Bootstrap, or JAX/NumPyro Hierarchical Bayesian (MCMC NUTS and SVI) Binomial and Beta-Binomial models.

  • LOSO-Validated Formulation Design (seroepi.estimators.formulation)

    Ranks candidate targets under pooled or equal-stratum weights, controls Bayesian or Benjamini-Hochberg False Discovery Rates against burden thresholds, and evaluates held-out geographic coverage via Leave-One-Stratum-Out (loso) cross-validation.

  • Publication-Ready Visuals & Live PyShiny App (seroepi.plotting, seroepi.app)

    Generates interactive Altair spatial choropleths (ChoroplethPlotter), cumulative coverage curves (FormulationPlotter), UpSet co-occurrence matrices (UpSetPlotter), and demographic pyramids (PyramidPlotter) inside a reactive PyShiny dashboard.

End-to-End Epidemiological Workflow

flowchart LR
    PW["<b>Surveillance Cohort</b><br/><i>Pathogenwatch + World Bank</i>"]
    AGG["<b>Stratified Aggregator</b><br/><i>Target × Spatial / Temporal Strata</i>"]
    EST["<b>Prevalence Estimator</b><br/><i>Unpooled / NumPyro NUTS &amp; SVI</i>"]
    FRM["<b>Formulation Meta-Estimator</b><br/><i>Top-K Valency + LOSO Stability CV</i>"]
    PLT["<b>Interactive Altair &amp; Shiny</b><br/><i>Choropleth, UpSet &amp; Coverage</i>"]

    PW --> AGG --> EST --> FRM --> PLT

Quickstart

from seroepi.aggregate import Aggregator
from seroepi.estimators.formulation import Formulation
from seroepi.estimators.hierarchical import HierarchicalSVIEstimator
from seroepi.examples import KlebnetNeonatalSepsis
from seroepi.plotting.choropleth import ChoroplethPlotter

# 1. Load the KlebNET Neonatal Sepsis benchmark collection (981 K. pneumoniae isolates)
ds = KlebnetNeonatalSepsis.ensure()

# 2. Aggregate capsule K-locus counts across geographic strata
agg = Aggregator(target=ds.var("K_locus"), strata=[ds.var("country")]).fit(ds)

# 3. Fit a Hierarchical Bayesian SVI prevalence model and 10-valent vaccine formulation
est = HierarchicalSVIEstimator().fit(agg)
vaccine = Formulation(estimator=est, valency=10).fit(agg)
chart = ChoroplethPlotter().plot(est)

Comments