DOCSEARCHbyAlgolia
Submit Docs

epydemix WebAPI Documentation

website·Indexed 30 days ago

https://epydemix-webapi.vercel.app/docs

A stateless REST API for running age-stratified epidemic simulations powered by epydemix. The documentation covers compartmental model presets (SIR, SEIR, SIS, V-SEIR, V-SEIHR), custom model and population definitions, vaccination campaigns, and deployment options via Docker, Google Cloud Run, or Fly.io. It also includes guides on AI integration via MCP and exporting simulations to standalone Python code.

Tokens
20.3K
Snippets
83
Records
125
Agent score
75%

What's inside epydemix WebAPI

  1. Overview of the V-SEIR model

    V-SEIR is a Susceptible-Exposed-Infected-Recovered model with a parallel vaccinated branch. Every clinical compartment has a corresponding _vax twin. This model is used when tracking infection dynamics and the impact of vaccination on susceptibility is required, but tracking hospitalizations as a separate compartment is not necessary (in which case V-SEIHR should be used instead).

  2. Overview of the SIS Model

    The Susceptible-Infected-Susceptible (SIS) model describes a disease where individuals return to the susceptible state after recovery, meaning there is no lasting immunity.

    Compartments:

    • Susceptible: Individuals who can be infected.
    • Infected: Individuals who are currently infectious.

    Transitions:

    • Susceptible → Infected: Mediated by the transmission_rate and the number of Infected individuals.
    • Infected → Susceptible: Occurs spontaneously at the recovery_rate.

  3. Overview of the SIR epidemic model

    The SIR model is a basic epidemic model where individuals move through three compartments: Susceptible (can be infected), Infected (currently infectious), and Recovered (immune). Transitions occur from Susceptible to Infected (mediated by transmission rate and the number of infected individuals) and from Infected to Recovered (spontaneous recovery).

  4. Overview of epydemix Web API

    The epydemix Web API is a RESTful interface for the epydemix simulation engine. It allows users to run compartmental epidemic models—such as SIR, SEIR, and SIS—against built-in population data via JSON requests, removing the need for a client-side Python environment.

  5. Overview of the V-SEIHR model

    V-SEIHR is a Susceptible-Exposed-Infected-Hospitalized-Recovered model featuring a parallel vaccinated branch. Every clinical compartment has an unvaccinated version and a corresponding _vax twin. The model simulates how vaccine efficacy reduces both the probability of infection (susceptibility) and the probability of severe outcomes (hospitalization). To implement a vaccination rollout schedule (moving individuals from Susceptible to Susceptible_vax), this model must be paired with a vaccination block; otherwise, the vaccinated branch remains at zero and the model behaves as a standard SEIHR model.

  6. Understand the epydemix API architecture

    The API is a stateless REST service built on top of the epydemix library. It performs discrete-time stochastic compartmental simulations on the server side. Users send a single JSON POST request to /api/v1/simulations containing the model, population, and run settings, and receive compartment trajectories and transition counts. No server-side state is maintained between requests, and no client-side simulation logic is required.

  7. Understand population and age-stratification in epydemix

    In epydemix, every simulation is age-stratified. A population defines who is being simulated and how they mix. It consists of two primary components:

    1. Population demographics: Named age bins (e.g., 0-4, 5-19) with associated population counts.
    2. Contact matrices: Square matrices for different layers (home, work, school, community). An entry $(i, j)$ represents the average number of contacts a person in age group $i$ has with people in age group $j$.

    Users can use built-in population presets (real-world data for countries or regions) or define custom populations inline.

  8. Modify model parameters during simulation using parameter_transforms

    The parameter_transforms parameter allows you to modify model parameters during a simulation. Each transform targets an existing parameter defined in model.parameters (including calculated parameters).

    Composition Order:

    • balcan and scale transforms stack multiplicatively in the order they are listed.
    • override transforms always take precedence for their specific date window, regardless of their position in the list.

  9. Use built-in epidemic model presets

    Model presets are pre-defined compartmental epidemic models that include a set of compartments, default parameters, and transition rules. They allow users to run simulations without manually defining compartments or transitions. If a preset does not meet specific needs, custom models can be declared manually.

  10. Troubleshoot AI safety filters for epidemic modeling

    Some AI models may flag conversations about epidemic models as safety violations. To bypass this, frame your requests as purely numerical, theoretical, or textbook exercises (e.g., 'textbook SIR / SEIR / SIS exercise'). If issues persist, try using smaller models like Claude Sonnet 4 or GPT-5.3 Instant.

  11. Implement a SEIR epidemic model

    The SEIR model extends the SIR model by adding an 'Exposed' compartment, representing a latent period where individuals are infected but not yet infectious.

    Compartments:

    • Susceptible: Individuals who can be infected.
    • Exposed: Individuals infected but not yet infectious.
    • Infected: Individuals who are currently infectious.
    • Recovered: Individuals who have recovered and are immune.

    Transitions:

    • Susceptible $\rightarrow$ Exposed: Driven by transmission_rate and the number of Infected individuals.
    • Exposed $\rightarrow$ Infected: Spontaneous transition at incubation_rate.
    • Infected $\rightarrow$ Recovered: Spontaneous transition at recovery_rate.

  12. Apply dynamic parameter transformations to a simulation

    Use the parameter_transforms array in the simulation request body to modify model parameters over time. Each transform object requires a target_parameter and a method. For example, the balcan method can be used to vary a parameter between a min_value and max_value over a specific date range defined by min_date and max_date. To verify the resulting values, set output.include_parameters to true in the request.
    curl -X POST BASE_URL/simulations \
  -H "Content-Type: application/json" \
  -d '{
    "model": {
      "preset": "SIR",
      "parameters": { "transmission_rate": 0.3, "recovery_rate": 0.1 }
    },
    "population": { "name": "United_States" },
    "simulation": {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "Nsim": 10
    },
    "parameter_transforms": [
      {
        "target_parameter": "transmission_rate",
        "method": "balcan",
        "max_date": "2024-01-15",
        "min_date": "2024-07-15",
        "max_value": 1,
        "min_value": 0.1
      }
    ],
    "output": { "include_parameters": true }
  }'