diseases
Example disease models: cholera, Ebola, HIV, and measles.
These are illustrative, lightly-parameterized models intended as starting points for building your own disease modules, not as validated models for any specific setting. Core disease base classes (ss.Disease, ss.Infection, ss.SIR, etc.) live in starsim.diseases.
Classes
| Name | Description |
|---|---|
| ART | Scale up antiretroviral therapy over time. |
| CD4_analyzer | Record the CD4 count of every agent at every timestep. |
| Cholera | Cholera, with both direct and environmental (waterborne) transmission. |
| Ebola | Ebola, including severe disease and transmission from unburied bodies. |
| HIV | Simple HIV model with CD4 count dynamics and ART. |
| Measles | Measles, as an SEIR model. |
ART
library.diseases.ART(year, coverage, pars=None, **kwargs)Scale up antiretroviral therapy over time.
Each timestep, agents infected art_delay ago are offered ART, and are treated with a probability interpolated from coverage at the corresponding year. Requires the HIV module.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float / array | year(s) at which coverage is specified | required |
| coverage | float / array | probability of ART initiation at each year | required |
| art_delay | Dist | par: delay from infection to ART eligibility | required |
Examples
import starsim.library as ssl
art = ssl.ART(year=[2000, 2010, 2020], coverage=[0, 0.4, 0.8])CD4_analyzer
library.diseases.CD4_analyzer(**kwargs)Record the CD4 count of every agent at every timestep.
Results are stored in self.cd4, a (timesteps × agents) array. Requires the HIV module. Note that this analyzer allocates a full dense array, so it is best suited to small simulations.
Cholera
library.diseases.Cholera(pars=None, **kwargs)Cholera, with both direct and environmental (waterborne) transmission.
An SEIR-type model in which exposed agents become infected, a fraction of whom become symptomatic; symptomatic agents may die, and everyone else recovers. Asymptomatic agents are infectious but shed far less bacteria (asymp_trans). In addition to person-to-person transmission via the network, infectious agents shed into a single well-mixed environmental reservoir, which decays exponentially and drives indirect transmission with a dose-response governed by half_sat_rate.
Parameter values are drawn from the literature; see the source for citations.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| beta | prob | per-contact transmission probability | required |
| init_prev | Dist | initial prevalence | required |
| dur_exp | Dist | duration from exposure to infectiousness | required |
| dur_asymp2rec | Dist | duration from infection to recovery, asymptomatic agents | required |
| dur_symp2rec | Dist | duration from symptoms to recovery | required |
| dur_symp2dead | Dist | duration from symptoms to death | required |
| p_death | Dist | probability of death among symptomatic agents | required |
| p_symp | Dist | probability an infection is symptomatic | required |
| asymp_trans | float | relative transmissibility of asymptomatic agents | required |
| beta_env | prob | scale factor for environmental transmission | required |
| half_sat_rate | float | environmental dose infecting 50% of those exposed | required |
| shedding_rate | freq | rate at which infectious agents shed to the environment | required |
| decay_rate | rate | rate at which environmental bacteria die off | required |
| p_env_transmit | Dist | environmental transmission probability (set each step) | required |
Attributes
| Name | Type | Description |
|---|---|---|
| exposed | BoolState | infected but not yet infectious |
| asymptomatic | alias |
infectious but not symptomatic |
| symptomatic | BoolState | currently symptomatic |
| recovered | BoolState | recovered and immune |
| ti_exposed | FloatArr | timestep of exposure |
| ti_symptomatic | FloatArr | timestep symptoms began |
| ti_recovered | FloatArr | timestep of recovery |
| ti_dead | FloatArr | timestep of death |
Examples
import starsim as ss
import starsim.library as ssl
sim = ss.Sim(diseases=ssl.Cholera(), networks='random')
sim.run()
sim.plot()Methods
| Name | Description |
|---|---|
| calc_environmental_prev | Calculate environmental prevalence |
| infect | Add indirect transmission |
| init_results | Initialize results |
| set_progression | Schedule symptoms, recovery, and death |
| step_die | Reset infected/recovered flags for dead agents |
| step_state | Adapted from https://github.com/optimamodel/gavi-outbreaks/blob/main/stisim/gavi/cholera.py |
calc_environmental_prev
library.diseases.Cholera.calc_environmental_prev()Calculate environmental prevalence
infect
library.diseases.Cholera.infect()Add indirect transmission
init_results
library.diseases.Cholera.init_results()Initialize results
set_progression
library.diseases.Cholera.set_progression(uids)Schedule symptoms, recovery, and death
step_die
library.diseases.Cholera.step_die(uids)Reset infected/recovered flags for dead agents
step_state
library.diseases.Cholera.step_state()Adapted from https://github.com/optimamodel/gavi-outbreaks/blob/main/stisim/gavi/cholera.py Original version by Dom Delport
Ebola
library.diseases.Ebola(pars=None, **kwargs)Ebola, including severe disease and transmission from unburied bodies.
Extends ss.SEIR with severe and buried states. Exposed agents become infectious, a fraction progress to severe disease, and a fraction of those die; everyone else recovers. Severe agents are more infectious (sev_factor), and dead agents remain infectious until buried (unburied_factor), with safe burials happening immediately and unsafe burials after a delay.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| init_prev | Dist | initial prevalence | required |
| beta | prob | per-contact transmission probability | required |
| sev_factor | float | relative transmissibility of severe agents | required |
| unburied_factor | float | relative transmissibility of unburied bodies | required |
| dur_exp | Dist | duration from exposure to symptoms (i.e. infectiousness) | required |
| dur_symp2sev | Dist | duration from symptoms to severe disease | required |
| dur_sev2dead | Dist | duration from severe disease to death | required |
| dur_dead2buried | Dist | duration from death to (unsafe) burial | required |
| dur_symp2rec | Dist | duration from symptoms to recovery, non-severe agents | required |
| dur_sev2rec | Dist | duration from severe disease to recovery | required |
| p_sev | Dist | probability of progressing to severe disease | required |
| p_death | Dist | probability of death among severe agents | required |
| p_safe_bury | Dist | probability of a safe (immediate) burial | required |
Attributes
| Name | Type | Description |
|---|---|---|
| exposed | BoolState | infected but not yet infectious |
| severe | BoolState | currently severely ill |
| buried | BoolState | dead and buried (no longer infectious) |
| ti_exposed | FloatArr | timestep of exposure |
| ti_severe | FloatArr | timestep severe symptoms began |
| ti_buried | FloatArr | timestep of burial |
Examples
import starsim as ss
import starsim.library as ssl
sim = ss.Sim(diseases=ssl.Ebola(), networks='random')
sim.run()
sim.plot()Methods
| Name | Description |
|---|---|
| set_progression | Schedule severe disease, recovery, death, and burial |
| step_die | Reset states for dead agents |
| step_state | Progress exposed -> infectious -> severe -> recovered/dead -> buried |
set_progression
library.diseases.Ebola.set_progression(uids)Schedule severe disease, recovery, death, and burial
step_die
library.diseases.Ebola.step_die(uids)Reset states for dead agents
step_state
library.diseases.Ebola.step_state()Progress exposed -> infectious -> severe -> recovered/dead -> buried
HIV
library.diseases.HIV(pars=None, **kwargs)Simple HIV model with CD4 count dynamics and ART.
Infected agents have a CD4 count that declines towards cd4_min while untreated and recovers towards cd4_max while on ART, at a rate set by cd4_rate. The per-timestep probability of death scales with how far the CD4 count has fallen, so agents with low CD4 counts die soonest. Agents on ART have their transmissibility reduced by art_efficacy. Vertical transmission is supported: set_congenital() infects the newborn.
Use with ART to scale up treatment over time, and CD4_analyzer to record CD4 counts. Since beta defaults to 0, it must be set for transmission to occur.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| beta | float | per-contact transmission probability (0 by default) | required |
| cd4_min | float | CD4 count approached by untreated agents | required |
| cd4_max | float | CD4 count approached by agents on ART | required |
| cd4_rate | float | number of timesteps to close the CD4 gap | required |
| eff_condoms | float | efficacy of condoms (not currently used internally) | required |
| art_efficacy | float | proportional reduction in transmission on ART | required |
| init_prev | Dist | initial prevalence | required |
| death_dist | Dist | death probability, by default CD4-modulated p_death |
required |
| p_death | rate | baseline death rate per unit time (not per infection) | required |
Attributes
| Name | Type | Description |
|---|---|---|
| on_art | BoolState | currently on ART |
| ti_art | FloatArr | timestep of ART initiation |
| ti_dead | FloatArr | timestep of HIV-caused death |
| cd4 | FloatArr | current CD4 count (default 500) |
Examples
import starsim as ss
import starsim.library as ssl
sim = ss.Sim(
diseases = ssl.HIV(beta=0.02, init_prev=0.05),
networks = 'random',
interventions = ssl.ART(year=[2000, 2020], coverage=[0, 0.8]),
)
sim.run()
sim.plot()Methods
| Name | Description |
|---|---|
| init_results | Initialize results |
| step_state | Update CD4 |
init_results
library.diseases.HIV.init_results()Initialize results
step_state
library.diseases.HIV.step_state()Update CD4
Measles
library.diseases.Measles(pars=None, **kwargs)Measles, as an SEIR model.
Configures ss.SEIR with measles natural-history parameters: exposed agents become infectious after dur_exp, then either die (with probability p_death) or recover after dur_inf. Natural history parameters are from the US CDC.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| beta | prob | per-contact transmission probability | required |
| init_prev | Dist | initial prevalence | required |
| dur_exp | Dist | duration from exposure to infectiousness | required |
| dur_inf | Dist | duration of infectiousness | required |
| p_death | Dist | probability of death among infected agents | required |
Attributes
| Name | Type | Description |
|---|---|---|
| exposed | BoolState | infected but not yet infectious |
| ti_exposed | FloatArr | timestep of exposure |
Examples
import starsim as ss
import starsim.library as ssl
sim = ss.Sim(diseases=ssl.Measles(), networks='random')
sim.run()
sim.plot()