Starsim

https://docs.starsim.org
Admin
Starsim is an agent-based modeling framework for simulating disease spread through dynamic...
Tokens:231,099
Snippets:2,613
Trust Score:6.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Starsim with uv

Source: https://docs.starsim.org/

Initialize a new project with uv, add Starsim as a dependency, and install it.

```bash
uv init example
cd example
uv add starsim
```

--------------------------------

### Configure Simulation Time and Timestep

Source: https://docs.starsim.org/tutorials/t2_model.html

Customize simulation start date, end date, and timestep. This example simulates for one year with a monthly timestep.

```python
sim = ss.Sim(start='2020-01-01', stop='2021-01-01', dt=ss.months(1), diseases='sis', networks=network)  # Simulate from 2020 for 1 year with a monthly timestep
sim.run().plot()
```

--------------------------------

### Install Starsim Locally from Source

Source: https://docs.starsim.org/

Install Starsim locally from its repository, including optional development dependencies.

```bash
pip install -e .[dev]
```

--------------------------------

### Install and Initialize R-Starsim

Source: https://docs.starsim.org/

Install the R version of Starsim from GitHub and initialize it. Requires the devtools package.

```r
# install.packages("devtools")
devtools::install_github("starsimhub/rstarsim")
library(starsim)
init_starsim()
```

--------------------------------

### Initialize Post-Setup

Source: https://docs.starsim.org/api/modules.html

Sets the initial values for module states after all setup is complete.

```python
modules.Module.init_post()
```

--------------------------------

### Help and Defaults

Source: https://docs.starsim.org/api/settings.html

How to get help on options and retrieve default values.

```APIDOC
## Help and Defaults

### Description
Access help information and default values for Starsim options.

### Examples
```python
# Print detailed help on all options
ss.options.help(detailed=True)

# Get the default value for a specific option
default_dpi = ss.options.get_default('dpi')
```
```

--------------------------------

### Example: Using Timeline.now()

Source: https://docs.starsim.org/api/timeline.html

Demonstrates creating a Timeline instance and using the now() method to retrieve time in different formats.

```python
t = ss.Timeline(start='2021-01-01', stop='2022-02-02', dt='week')
t.ti = 25
t.now() # Returns <2021-06-25>
t.now('date') # Returns <2021-06-25>
t.now('year') # Returns 2021.479
t.now('str') # Returns '2021-06-25'
```

--------------------------------

### Example: Create and run a simulation with MixingPool

Source: https://docs.starsim.org/api/networks.html

Demonstrates how to set up parameters for a MixingPool, define an initialization function, create a SIS disease model, and run a simulation.

```python
import starsim as ss

# Set the parameters
mp_pars = dict(
    src = lambda sim: sim.people.male, # only males are infectious
    dst = None, # all agents are susceptible
    beta = ss.Rate(0.2),
    n_contacts = ss.poisson(lam=4),
)

# Seed 5% of the male population
def p_init(self, sim, uids):
    return 0.05*sim.people.male

# Create and run the sim
sis = ss.SIS(init_prev=p_init)
mp = ss.MixingPool(**mp_pars)
sim = ss.Sim(diseases=sis, networks=mp)
sim.run()
sim.plot()
```

--------------------------------

### Getting help on Starsim options

Source: https://docs.starsim.org/whatsnew.html

The `ss.options.help()` method provides detailed information about available configuration options. Use `detailed=True` for more in-depth explanations.

```python
ss.options.help()
ss.options.help(detailed=True)
```

--------------------------------

### Disease Module Step State Example

Source: https://docs.starsim.org/user_guide/basics_sim.html

This example demonstrates the `step_state` method for a disease module, typically handling disease progression before transmission.

```python
def step_state(self):
    """ Progress infectious -> recovered """
    recovered = (self.infected & (self.ti_recovered <= self.ti)).uids
    self.infected[recovered] = False
    self.susceptible[recovered] = True
    self.update_immunity()
    return
```

--------------------------------

### Install Starsim with pip

Source: https://docs.starsim.org/

Install the Starsim library using pip. This is the most common method for Python users.

```bash
pip install starsim
```

--------------------------------

### Campaign Screening Example

Source: https://docs.starsim.org/api/interventions.html

Creates a campaign screening intervention. The first example screens 20% of the eligible population in 2020. The second screens 20% in both 2025 and 2030.

```python
screen1 = ss.campaign_screening(product=my_prod, prob=0.2, years=2030) # Screen 20% of the eligible population in 2020
screen2 = ss.campaign_screening(product=my_prod, prob=0.02, years=[2025,2030]) # Screen 20% of the eligible population in 2025 and again in 2030
```

--------------------------------

### Example: Mocking a Distribution

Source: https://docs.starsim.org/api/distributions.html

Shows how to create a mocked distribution for testing, including setting a time step. It then calls `rvs` on the mocked distribution.

```python
dist = ss.normal(3, 2, unit='years').mock(dt=ss.days(1))
dist.rvs(10)
```

--------------------------------

### Campaign Triage Example

Source: https://docs.starsim.org/api/interventions.html

Sets up a campaign triage intervention. This example, for instance, triages all positive screens into confirmatory testing in 2030 with a 90% probability.

```python
# Example: In 2030, triage all positive screens into confirmatory testing
screened_pos = lambda sim: sim.interventions.screening.outcomes['positive']
triage1 = ss.campaign_triage(product=my_triage, eligibility=screen_pos, prob=0.9, years=2030)
```

--------------------------------

### Basic Simulation Initialization

Source: https://docs.starsim.org/user_guide/advanced_random.html

A minimal example of initializing a Starsim simulation object with agent count and duration.

```text
Sim(n=20; 0—1.0)
```

--------------------------------

### Run Multiple Simulations

Source: https://docs.starsim.org/api/run.html

Example of setting up and running multiple `Sim` objects using `MultiSim`. This demonstrates creating distinct simulation scenarios and then executing them in parallel.

```python
import starsim as ss

s1 = ss.Sim(networks='random', diseases=ss.SIS(beta=0.02), label='Low transmission')
s2 = ss.Sim(networks='random', diseases=ss.SIS(beta=0.05), label='Medium transmission')
s3 = ss.Sim(networks='random', diseases=ss.SIS(beta=0.10), label='High transmission')

msim = ss.MultiSim(sims=[s1, s2, s3])
msim.run()

# Plot individual sims
msim.plot()

# Calculate mean results across sims and plot
msim.mean()
msim.plot()
```

--------------------------------

### Define Simulation Setup Function

Source: https://docs.starsim.org/user_guide/workflows_samples.html

Encapsulates the creation of a simulation object with specified parameters. This promotes code reusability and modularity.

```python
def get_sim(seed, p_death):
    ppl = ss.People(2000)
    net = ss.RandomNet(n_contacts=ss.poisson(5))
    sir = ss.SIR(p_death=p_death)
    sim = ss.Sim(people=ppl, networks=net, diseases=sir, rand_seed=seed)
    sim.init(verbose=0)
    return sim
```

--------------------------------

### init

Source: https://docs.starsim.org/api/distributions.html

Calculates the starting seed and creates the Random Number Generator (RNG).

```APIDOC
## init

### Description
Calculate the starting seed and create the RNG.

### Method
```python
distributions.Dist.init(force=True)
```
```

--------------------------------

### Routine Screening Examples

Source: https://docs.starsim.org/api/interventions.html

Creates routine screening interventions. The first screens 2% annually. The second starts screening in 2020. The third scales up screening from 0.5% to 2.5% over five years starting in 2020.

```python
screen1 = ss.routine_screening(product=my_prod, prob=0.02) # Screen 2% of the eligible population every year
screen2 = ss.routine_screening(product=my_prod, prob=0.02, start_year=2020) # Screen 2% every year starting in 2020
screen3 = ss.routine_screening(product=my_prod, prob=np.linspace(0.005,0.025,5), years=np.arange(2020,2025)) # Scale up screening over 5 years starting in 2020
```

--------------------------------

### Timing iteration after preload (second run)

Source: https://docs.starsim.org/user_guide/workflows_samples.html

This example shows the timing of iterating through dataframes after preloading, demonstrating consistent fast access from the cache.

```python
with sc.Timer():
    for df in res:
        continue
```

```text
Elapsed time: 9.59 ms
```

--------------------------------

### Start Simulation Step

Source: https://docs.starsim.org/api/sim.html

Initiates the simulation step. This method primarily handles progress printing, with actual state changes occurring within the simulation modules.

```python
sim.Sim.start_step()
```

--------------------------------

### Product.init_pre

Source: https://docs.starsim.org/api/products.html

Initialize the product. Skips initialization if the product has already been initialized.

```APIDOC
## Product.init_pre

### Description
Initialize the product; skips if already initialized.

### Method
products.Product.init_pre(sim)

### Parameters
- **sim** (Simulation) - The simulation object.
```

--------------------------------

### Define Birth Outcomes for Congenital Infections

Source: https://docs.starsim.org/api/diseases.html

Example of defining parameters for congenital outcomes, including outcome keys and a probabilistic assignment. This setup is used by `set_congenital`.

```python
self.define_pars(
    birth_outcome_keys = ['stillborn', 'congenital', 'normal'],
    birth_outcomes     = sc.objdict(default=ss.choice(a=3, p=[0.3, 0.4, 0.3])),  # Illustrative placeholder
)
```

--------------------------------

### Profile Module.start_step Function

Source: https://docs.starsim.org/user_guide/advanced_profiling.html

This profiling snippet focuses on the `Module.start_step` function, indicating the time consumed by module-specific initialization or setup routines within the simulation loop.

```python
@required()
```

--------------------------------

### Compare Mixing Pool and Contact Network Transmission

Source: https://docs.starsim.org/tutorials/t5_networks.html

This example demonstrates the setup and simulation of both a mixing pool and a contact network to compare their disease transmission patterns. It requires importing the necessary simulation and network modules.

```python
# Simple mixing pool example
mp = ss.MixingPool(beta=1.0, n_contacts=ss.poisson(lam=3))
sir_mp = ss.SIR()
sim_mp = ss.Sim(diseases=sir_mp, networks=mp, verbose=0, label='Mixing Pool')

# Equivalent contact network
net = ss.RandomNet(n_contacts=ss.poisson(lam=3))
sir_net = ss.SIR(beta=ss.peryear(0.1))
sim_net = ss.Sim(diseases=sir_net, networks=net, verbose=0, label='Contact Network')

msim = ss.MultiSim([sim_mp, sim_net]).run()
msim.plot()
```

--------------------------------

### Initialize and Run Simulation

Source: https://docs.starsim.org/user_guide/basics_people.html

Initializes a simulation with a specified number of people and runs it. This setup is common for observing disease spread or other population-level dynamics.

```python
ppl = ss.People(30)
sim = ss.Sim(people=ppl, diseases=ss.SIS(init_prev=0.1), networks=ss.RandomNet())
sim.run()
print(f'Number of infected people: {sim.people.sis.infected.sum()}')
```

--------------------------------

### Define Simple SIS Vaccine Intervention

Source: https://docs.starsim.org/tutorials/t6_interventions.html

Define a simple vaccine intervention as a function for the SIS disease model. This function modifies the relative transmission rate of the SIS disease when the simulation reaches a specified start year. Ensure the 'diseases' parameter in the simulation setup includes 'sis'.

```python
import starsim as ss

def simple_sis_vaccine(sim, start=2030, eff=0.9):
    if sim.now == start:
        sim.diseases.sis.rel_trans[:] *= 1-eff
    return

pars = dict(
    start=2000,
    stop=2050,
    diseases='sis',
    networks='random',
    interventions=simple_sis_vaccine,
)

sim = ss.Sim(pars)
sim.run()
sim.plot()
ss.show()
```

--------------------------------

### Define a Normal CalibComponent for Disease Prevalence

Source: https://docs.starsim.org/user_guide/workflows_calibration.html

This example demonstrates how to create a `Normal` calibration component to model disease prevalence. It uses the `prevalent` conformer to align simulation output with real data points specified by date. The `expected` argument provides the observed prevalence, and `extract_fn` specifies how to get prevalence from simulation results. Optional `sigma2` can be provided to define variance.

```python
prevalence = ss.Normal(
    name = 'Disease prevalence',
    conform = 'prevalent',

    expected = pd.DataFrame({
        'x': [0.13, 0.16, 0.06],    # Prevalence of infection
    }, index=pd.Index([ss.date(d) for d in ['2020-01-12', '2020-01-25', '2020-02-02']], name='t')), # On these dates
    
    extract_fn = lambda sim: pd.DataFrame({
        'x': sim.results.sir.prevalence,
    }, index=pd.Index(sim.results.timevec, name='t')),

    # You can specify the variance as well, but it's optional (max likelihood estimates will be used if not provided)
    # This could be a single float or an array with the same shape as the expected values
    sigma2 = 0.05, # e.g. (num_replicates/sigma2_model + 1/sigma2_data)^-1
    # Alternatively, specify a variance for each data point
    #sigma2 = np.array([0.05, 0.25, 0.01])
)
```

--------------------------------

### Samples.new Method

Source: https://docs.starsim.org/api/samples.html

Creates a new Samples object, saves it to disk, and returns it.

```APIDOC
## Samples.new Method

### Description
Creates a new Samples object and saves it.

### Parameters
*   **folder** (`path`) - The folder to save the zip file in. (Required)
*   **outputs** - A list of tuples `(df: pd.DataFrame, summary_row: dict)` where the summary row must contain an entry for 'seed'. (Required)
*   **identifiers** (`list`, optional) - A list of columns to use as identifiers. These should appear in the summary dataframe and have the same value for all samples. Useful for generating multiple sets of results (e.g., for scenarios).
*   **fname** (`str`, optional) - Filename for the zip file; auto-generated from identifiers if not supplied.
*   **verbose** (`bool`, optional) - Whether to print the save path (default True).
```

--------------------------------

### sim.Sim.init_modules_pre

Source: https://docs.starsim.org/api/sim.html

Initialize all the modules with the sim.

```APIDOC
## init_modules_pre

### Description
Initialize all the modules with the sim.

### Method Signature
sim.Sim.init_modules_pre()
```

--------------------------------

### Demonstrate PRNG with NumPy

Source: https://docs.starsim.org/user_guide/advanced_random.html

This example uses numpy to demonstrate how setting the same seed for a pseudo-random number generator (PRNG) results in identical sequences of random numbers.

```python
import numpy as np
np.random.seed(42) # Set the seed to 42
draws1 = np.random.random(size=10) # Draw 10 realizations
print(f'First draws: {draws1.round(2)}')

np.random.seed(42) # Reset the seed to 42
draws2 = np.random.random(size=10) # Draw 10 realizations
print(f'Second draws: {draws2.round(2)}')

assert np.array_equal(draws1, draws2), "The two sets of draws should be equal since the seed is the same."
```

--------------------------------

### Initialize Product Base Class

Source: https://docs.starsim.org/api/products.html

Constructor for the generic Product base class. Subclasses implement the administer() method.

```python
products.Product(name=None, label=None, **kwargs)
```

--------------------------------

### Run a Simple Starsim Demo in Python

Source: https://docs.starsim.org/

Execute a basic demo of the Starsim library to see it in action.

```python
import starsim as ss
ss.demo()
```

--------------------------------

### Initialize Pre-Setup

Source: https://docs.starsim.org/api/modules.html

Performs preliminary initialization steps for a module before the simulation begins. This method is called once during Sim initialization.

```python
modules.Module.init_pre(sim, force=False)
```

--------------------------------

### init

Source: https://docs.starsim.org/api/sim.html

Performs all initializations required for the simulation to begin.

```APIDOC
## init

### Description
Perform all initializations for the sim

### Method Signature
`sim.Sim.init()`
```

--------------------------------

### SIR Resampling Output Example

Source: https://docs.starsim.org/user_guide/workflows_sir_calibration.html

This snippet shows an example of the output generated after performing SIR resampling, including the calculated ESS and the number of samples to be resampled.

```text
============================================================
Effective Sample Size (ESS) = 7.3 out of 100
WARNING: ESS is below 30, consider increasing N
============================================================
Resampling K = 11 samples from the weighted ensemble of N = 100 samples

```

--------------------------------

### Lognormal Distribution (Explicit) Example

Source: https://docs.starsim.org/api/distributions.html

Example showing how to sample from the explicit lognormal distribution and verify its mean. The mean of the sampled data should be close to the specified 'mean' parameter.

```python
ss.lognorm_ex(mean=2, std=1, strict=False).rvs(1000).mean() # Should be close to 2
```

--------------------------------

### start_step

Source: https://docs.starsim.org/api/sim.html

Initiates a simulation step, primarily handling progress printing. Actual state changes occur within the modules.

```APIDOC
## start_step

### Description
Start the step – only print progress; all actual changes happen in the modules

### Method Signature
`sim.Sim.start_step()`
```

--------------------------------

### Get Current Simulation Time

Source: https://docs.starsim.org/api/timeline.html

Retrieves the current simulation time in various formats. Specify the 'key' parameter to get time as 'time' (default), 'year', 'date', or 'str'.

```python
timeline.Timeline.now(key=None)
```

--------------------------------

### Adapt HIV Example for MF and MSM Transmission

Source: https://docs.starsim.org/tutorials/solutions.html

Use this code to adapt an HIV transmission example to include both MF and MSM transmission networks by specifying separate beta values for each network.

```python
import starsim as ss
import starsim.library as ssl

# HIV transmitting on both networks
hiv = ssl.diseases.HIV(beta={'mf': [0.05, 0.025], 'msm': [0.08, 0.08]})

# Heterosexual and MSM networks
mf  = ss.MFNet(duration=1/24, acts=80)
msm = ss.MSMNet(duration=1/24, acts=80)

pars = dict(start=2000, dur=20, dt=1/12, verbose=0)
sim = ss.Sim(pars=pars, diseases=hiv, networks=[mf, msm])
sim.run()
sim.plot('hiv')
```

--------------------------------

### Timeline with Start, Stop, and dt

Source: https://docs.starsim.org/user_guide/advanced_time.html

Illustrates how a timeline object is initialized with start, stop, and a time step (dt). The output displays the time points and the total number of steps plus one.

```python
t = ss.Timeline(start=0, stop=1, dt=1.0)
t.init()
print('Time points:', t.timevec)
print('npts:', t.npts, '(= 1 step + 1)')
```

--------------------------------

### sim.Sim.init_dists

Source: https://docs.starsim.org/api/sim.html

Initialize the distributions.

```APIDOC
## init_dists

### Description
Initialize the distributions.

### Method Signature
sim.Sim.init_dists()
```

--------------------------------

### utils.ndict.get

Source: https://docs.starsim.org/api/utils.html

Get an entry from this ndict.

```APIDOC
## utils.ndict.get

### Description
Get an entry from this ndict.
See also `sim.get_module()`. Note: if a type is supplied that matches more than one entry, this function only returns the first match. Use `Sim.get_modules()` to handle multiple matches.

### Signature
```python
utils.ndict.get(key, default=None, match_case=False)
```

### Parameters
- **key** (str / type): The object to get, either a type (e.g. `ss.SIR`) or a string (e.g. `'sir'`). This parameter is required.
- **default** (`obj`): What to return if not found. Defaults to `None`.
- **match_case** (bool): If False (default), ignore case with string matching. Defaults to `False`.

### Examples
```python
sim = ss.Sim(diseases=ss.SIR(name='MySIR'), networks='random')
sim.run()

# All return sim.diseases.MySIR
sim.diseases.get('MySIR')
sim.diseases.get('mysir')
sim.diseases.get(ss.SIR)
```
```

--------------------------------

### Configure Notebook and Import Libraries

Source: https://docs.starsim.org/user_guide/workflows_sir_calibration.html

Sets up the notebook environment for autoreloading and inline plotting, then imports necessary libraries for Starsim, Optuna, and data manipulation.

```python
# Configure notebook autoreloading and inline plotting
%load_ext autoreload
%autoreload 2
%matplotlib inline

##%% Imports and settings
import numpy as np
import pandas as pd
import sciris as sc
import warnings
import optuna
import seaborn as sns
from IPython.display import display
import matplotlib.pyplot as plt
from scipy.special import betaln, gammaln
import starsim as ss

# Set additional options
optuna.logging.set_verbosity(optuna.logging.CRITICAL)
ss.options(jupyter=True)
warnings.simplefilter(action='ignore', category=FutureWarning)
warnings.filterwarnings('ignore', category=optuna.exceptions.ExperimentalWarning)
```

--------------------------------

### now

Source: https://docs.starsim.org/api/timeline.html

Get the current simulation time in different formats.

```APIDOC
## now

### Description
Get the current simulation time.

### Method
`timeline.Timeline.now(key=None)`

### Parameters
#### Query Parameters
- **key** (str) - Optional - which type of time to get: “time” (default), “year”, “date”, “tvec”, or “str”

### Examples
```python
t = ss.Timeline(start='2021-01-01', stop='2022-02-02', dt='week')
t.ti = 25
t.now() # Returns <2021-06-25>
t.now('date') # Returns <2021-06-25>
t.now('year') # Returns 2021.479
t.now('str') # Returns '2021-06-25'
```
```

--------------------------------

### Initialize Timeline Object

Source: https://docs.starsim.org/api/timeline.html

Instantiate a Timeline object with specified start, stop, and time step parameters. Supports various input types for start and stop, including strings, numbers, and date/duration objects. The time step can also be a duration object.

```python
t1 = ss.Timeline(
    start=2000,
    stop=2020,
    dt=1.0
)
t2 = ss.Timeline(start='2021-01-01', stop='2021-04-04', dt=ss.days(2))
```

--------------------------------

### Example: Resetting and Resampling Distribution

Source: https://docs.starsim.org/api/distributions.html

Demonstrates how to reset a distribution's state to its original or most recent saved state and then resample. It asserts that resampling after reset yields predictable results.

```python
dist = ss.random(seed=5).init()
r1 = dist(5)
r2 = dist(5)
dist.reset(-1)
r3 = dist(5)
dist.reset(0)
r4 = dist(5)
assert all(r1 != r2)
assert all(r2 == r3)
assert all(r4 == r1)
```

--------------------------------

### Dist.rand

Source: https://docs.starsim.org/api/distributions.html

Provides a simple way to get random numbers.

```APIDOC
## rand

### Description
Simple way to get simple random numbers

### Parameters
- **size** - Required - The size of the random numbers to generate.

### Method
`distributions.Dist.rand`
```

--------------------------------

### init

Source: https://docs.starsim.org/api/loop.html

Parses the simulation object into the integration plan.

```APIDOC
## init

### Description
Parse the sim into the integration plan

### Method Signature
```
loop.Loop.init()
```
```

--------------------------------

### rand

Source: https://docs.starsim.org/api/distributions.html

Provides a simple way to get random numbers.

```APIDOC
## rand

### Description
Simple way to get simple random numbers.

### Method
```python
distributions.Dist.rand()
```
```

--------------------------------

### get_inds

Source: https://docs.starsim.org/api/networks.html

Get the specified indices from the edgelist and return them as a dict.

```APIDOC
## get_inds

### Description
Get the specified indices from the edgelist and return them as a dict.

### Method
Not specified (likely internal or part of a larger object)

### Endpoint
Not applicable

### Parameters
#### Query Parameters
- **inds** (int, array, slice) - Required - the indices to find
- **remove** (bool) - Optional - whether to remove the indices. Defaults to `False`.
```

--------------------------------

### init_pre

Source: https://docs.starsim.org/api/networks.html

Initialize with the sim, initialize the edges, and validate p1 and p2.

```APIDOC
## init_pre

### Description
Initialize with the sim, initialize the edges, and validate p1 and p2.

### Method
Not specified (likely internal or part of a larger object)

### Endpoint
Not applicable

### Parameters
#### Request Body
- **sim** (object) - Required
```

--------------------------------

### Sample from Prior and Run Simulations

Source: https://docs.starsim.org/user_guide/workflows_sir_calibration.html

This snippet sets up prior samples, generates random seeds, prepares parameter dictionaries, and runs StarSim simulations in parallel to collect trajectories. Ensure 'sc' and 'run_starsim' are imported and configured.

```python
N = 100  # Number of prior samples (more is better, but slower)
# For Beta-Binomial, the concentration parameter. Lower kappa --> broader
# posterior and higher effective sample size (ESS) for the same N. But not a
# free parameter, kappa comes from the over-dispersion in the observed data.
kappa = 10 

# Sample from the prior
prior_samples = sample_from_prior(size=N)

rand_seeds = np.random.randint(0, 1e6, size=2*N)
rand_seeds = np.unique(rand_seeds)[:N]

# Prepare parameter dicts for each sample
sample_pars_list = [
    {
        'pars': {'beta': {'value': row['beta']}, 'gamma': {'value': row['gamma']}},
        'rand_seed': rand_seeds[idx]  # Random seed for each simulation
    }
    for idx, row in prior_samples.iterrows()
]

# Run simulations in parallel and collect trajectories
sim_results_list = sc.parallelize(run_starsim, iterkwargs=sample_pars_list, serial=False)

# Store latent state trajectories for each sample
trajectories = pd.concat(sim_results_list) \
    .reset_index() \
    .set_index(['rand_seed', 'Time'])

```

--------------------------------

### check_version

Source: https://docs.starsim.org/api/debugtools.html

Check the installed Starsim version against an expected version string.

```APIDOC
## check_version

### Description
Check the expected Starsim version with the one actually installed. The expected version string may optionally start with ‘>=’ or ‘<=’ (== is implied otherwise), but other operators (e.g. ~=) are not supported. Note that ‘>’ and ‘<’ are interpreted to mean ‘>=’ and ‘<=’; ‘>’ and ‘<’ are not supported.

### Parameters
- **expected** (str) - Required - Expected version information.
- **die** (bool) - Optional - Whether or not to raise an exception if the check fails. Defaults to `False`.
- **warn** (bool) - Optional - Whether to raise a warning if the check fails. Defaults to `True`.

### Examples
```python
ss.check_version('>=3.0.0', die=True) # Will raise an exception if an older version is used
```
```

--------------------------------

### Module Initialization with Pars (Old vs New)

Source: https://docs.starsim.org/whatsnew.html

Illustrates the change in how modules are initialized with parameters, moving from `ss.Module(pars=dict(par=x))` to `ss.Module(par=x)`.

```python
ss.Module(pars=dict(par=x))
```

```python
ss.Module(par=x)
```

--------------------------------

### rvs

Source: https://docs.starsim.org/api/distributions.html

Gets random variates. This is the primary method for sampling from the distribution.

```APIDOC
## rvs

### Description
Get random variates – use this!

### Method
```python
distributions.Dist.rvs(size)
```

### Parameters
- `size` (int): The number of random variates to generate.
```

--------------------------------

### Notebook Configuration and Imports

Source: https://docs.starsim.org/user_guide/workflows_calibration.html

Essential imports and settings for running Starsim and Optuna calibration in a notebook environment. Includes loading extensions and setting default options.

```python
# Notebook configuration
%load_ext autoreload
%autoreload 2
%matplotlib inline

##%% Imports and settings
import sciris as sc
import starsim as ss
ss.options(jupyter=True)
import numpy as np
import pandas as pd

n_agents = 2e3
debug = False # If true, will run in serial

```

--------------------------------

### Get Distribution State

Source: https://docs.starsim.org/api/distributions.html

Return a copy of the current state of the distribution.

```python
distributions.Dist.get_state()
```

--------------------------------

### Module Initialization (Old vs New)

Source: https://docs.starsim.org/whatsnew.html

Demonstrates the change in module initialization from using `omergeleft` for parameters and distributions to using `default_pars` and `update_pars`.

```python
def __init__(self, pars=None, **kwargs):

    pars = ss.omergeleft(pars,
        dur_inf = 6,
        init_prev = 0.01,
        p_death = 0.01,
        beta = 0.5,
    )

    par_dists = ss.omergeleft(par_dists,
        dur_inf = ss.lognorm_ex,
        init_prev = ss.bernoulli,
        p_death = ss.bernoulli,
    )

    super().__init__(pars=pars, par_dists=par_dists, *args, **kwargs)
```

```python
def __init__(self, pars=None, **kwargs):
    super().__init__()
    self.default_pars(
        beta = 0.5,
        init_prev = ss.bernoulli(0.01),
        dur_inf = ss.lognorm_ex(6),
        p_death = ss.bernoulli(0.01),
    )
    self.update_pars(pars, **kwargs)
```

--------------------------------

### infect

Source: https://docs.starsim.org/api/diseases.html

Determine who gets infected on this timestep via transmission on the network.

```APIDOC
## diseases.Infection.infect()

### Description
Determine who gets infected on this timestep via transmission on the network.
```

--------------------------------

### Initialize Integration Plan

Source: https://docs.starsim.org/api/loop.html

Parse the simulation object to create the integration plan.

```python
loop.Loop.init()
```

--------------------------------

### Demonstrate Infection Log Analyzer

Source: https://docs.starsim.org/user_guide/modules_analyzers.html

Initializes a simulation with the infection log analyzer and runs the simulation. The analyzer is then accessed and plotted.

```python
# Demonstrate infection log
sim = ss.Sim(n_agents=1000, dt=0.2, dur=15, diseases='sir', networks='random', analyzers='infection_log')
sim.run()
infection_log = sim.analyzers[0]
infection_log.plot()
```

--------------------------------

### Get Unit Class

Source: https://docs.starsim.org/api/time.html

Converts a string or class into its corresponding TimePar class.

```python
time.get_unit_class(which, unit)
```

--------------------------------

### run_trial

Source: https://docs.starsim.org/api/calibration.html

Define the objective for Optuna.

```APIDOC
## run_trial

### Description
Define the objective for Optuna.

### Method
`calibration.Calibration.run_trial(trial)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **trial** (object) - Required - The Optuna trial object.
```

--------------------------------

### modules.Module.init_post

Source: https://docs.starsim.org/api/modules.html

Performs post-initialization steps for the module's states.

```APIDOC
## modules.Module.init_post

### Description
Initialize the values of the states; the last step of initialization
```

--------------------------------

### Plotting Calibration Study

Source: https://docs.starsim.org/user_guide/workflows_calibration.html

Plots a contour of the calibration study. Requires 'sklearn' to be installed.

```python
calib.plot_optuna('plot_param_importances');
```

--------------------------------

### Initialize Product Pre-computation

Source: https://docs.starsim.org/api/products.html

Initializes product pre-computation. Skips if the product has already been initialized.

```python
products.Product.init_pre(sim)
```

--------------------------------

### Get Rate Class

Source: https://docs.starsim.org/api/time.html

Helper function to obtain a Rate class based on a unit.

```python
time.get_rate_class(unit)
```

--------------------------------

### Get Duration Class

Source: https://docs.starsim.org/api/time.html

Helper function to obtain a Dur class based on a unit.

```python
time.get_dur_class(unit)
```

--------------------------------

### Instantiate SIR Module with Default Parameters

Source: https://docs.starsim.org/user_guide/basics_parameters.html

Demonstrates valid ways to instantiate a custom SIR module, showing how parameter values are checked against the defined format.

```python
sir1 = MySIR(p_death=0.02)
sir2 = MySIR(p_death=ss.bernoulli(p=0.2))
```

--------------------------------

### Convert Date to JSON

Source: https://docs.starsim.org/api/time.html

Use `time.date.to_json()` to get a JSON representation of the date object.

```python
time.date.to_json()
```

--------------------------------

### Initialize StaticNet with NetworkX Graph

Source: https://docs.starsim.org/api/networks.html

Creates a static network from a pre-existing networkx graph. Partnerships are static and only end when a partner dies.

```python
import networkx as nx
import starsim as ss
g = nx.scale_free_graph(n=10000)
ss.StaticNet(graph=g)
```

--------------------------------

### run

Source: https://docs.starsim.org/api/sim.html

Executes the simulation model. This is the main method for running a simulation from start to finish.

```APIDOC
## run

### Description
Run the model – the main method for running a simulation.

### Method Signature
`sim.Sim.run()`
```

--------------------------------

### Module Method: start_step

Source: https://docs.starsim.org/api/modules.html

Performs tasks at the beginning of a simulation step. This is part of the module's update cycle.

```python
modules.Module.start_step()
```

--------------------------------

### Define Shrunk Class

Source: https://docs.starsim.org/api/utils.html

Use Shrunk to indicate an object has been shrunken. No setup is required.

```python
utils.Shrunk(obj=None, attr=None)
```

--------------------------------

### Check Starsim Version with ss.check_version()

Source: https://docs.starsim.org/whatsnew.html

Use ss.check_version() to determine the currently installed version of Starsim.

```python
ss.check_version()
```

--------------------------------

### init_modules_pre

Source: https://docs.starsim.org/api/sim.html

Initializes all modules within the simulation.

```APIDOC
## init_modules_pre

### Description
Initialize all the modules with the sim

### Method Signature
`sim.Sim.init_modules_pre()`
```

--------------------------------

### Simulate Die Rolls

Source: https://docs.starsim.org/api/distributions.html

Example of simulating 10 die rolls using the choice function.

```python
# Simulate 10 die rolls
ss.choice(6, strict=False)(10) + 1
```

--------------------------------

### Simulate People Initialization and Progress

Source: https://docs.starsim.org/user_guide/basics_model.html

This output shows the initialization of 20 agents and the simulation progress over time. It details the data generated for each agent, including their status, age, and health metrics.

```text
Initializing sim with 20 agents

  Running 2000.01.01 ( 0/51) (0.00 s)  ———————————————————— 2%

  Running 2010.01.01 (10/51) (0.39 s)  ••••———————————————— 22%

  Running 2020.01.01 (20/51) (0.41 s)  ••••••••———————————— 41%

  Running 2030.01.01 (30/51) (0.43 s)  ••••••••••••———————— 61%

  Running 2040.01.01 (40/51) (0.45 s)  ••••••••••••••••———— 80%

  Running 2050.01.01 (50/51) (0.47 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  25.1524   False      NaN         NaN    1.0                  False             True         False       0.3449            1.0             33.0           42.7465        0.6551
1     1     1   True   4.9883    True      NaN         NaN    1.0                  False            False          True       0.0000            1.0             42.0           52.0214        1.0051
2     2     2   True  58.1494   False      NaN         NaN    1.0                  False             True         False       0.6627            1.0             23.0           31.5178        0.3373
3     3     3   True   0.1302   False      NaN         NaN    1.0                  False            False          True       0.0000            1.0             49.0           59.3261        1.5559
4     4     4   True  43.8199   False      NaN         NaN    1.0                  False             True         False       0.1787            1.0             38.0           48.7212        0.8213
5     5     5   True  42.6909   False      NaN         NaN    1.0                  False             True         False       0.3620            1.0             29.0           37.6566        0.6380
6     6     6   True  54.2923    True      NaN         NaN    1.0                  False             True         False       0.1526            1.0             38.0           47.5738        0.8474
7     7     7   True  52.6040   False      NaN         NaN    1.0                  False             True         False       0.1201            1.0             39.0           49.7212        0.8799
8     8     8   True   7.0769   False      NaN         NaN    1.0                  False             True         False       0.6627            1.0             22.0           31.8954        0.3373
9     9     9   True  27.2292   False      NaN         NaN    1.0                  False             True         False       0.6816            1.0             18.0           28.5382        0.3184
10   10    10   True   4.0500    True      NaN         NaN    1.0                  False             True         False       0.5393            1.0             29.0           38.6003        0.4607
11   11    11   True  42.6985   False      NaN         NaN    1.0                  False             True         False       0.7392            1.0             16.0           23.6503        0.2608
12   12    12   True  25.2828    True      NaN         NaN    1.0                  False             True         False       0.6321            1.0             24.0           33.8575        0.3679
13   13    13   True  27.6266    True      NaN         NaN    1.0                  False             True         False       0.6454            1.0             23.0           32.7132        0.3546
14   14    14   True  24.6072   False      NaN         NaN    1.0                  False             True         False       0.5097            1.0             30.0           40.1969        0.4903
15   15    15   True  48.8226   False      NaN         NaN    1.0                  False             True         False       0.3416            1.0             32.0           42.4071        0.6584
16   16    16   True  16.9486   False      NaN         NaN    1.0                  False             True         False       0.3998            1.0             31.0           40.2152        0.6002
17   17    17   True  19.6193    True      NaN         NaN    1.0                  False             True         False       0.5808            1.0             28.0           37.0291        0.4192
18   18    18   True  40.8453    True      NaN         NaN    1.0                  False             True         False       0.3479            1.0             29.0           39.7353        0.6521
19   19    19   True  25.0690   False      NaN         NaN    1.0                  False            False          True       0.7392            1.0             50.0           60.8258        1.2608
```

--------------------------------

### Get Keys of Dist Objects

Source: https://docs.starsim.org/api/distributions.html

Returns the keys of the Dist objects managed by the Dists collection.

```python
distributions.Dists.keys()
```

--------------------------------

### Get Specific Person - Person

Source: https://docs.starsim.org/api/people.html

Retrieves a specific agent (Person object) from the simulation by its index.

```python
print(sim.people.person(5)) # The 5th agent in the simulation
```

--------------------------------

### Initialize Samples Object

Source: https://docs.starsim.org/api/samples.html

Stores CSV outputs and summary dataframes. Use Samples.new() to create a new one or Samples(fname) to read an existing file.

```python
samples.Samples(fname, memory_buffer=True, preload=False)
```

--------------------------------

### Get Default Option Value

Source: https://docs.starsim.org/api/settings.html

Retrieve the original default value for a specific Starsim option.

```python
settings.Options.get_default(key)
```

--------------------------------

### Initialize Sim with Default Demographics and Run

Source: https://docs.starsim.org/tutorials/t3_demographics.html

Enable default birth and death rates by setting demographics=True. The simulation is then run and plotted.

```python
ss.Sim(demographics=True).run().plot();
```

--------------------------------

### Get Candidates for Treatment

Source: https://docs.starsim.org/api/interventions.html

Retrieves the indices of individuals who are candidates for treatment within the `treat_num` intervention.

```python
interventions.treat_num.get_candidates()
```

--------------------------------

### Clear Results Directory

Source: https://docs.starsim.org/user_guide/workflows_samples.html

Clears all existing files from the results directory before starting new simulations.

```python
# Clear the existing results
for file_path in resultsdir.glob('*'):
    file_path.unlink()
```

--------------------------------

### Initialize network with simulation data

Source: https://docs.starsim.org/api/networks.html

Initialize the network with simulation data, including edges, and validate the p1 and p2 parameters.

```python
networks.Network.init_pre(sim)
```

--------------------------------

### Visualize Step Order with Different Module Timesteps

Source: https://docs.starsim.org/user_guide/advanced_profiling.html

Demonstrates visualizing the simulation loop's step order when modules have different timesteps. This helps in understanding how and when different parts of the simulation execute.

```python
sis = ss.SIS(dt=0.1)
net = ss.RandomNet(dt=0.5)
births = ss.Births(dt=1)
sim = ss.Sim(dt=0.1, dur=5, diseases=sis, networks=net, demographics=births)
sim.init()
sim.loop.plot_step_order()
```

--------------------------------

### Create and Save New Samples Object

Source: https://docs.starsim.org/api/samples.html

Creates a new Samples object and saves it as a zip file. Requires a folder path and a list of (dataframe, summary_row) tuples. Optionally specify identifiers and filename.

```python
samples.Samples.new(folder, outputs, identifiers=None, fname=None, verbose=True)
```

--------------------------------

### Get Available Agents in SexualNetwork

Source: https://docs.starsim.org/api/networks.html

Returns UIDs of active agents of the given sex who are not currently partnered.

```python
networks.SexualNetwork.available(people, sex)
```

--------------------------------

### Initialize Options Object

Source: https://docs.starsim.org/api/settings.html

Instantiate the Options object to manage Starsim settings.

```python
settings.Options()
```

--------------------------------

### Get Birth Rates

Source: https://docs.starsim.org/api/demographics.html

Extract the right birth rates to use and translate it into a number of people to add.

```python
demographics.Births.get_births()
```

--------------------------------

### sim.Sim.init

Source: https://docs.starsim.org/api/sim.html

Perform all initializations for the sim. This method can optionally force overwrites and time the initialization process.

```APIDOC
## init

### Description
Perform all initializations for the sim. This method can optionally force overwrites and time the initialization process.

### Method Signature
sim.Sim.init(force=False, timer=False, **kwargs)

### Parameters
#### Parameters
- **force** (bool) - whether to overwrite sim attributes even if they already exist | `False`
- **timer** (bool) - if True, count the time required for initialization (otherwise just count run time) | `False`
- **kwargs** (dict) - passed to ss.People() | `{}`
```

--------------------------------

### Disease step_state Method

Source: https://docs.starsim.org/api/diseases.html

Performs updates at the start of the timestep, prior to transmission. These are typically state changes.

```python
diseases.Disease.step_state()
```

--------------------------------

### Timing iteration after preload

Source: https://docs.starsim.org/user_guide/workflows_samples.html

After preloading, iterating through dataframes is fast as all data is already in the cache. This example demonstrates the timing.

```python
with sc.Timer():
    for df in res:
        continue
```

```text
Elapsed time: 6.46 ms
```

--------------------------------

### Instantiate Calibration

Source: https://docs.starsim.org/api/calibration.html

Handles the calibration of Starsim simulations using the Optuna hyperparameter optimization library. Requires simulation data and calibration parameters.

```python
calibration.Calibration(
    sim,
    calib_pars,
    n_workers=None,
    total_trials=None,
    reseed=True,
    build_fn=None,
    build_kw=None,
    eval_fn=None,
    eval_kw=None,
    components=None,
    prune_fn=None,
    label=None,
    study_name=None,
    db_name=None,
    keep_db=None,
    continue_db=None,
    storage=None,
    sampler=None,
    die=False,
    debug=False,
    verbose=True,
)
```

--------------------------------

### Choose Between Specified Options with Probabilities

Source: https://docs.starsim.org/api/distributions.html

Example of choosing between specified options with custom probabilities using the choice function.

```python
# Choose between specified options each with a specified probability (must sum to 1)
ss.choice(a=[30, 70], p=[0.3, 0.7], strict=False)(10)
```
Tokens:
Raw