Starsim models are designed to capture disease dynamics within a population of agents, which typically represent people (but may represent animals or other things). In keeping with this, the basic ingredients of a Starsim model are the People class, which store all the relevant attributes about people, a collection of Modules that determine what happens to people on each time step, and the Sim class, which pulls all the components together, runs the simulation, and stores the Results.
Overview of People
More details on the People class are in the separate user guide page, but we give a basic introduction here since people are so central to the model structure. When people are created, by default they come with basic states that are stored for each person. These basic states include age, sex, and whether the person is alive. All of these states are stored as arrays, so the basic structure of the People class can be easily exported to a dataframe, e.g.:
import starsim as ssss.options(jupyter=True)sim = ss.Sim(n_agents=10)sim.init()df = sim.people.to_df()print(df)
Initializing sim with 10 agents
uid slot alive age female ti_dead ti_removed scale
0 0 0 True 31.902851 True NaN NaN 1.0
1 1 1 True 20.196325 False NaN NaN 1.0
2 2 2 True 27.718803 False NaN NaN 1.0
3 3 3 True 19.897545 False NaN NaN 1.0
4 4 4 True 24.346598 False NaN NaN 1.0
5 5 5 True 11.795712 True NaN NaN 1.0
6 6 6 True 32.119804 False NaN NaN 1.0
7 7 7 True 40.963028 False NaN NaN 1.0
8 8 8 True 5.724649 True NaN NaN 1.0
9 9 9 True 29.568054 True NaN NaN 1.0
When a module is added to a sim, this can add additional states to people. Tracking and updating the states of people is one of the main ways in which Starsim models disease dynamics. For example:
Initializing sim with 20 agents
Running 2000 ( 0/51) (0.00 s) ———————————————————— 2%
Running 2010 (10/51) (0.03 s) ••••———————————————— 22%
Running 2020 (20/51) (0.05 s) ••••••••———————————— 41%
Running 2030 (30/51) (0.07 s) ••••••••••••———————— 61%
Running 2040 (40/51) (0.09 s) ••••••••••••••••———— 80%
Running 2050 (50/51) (0.11 s) •••••••••••••••••••• 100%
uid slot alive age female ti_dead ti_removed scale randomnet.participant sis.susceptible sis.infected sis.rel_sus sis.rel_trans sis.ti_infected sis.ti_recovered sis.immunity
0 0 0 True 31.9029 True NaN NaN 1.0 False True False 0.0000 1.0 40.0 48.6462 1.0651
1 1 1 True 20.1963 False NaN NaN 1.0 False False True 0.1108 1.0 41.0 50.1904 0.8892
2 2 2 True 27.7188 False NaN NaN 1.0 False True False 0.3615 1.0 37.0 47.1850 0.6385
3 3 3 True 19.8975 False NaN NaN 1.0 False False True 0.0000 1.0 46.0 55.7581 1.2836
4 4 4 True 24.3466 False NaN NaN 1.0 False False True 0.1712 1.0 50.0 60.2779 1.8288
5 5 5 True 11.7957 True NaN NaN 1.0 False True False 0.3252 1.0 33.0 42.8767 0.6748
6 6 6 True 32.1198 False NaN NaN 1.0 False False True 0.0497 1.0 41.0 52.2641 0.9503
7 7 7 True 40.9630 False NaN NaN 1.0 False False True 0.0000 1.0 42.0 51.3936 1.0716
8 8 8 True 5.7246 True NaN NaN 1.0 False True False 0.0000 1.0 38.0 48.9118 1.0786
9 9 9 True 29.5681 True NaN NaN 1.0 False True False 0.1256 1.0 39.0 48.5133 0.8744
10 10 10 True 12.1764 True NaN NaN 1.0 False True False 0.0987 1.0 37.0 47.9870 0.9013
11 11 11 True 45.5516 True NaN NaN 1.0 False True False 0.4826 1.0 32.0 41.8089 0.5174
12 12 12 True 40.1340 False NaN NaN 1.0 False True False 0.0917 1.0 38.0 49.8741 0.9083
13 13 13 True 42.1071 True NaN NaN 1.0 False True False 0.3681 1.0 36.0 47.7326 0.6319
14 14 14 True 0.2257 False NaN NaN 1.0 False False True 0.0000 1.0 46.0 56.1066 1.5114
15 15 15 True 38.9969 True NaN NaN 1.0 False False True 0.0000 1.0 48.0 60.7664 1.5676
16 16 16 True 0.2895 True NaN NaN 1.0 False True False 0.2516 1.0 36.0 45.7710 0.7484
17 17 17 True 46.9728 False NaN NaN 1.0 False True False 0.3347 1.0 38.0 48.8247 0.6653
18 18 18 True 45.3351 False NaN NaN 1.0 False True False 0.2605 1.0 37.0 46.5924 0.7395
19 19 19 True 49.2198 True NaN NaN 1.0 False False True 0.0000 1.0 45.0 55.5627 1.0141
We can see even in this very simple example with only one disease and 20 agents, a lot of data is generated!
Overview of Modules
Starsim contains the following kinds of modules, listed below in the order that they are typically updated:
Demographics
Diseases
Connectors
Networks
Interventions
Analyzers
Modules typically store parameters (e.g. the transmission probability), states of people (e.g. whether they are susceptible, infected, or recovered), and results (e.g. the number of people infected at each point in time).
Overview of a Sim
The Sim object is responsible for storing assembling, initializing, and running the model. The Sim class contains some top-level parameters (including the number of agents in the simulation, the start and stop times, and the random seed) and results (e.g. the population size over time), but almost all other parameters and results are specific to modules and stored within them. There are more details on the Sim on the linked page.
What happens when you add a module?
When you add a module to a Sim, the module’s parameters, states, and results will be added to the centralized collections of parameters, states, and results that are maintained within the Sim. To illustrate this, let’s create a Sim with an SIR disease module and a random contact network:
import starsim as ss sir = ss.SIR(dur_inf=10, beta=0.2, init_prev=0.4, p_death=0.2)sim = ss.Sim(diseases=sir, networks='random')sim.init() # Initialize the sim to create
The call to sim.init() means that the SIR module gets added to sim.diseases and the RandomNet network gets added to sim.networks. In addition, the following updates are made: * the parameters of the modules are added to the sim’s centralized parameter dictionary, so you can access them via either sim.pars.sir.init_prev or sim.diseases.sir.pars.init_prev * the states specific to each module are added to People, so you can access them via sim.diseases.sir.infected or sim.people.sir.infected * the results specific to each module are added to the centralized Results dictionary of the Sim, so you can access them via sim.diseases.sir.results.n_infected or sim.results.sir.n_infected.
Overview of Results
Once you’ve run a Sim, all the results are stored under sim.results. This is structured similarly to a nested dictionary, with results specific to each module stored in their own dictionaries, like the sim.results.sir.n_infected example above.