What is Starsim?

Starsim is an open-source agent-based modeling framework for simulating the spread of diseases among agents via dynamic transmission networks. Starsim supports:

  • Co-transmission of multiple diseases at once, capturing how they interact biologically and behaviorally;
  • Non-infectious diseases, either on their own or as factors affecting the transmission or mortality of infectious diseases;
  • Detailed modeling of mother-child relationships starting from conception, allowing investigation of infant and childhood diseases;
  • Multiple types of transmission network, including theoretical (e.g. Erdős–Rényi) and realistic (e.g. age-assortative sexual partnerships);
  • Different intervention types, such as vaccines or treatments, and showing their impact through different delivery methods such as mass campaigns or targeted outreach.

For more information, please check out the:

Why Starsim?

High performance

Optimized vector computations and just-in-time Numba compilation mean Starsim achieves C++ speeds from pure Python.

Easy to use

Starsim's modular structure means you can reuse or adapt existing disease models, transmission networks, and demographics.

Global community

We're a community, not a product. We believe in transparency and collaboration to ensure the best global health outcomes.

Installation

If you have Python, you can install Starsim:

> pip install starsim

Examples

This is what an extremely simple Starsim simulation looks like:

  1. Create a susceptible-infectious-recovered (SIR) disease model with default parameters.
  2. Create a random transmission network between agents (also with default parameters).
  3. Run the simulation and plot the results.
import starsim as ss

sim = ss.Sim(diseases='sir', networks='random') # Create the sim
sim.run() # Run the sim
sim.plot() # Plot the results

You can easily customize model parameters, and run simulations in parallel:

  1. Create a dictionary defining the parameters of the simulation.
  2. Modify only those parameters you want to differ between scenarios.
  3. Run the simulations in parallel, and plot the results you are interested in.
import starsim as ss
import sciris as sc

# Set the parameters for the baseline simulation
pars1 = sc.objdict( # Note: can also use regular Python dictionary
	n_agents = 10_000,     # Number of agents to simulate
	networks = sc.objdict( # *Networks* add detail on how the agents interact with each other
		type = 'random',   # Here, we use a 'random' network
		n_contacts = 4     # Each person has an average of 4 contacts with other people
	),
	diseases = sc.objdict( # *Diseases* add detail on what diseases to model
		type = 'sis',      # Here, we're creating an SIS disease
		init_prev = 0.1,   # Proportion of the population initially infected
		beta = 0.1,        # Probability of transmission between contacts
	)
)

# Make a modified version of the parameters for the scenario
pars2 = pars1.copy(deep=True)
pars2.diseases.beta = 0.2

# Create the simulations
s1 = ss.Sim(pars1, label='Low transmission')
s2 = ss.Sim(pars2, label='High transmission')

# Run and plot the simulations
msim = ss.parallel(s1, s2)
msim.plot('sis_n_infected')

Everything in Starsim can be customized, including diseases, demographics, and intervention. This example shows how to write custom interventions, namely a vaccine product and vaccination campaign:

import starsim as ss
import matplotlib.pyplot as plt

# Define the simulation parameters
pars = dict(
	n_agents = 20_000,
	birth_rate = 20,
	death_rate = 15,
	networks = dict(
		type = 'random',
		n_contacts = 4
	),
	diseases = dict(
		type = 'sir',
		dur_inf = 10,
		beta = 0.1,
	)
)

# Create the product: a vaccine with 50% efficacy
my_vaccine = ss.sir_vaccine(efficacy=0.5)

# Create the vaccine campaign
campaign = ss.routine_vx(
	start_year = 2015,    # Begin vaccination in 2015
	prob = 0.2,           # 20% coverage
	product = my_vaccine  # Use the MyVaccine product
)

# Now create two sims: a baseline sim and one with the intervention
sim_base = ss.Sim(pars=pars)
sim_intv = ss.Sim(pars=pars, interventions=campaign)

# Run sims in parallel
sims = ss.parallel(sim_base, sim_intv).sims
base = sims[0].results
vax = sims[1].results

# Plot
plt.figure()
plt.plot(base.yearvec, base.sir.prevalence, label='Baseline')
plt.plot(vax.yearvec, vax.sir.prevalence, label='Vaccine')
plt.axvline(x=2015, color='k', ls='--')
plt.title('Vaccine impact')
plt.xlabel('Year')
plt.ylabel('Prevalence')
plt.legend()

Paper

Starsim has not yet been published. But if you want to cite it, please use:

Cliff Kerr, Robyn Stuart, Romesh Abeysuriya, Jamie Cohen, Paula Sanz-Leon, Alina Muellenmeister, Keith Alexander Ashe, Luojun Yang, 
Clinton Collins, Daniel Klein (2024). Starsim: An agent-based framework for modeling health and disease. In preparation.

Contact

Have questions? Want to collaborate? We'd love to hear from you!