STIsim

https://github.com/starsimhub/stisim
Admin
STIsim is an agent-based modeling framework for designing and configuring simulations of...
Tokens:21,288
Snippets:173
Trust Score:8.9
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Customize simulation configuration

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_intro.ipynb

Provides examples of configuring simulations via inline keyword arguments, overriding disease-specific parameters, and manually instantiating modules for full control.

```python
# Inline parameters
sim = sti.Sim(
    diseases='ng',
    n_agents=2000,
    start=2010,
    stop=2025,
)
sim.run(verbose=0)

# Disease-specific parameters
sim = sti.Sim(
    diseases=['ng', 'ct'],
    sti_pars=dict(
        ng=dict(init_prev=0.05),
        ct=dict(init_prev=0.08),
    ),
)
sim.run(verbose=0)

# Full module control
import starsim as ss

ng = sti.Gonorrhea(beta_m2f=0.08, init_prev=0.03)
nw = sti.StructuredSexual()
pregnancy = sti.Pregnancy(fertility_rate=20)
deaths = ss.Deaths(death_rate=10)

sim = sti.Sim(
    diseases=ng,
    networks=nw,
    demographics=[pregnancy, deaths],
    n_agents=2000,
    start=2010,
    stop=2030,
)
sim.run(verbose=0)
sim.plot(key=['ng.new_infections', 'ng.prevalence'])
```

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

### Run a basic STIsim simulation

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_intro.ipynb

Demonstrates the simplest way to initialize, run, and visualize a simulation for a specific disease (gonorrhea) using default settings.

```python
import stisim as sti

sim = sti.Sim(diseases='ng')
sim.run(verbose=0)
sim.plot(key=['ng.new_infections', 'ng.prevalence'])
```

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

### Inspect simulation parameters and components

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_intro.ipynb

Shows how to access and print simulation metadata, network configurations, and disease-specific parameters after initialization.

```python
sim = sti.Sim(diseases='ng')
sim.init()

print(f'Start:    {sim.pars.start}')
print(f'Stop:     {sim.pars.stop}')
print(f'Timestep: {sim.pars.dt} years ({sim.pars.dt*12:.0f} month)')
print(f'Agents:   {sim.pars.n_agents}')

for name, nw in sim.networks.items():
    print(f'{name}: {type(nw).__name__}')

ng = sim.diseases.ng
print(f'Disease: {type(ng).__name__}')
print(f'Transmission (M to F): {ng.pars.beta_m2f}')
print(f'Initial prevalence: {ng.pars.init_prev}')
print(f'Condom efficacy: {ng.pars.eff_condom}')

print(f'Demographics: {dict(sim.demographics)}')
```

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

### Install STIsim using uv

Source: https://github.com/starsimhub/stisim/blob/main/README.md

Installs STIsim using uv, a fast Python package installer and resolver. This method involves initializing a project with uv and then adding stisim as a dependency.

```shell
uv init example
cd example
uv add stisim
```

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

### HIVsim Quick Start: Zimbabwe Demo

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates a quick simulation using the hivsim package with pre-defined settings for Zimbabwe. This provides a streamlined way to run an HIV-focused simulation with sensible defaults.

```python
import hivsim

# Quick demo with Zimbabwe data
sim = hivsim.demo('zimbabwe')

# Or create custom simulation
sim = hivsim.Sim(
    n_agents=10000,
    start=1980,
    stop=2030,
    init_prev=0.01,
    beta_m2f=0.05,
)
sim.run()
sim.plot('hiv')
```

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

### Install and Test STIsim

Source: https://github.com/starsimhub/stisim/blob/main/CLAUDE.md

Commands to install STIsim in development mode and run tests using pytest. Includes options for running all tests, specific tests, pattern matching, and coverage analysis.

```bash
pip install -e .
cd tests && pytest test_*.py -n auto
pytest tests/test_sim.py::test_hiv_sim -v
pytest tests/test_*.py -k "hiv" -v
pytest tests/test_*.py --cov=stisim
```

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

### Install STIsim using pip

Source: https://github.com/starsimhub/stisim/blob/main/README.md

Installs the STIsim package using pip, the standard Python package installer. This is the most straightforward method for users who have Python and pip set up.

```shell
pip install stisim
```

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

### Install STIsim locally with development dependencies

Source: https://github.com/starsimhub/stisim/blob/main/README.md

Installs STIsim from a local clone of the repository, including optional dependencies for development, testing, and documentation. This is useful for developers contributing to the project.

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

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

### HIVsim Zimbabwe Example with Custom Agents and Run/Plot

Source: https://context7.com/starsimhub/stisim/llms.txt

Runs the Zimbabwe demo using hivsim with custom agent numbers and automatically executes the simulation and plotting. It also shows how to access detailed simulation results like peak prevalence and ART coverage.

```python
import hivsim

# Run Zimbabwe demo with custom agents
sim = hivsim.demo(
    'zimbabwe',
    n_agents=20000,
    run=True,
    plot=True,
)

# Access detailed results
print(f"Peak HIV prevalence: {max(sim.results.hiv.prevalence):.1%}")
print(f"Final ART coverage: {sim.results.hiv.p_on_art[-1]:.1%}")
```

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

### Create and Run a STIsim Simulation

Source: https://github.com/starsimhub/stisim/blob/main/CLAUDE.md

Example of how to create a STIsim simulation instance with specified diseases, network type, number of agents, and duration, followed by running the simulation.

```python
sim = sti.Sim(
    diseases=['hiv', 'syphilis'],  # or disease instances
    networks=sti.StructuredSexual(),
    n_agents=1000,
    dur=40
)
sim.run()
```

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

### Configure STI Testing and Treatment in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Sets up interventions for STI testing and treatment, including diagnostic tests with specified sensitivity and specificity, and treatment efficacy. This example uses Gonorrhea ('ng') as the disease.

```python
import stisim as sti
import starsim as ss
import pandas as pd

# Create diagnostic product
dx_data = pd.DataFrame({
    'state': ['susceptible', 'exposed', 'infected'],
    'p_positive': [0.02, 0.95, 0.98]  # Specificity, sensitivity
})
ng_dx = sti.STIDx(df=dx_data, disease='ng', name='ng_test')

# Create testing intervention (symptomatic women)
ng_test = sti.STITest(
    product=ng_dx,
    eligibility=lambda sim: sim.diseases.ng.seeking_care,
    name='ng_testing',
)

# Create treatment intervention
ng_tx = sti.STITreatment(
    diseases='ng',
    eligibility=lambda sim: sim.interventions.ng_testing.last_outcomes['positive'],
    pars=dict(treat_eff=ss.bernoulli(p=0.95)),  # 95% cure rate
    name='ng_treatment',
)

sim = sti.Sim(
    diseases=['ng'],
    interventions=[ng_test, ng_tx],
    n_agents=5000,
)
sim.run()
```

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

### Install rstarsim R package

Source: https://github.com/starsimhub/stisim/blob/main/README.md

Installs the rstarsim R package, which allows users to interact with STIsim from the R environment. It requires the reticulate and devtools packages and installs the package from GitHub.

```r
install.packages(c("reticulate", "devtools"))
devtools::install_github("starsimhub/rstarsim")
```

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

### Load existing conda environment for rstarsim

Source: https://github.com/starsimhub/stisim/blob/main/README.md

Loads a pre-existing conda environment for use with the rstarsim package. This is an alternative to the automatic environment setup performed by rstarsim on first use.

```r
library(starsim)
load_starsim("my_env_name")
```

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

### Define a Generic Testing Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

The STITest class is the base for testing interventions. It controls who gets tested, how often, and with which diagnostic product. Key parameters include the diagnostic product, testing probability, eligibility criteria, and active period.

```python
test = sti.STITest(
    product=my_diagnostic,      # Diagnostic product (required)
    test_prob_data=0.1,         # Per-timestep probability of testing
    eligibility=lambda sim: sim.people.female,  # Who is eligible
    start=2015,                 # When testing begins
)
```

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

### Add HIV with Coinfection Connectors (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_cotransmission.ipynb

Models HIV coinfection with other STIs (Gonorrhea, Chlamydia, Trichomoniasis) using STIsim connectors. Connectors like `hiv_ng` modify relative susceptibility and transmissibility between diseases. This example sets up HIV and bacterial STIs, defines connectors, runs the simulation, and plots prevalences.

```python
# Create disease modules
hiv = sti.HIV(init_prev=0.10)
ng = sti.Gonorrhea(init_prev=0.03)
ct = sti.Chlamydia(init_prev=0.05)
tv = sti.Trichomoniasis(init_prev=0.08)

# Create connectors for HIV-STI interactions
connectors = [
    sti.hiv_ng(hiv, ng),   # NG increases HIV susceptibility (default: 1.2x)
    sti.hiv_ct(hiv, ct),   # CT increases HIV susceptibility (default: 1.0x)
    sti.hiv_tv(hiv, tv),   # TV increases HIV susceptibility (default: 1.5x)
]

sim = sti.Sim(
    diseases=[hiv, ng, ct, tv],
    connectors=connectors,
    n_agents=2000,
    start=2010,
    stop=2030,
)
sim.run(verbose=0)
sim.plot(key=['hiv.prevalence', 'ng.prevalence', 'ct.prevalence', 'tv.prevalence'])
```

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

### Run STIsim Simulation

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Initializes and executes a gonorrhea simulation using the STIsim library.

```python
import stisim as sti
import matplotlib.pyplot as plt

sim = sti.Sim(diseases='ng', n_agents=2000, start=2010, stop=2030)
sim.run(verbose=0)
```

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

### Initialize and Run Basic STI Simulation

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates the creation of a multi-disease simulation using the sti.Sim class. It shows how to define diseases, network structures, population size, and timeframes, followed by execution and result visualization.

```python
import stisim as sti

# Create a basic HIV and syphilis co-circulation simulation
sim = sti.Sim(
    diseases=['hiv', 'syphilis'],
    networks=sti.StructuredSexual(),
    n_agents=10000,
    start=2000,
    stop=2030,
)

# Run the simulation
sim.run()

# Plot results
sim.plot()

# Access specific results
print(f"Final HIV prevalence: {sim.results.hiv.prevalence[-1]:.2%}")
print(f"Final syphilis prevalence: {sim.results.syphilis.prevalence[-1]:.2%}")
```

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

### Perform Basic Calibration in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates basic calibration of Stisim model parameters to match observed data. It uses Optuna for optimization and defines calibration targets and parameters with their bounds.

```python
import stisim as sti
import pandas as pd

# Define calibration targets
data = pd.DataFrame({
    'time': [2000, 2005, 2010, 2015, 2020],
    'hiv.prevalence': [0.15, 0.18, 0.16, 0.14, 0.12],
    'hiv.n_on_art': [0, 1000, 50000, 150000, 250000],
})

# Define parameters to calibrate with bounds
calib_pars = dict(
    hiv_beta_m2f=dict(low=0.01, high=0.10, guess=0.05),
    hiv_init_prev=dict(low=0.01, high=0.20, guess=0.10),
    nw_prop_f0=dict(low=0.70, high=0.95, guess=0.85),
)

# Create base simulation
def make_sim():
    return sti.Sim(
        diseases=['hiv'],
        n_agents=5000,
        start=1990,
        stop=2025,
    )

# Run calibration
calib = sti.Calibration(
    sim=make_sim(),
    calib_pars=calib_pars,
    data=data,
    total_trials=100,
    n_workers=4,
)
calib.calibrate()

# View best parameters
print(calib.df.head())
best_pars = calib.df.iloc[0]
print(f"Best beta_m2f: {best_pars['hiv_beta_m2f']:.4f}")
```

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

### Initialize Disease Modules

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates how to instantiate and configure disease modules such as Gonorrhea, Chlamydia, and Syphilis with custom transmission and progression parameters.

```python
import stisim as sti
import starsim as ss

# Create gonorrhea with custom parameters
ng = sti.Gonorrhea(
    pars=dict(
        beta_m2f=0.06,
        dur_exp=ss.weeks(1),
        p_symp=[0.50, 0.90],
        dur_asymp2clear=[[ss.weeks(52), ss.weeks(5)], [ss.weeks(52), ss.weeks(5)]],
        p_symp_care=[0.3, 0.5]
    )
)

# Create chlamydia
ct = sti.Chlamydia(pars=dict(beta_m2f=0.06, p_symp=[0.20, 0.50]))

# Create syphilis
syph = sti.Syphilis(pars=dict(beta_m2f=0.1, init_prev=0.02))

sim = sti.Sim(diseases=[ng, ct, syph], n_agents=5000)
sim.run()
```

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

### Implement PrEP Intervention in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Details the implementation of a Pre-Exposure Prophylaxis (PrEP) intervention, specifying coverage levels over time and the efficacy of PrEP in preventing HIV.

```python
import stisim as sti

# PrEP intervention for FSW
prep = sti.Prep(
    pars=dict(
        coverage=[0, 0.01, 0.30, 0.50],  # Coverage over time
        years=[2010, 2015, 2020, 2025],
        eff_prep=0.80,                    # 80% efficacy
    )
)

sim = sti.Sim(
    diseases=['hiv'],
    interventions=[sti.HIVTest(), sti.ART(), prep],
    n_agents=5000,
)
sim.run()
```

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

### Implement Interventions

Source: https://context7.com/starsimhub/stisim/llms.txt

Sets up public health interventions including HIV testing protocols and ART treatment coverage schedules.

```python
import stisim as sti
import numpy as np
import pandas as pd

# HIV testing intervention
hiv_test = sti.HIVTest(
    name='hiv_testing',
    test_prob_data=np.array([0.01, 0.05, 0.10, 0.15]),
    years=[2000, 2010, 2015, 2020],
    eligibility=lambda sim: ~sim.diseases.hiv.diagnosed
)

# ART treatment coverage
art_data = pd.DataFrame({'p_art': [0.0, 0.10, 0.50, 0.80]}, index=[2000, 2010, 2015, 2020])

sim = sti.Sim(diseases=['hiv'], interventions=[hiv_test], n_agents=5000)
sim.run()
```

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

### Create ART Intervention in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates how to create and apply an Antiretroviral Therapy (ART) intervention in Stisim. It sets initiation probability and future coverage targets.

```python
import stisim as sti

art = sti.ART(
    coverage_data=art_data,
    pars=dict(
        init_prob=0.9,                               # 90% initiation rate
        future_coverage={'year': 2025, 'prop': 0.90} # 90% target by 2025
    )
)

sim = sti.Sim(
    diseases=['hiv'],
    interventions=[sti.HIVTest(), art],
    n_agents=5000,
)
sim.run()

print(f"Proportion on ART: {sim.results.hiv.p_on_art[-1]:.1%}")
```

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

### Configure Simulation with Location-Based Demographics

Source: https://context7.com/starsimhub/stisim/llms.txt

Illustrates the use of the demographics parameter to automatically download and apply country-specific demographic data, such as age distributions, fertility, and mortality rates.

```python
import stisim as sti

# Create simulation with Zimbabwe demographics
sim = sti.Sim(
    diseases=['hiv'],
    demographics='Zimbabwe',  # Auto-downloads age, death, fertility data
    n_agents=10000,
    total_pop=15_000_000,    # Total population for scaling
    start=1980,
    stop=2030,
)

sim.run()
print(f"Population at end: {sim.results.n_alive[-1]:,}")
```

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

### Access and Inspect Simulation Results

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Demonstrates how to retrieve specific disease metrics from the simulation results object and inspect the underlying NumPy arrays and time vectors.

```python
# Access individual results
prev = sim.results.ng.prevalence
print(f'{prev.label}: min={prev.values.min():.3f}, mean={prev.values.mean():.3f}, max={prev.values.max():.3f}')

new_inf = sim.results.ng.new_infections
print(f'{new_inf.label}: min={new_inf.values.min():.0f}, mean={new_inf.values.mean():.1f}, max={new_inf.values.max():.0f}')

# Inspect raw data
print(f'Values (first 5): {prev.values[:5]}')
print(f'Timevec: {prev.timevec[0]} to {prev.timevec[-1]} ({len(prev.values)} timesteps)')
```

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

### Configure Simulation with Custom Disease and Network Parameters

Source: https://context7.com/starsimhub/stisim/llms.txt

Shows how to pass custom transmission probabilities and network risk group proportions into the simulation constructor. This allows for fine-grained control over disease dynamics and population behavior.

```python
import stisim as sti

# Create simulation with custom disease parameters
sim = sti.Sim(
    diseases=['hiv', 'ng', 'ct'],  # HIV, gonorrhea, chlamydia
    n_agents=5000,
    start=1990,
    stop=2025,
    # HIV parameters
    beta_m2f=0.05,           # Male-to-female transmission probability
    rel_beta_f2m=0.5,        # Female-to-male relative transmission
    eff_condom=0.9,          # Condom efficacy
    init_prev=0.03,          # Initial HIV prevalence
    # Network parameters
    prop_f0=0.85,            # Proportion of females in low-risk group
    prop_m0=0.80,            # Proportion of males in low-risk group
)

sim.run()
sim.plot('hiv')
```

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

### Configure VMMC Intervention in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Shows how to set up a Voluntary Medical Male Circumcision (VMMC) intervention, including coverage data and efficacy parameters. This intervention aims to reduce HIV acquisition.

```python
import stisim as sti
import pandas as pd

# VMMC coverage data
vmmc_data = pd.DataFrame({
    'p_vmmc': [0.0, 0.05, 0.30, 0.50]
}, index=[2000, 2010, 2015, 2020])

vmmc = sti.VMMC(
    coverage_data=vmmc_data,
    pars=dict(
        eff_circ=0.6,  # 60% reduction in HIV acquisition
        future_coverage={'year': 2025, 'prop': 0.60}
    )
)

sim = sti.Sim(
    diseases=['hiv'],
    interventions=[sti.HIVTest(), sti.ART(), vmmc],
    n_agents=5000,
)
sim.run()
```

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

### Resample Results to Annual Frequency

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Aggregates monthly simulation data into annual summaries, automatically applying sum or mean operations based on the result type.

```python
# Resample single result
annual = sim.results.ng.new_infections.resample('year')

# Resample to DataFrame
annual_df = sim.results.ng.new_infections.resample('year', output_form='dataframe')

# Resample entire simulation
annual_all = sim.to_df(resample='year', use_years=True)
```

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

### STIsim Import Conventions

Source: https://github.com/starsimhub/stisim/blob/main/CLAUDE.md

Demonstrates the recommended import conventions for STIsim and related libraries. It highlights the use of aliases to avoid naming conflicts with disease instances.

```python
import numpy as np
import sciris as sc
import starsim as ss
import stisim as sti
import hivsim
```

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

### Export Results to DataFrame

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Converts simulation results or individual result objects into Pandas DataFrames for further analysis.

```python
# Export all
df = sim.to_df()

# Export single result
prev_df = sim.results.ng.prevalence.to_df()
```

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

### Visualize Simulation Results

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Uses the built-in plotting functionality to visualize high-level, specific, or stratified simulation metrics.

```python
# Default plot
sim.plot()

# Plot specific results
sim.plot(key=['ng.prevalence', 'ng.new_infections'])

# Plot sex-stratified results
sim.plot(key=['ng.prevalence_f', 'ng.prevalence_m'])
```

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

### Define PrEP Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

The PrEP (Pre-exposure Prophylaxis) intervention targets specific populations, such as FSWs, to reduce susceptibility. It defaults to an 80% reduction in susceptibility. Coverage and years of implementation can be specified.

```python
prep = sti.Prep(coverage=[0, 0.5], years=[2020, 2025])
```

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

### Create Custom Plots with Matplotlib

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_results.ipynb

Generates publication-quality figures by directly accessing result values and resampling data for custom visualization layouts.

```python
fig, axes = plt.subplots(1, 2, figsize=(10, 4))

# Left: prevalence by sex
axes[0].plot(sim.timevec, sim.results.ng.prevalence_f, label='Female')
axes[0].plot(sim.timevec, sim.results.ng.prevalence_m, label='Male')
axes[0].legend()

# Right: annual new infections
annual_inf = sim.results.ng.new_infections.resample('year', output_form='dataframe', use_years=True)
axes[1].bar(annual_inf.index, annual_inf['value'])

plt.tight_layout()
```

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

### Configure Sexual Networks

Source: https://context7.com/starsimhub/stisim/llms.txt

Configures various network topologies including structured sexual behavior, MSM dynamics, and prior partner tracking for contact tracing.

```python
import stisim as sti
import starsim as ss

# Structured sexual network
network = sti.StructuredSexual(pars=dict(prop_f0=0.85, f0_conc=0.0001, acts=ss.lognorm_ex(ss.freqperyear(80), ss.freqperyear(30))))

# MSM network
msm_network = sti.AgeMatchedMSM(pars=dict(msm_share=ss.bernoulli(p=0.015)))

# Prior partners network
prior_net = sti.PriorPartners(pars=dict(dur_recall=ss.years(1)))

sim = sti.Sim(diseases=['hiv'], networks=[network, msm_network, prior_net], n_agents=5000)
sim.run()
```

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

### Implement HIV Testing and ART

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_interventions.ipynb

This code snippet sets up an HIV simulation with testing and Antiretroviral Therapy (ART) interventions. It includes HIV-specific classes like `HIVTest` and `ART`, and requires demographic data such as pregnancy and deaths for ART's infant protection logic. It compares simulation results with and without these interventions.

```python
# Create HIV testing: 10% annual probability, starting in 2000
hiv_test = sti.HIVTest(test_prob_data=0.1, start=2000, name='hiv_test')

# Create ART: coverage ramps from 0% to 90% over time
art_data = pd.DataFrame(
    index=np.arange(2000, 2031),
    data={'p_art': np.clip(np.linspace(0, 0.9, 31), 0, 1)}
)
art = sti.ART(coverage_data=art_data)

# Demographics needed for ART (pregnancy protection)
demographics = [sti.Pregnancy(fertility_rate=20), ss.Deaths(death_rate=10)]

# Run with and without interventions
sim_base = sti.Sim(diseases='hiv', demographics=[sti.Pregnancy(fertility_rate=20), ss.Deaths(death_rate=10)],
                   n_agents=3000, start=2000, stop=2030)
sim_intv = sti.Sim(diseases='hiv', demographics=demographics, interventions=[hiv_test, art],
                   n_agents=3000, start=2000, stop=2030)

sim_base.run(verbose=0)
sim_intv.run(verbose=0)

fig, axes = plt.subplots(1, 2, figsize=(10, 4))

axes[0].plot(sim_base.timevec, sim_base.results.hiv.new_infections, label='No ART', alpha=0.7)
axes[0].plot(sim_intv.timevec, sim_intv.results.hiv.new_infections, label='Testing + ART', alpha=0.7)
axes[0].set_xlabel('Year')
axes[0].set_ylabel('New HIV infections')
axes[0].legend()

axes[1].plot(sim_intv.timevec, sim_intv.results.hiv.p_on_art)
axes[1].set_xlabel('Year')
axes[1].set_ylabel('Proportion on ART')
axes[1].set_title('ART coverage')

plt.tight_layout()
fig
```

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

### Initialize STIsim with Diseases (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/diseases/index.md

Demonstrates how to initialize an STIsim simulation with different disease modules. Diseases can be specified by their string alias for default parameters or by creating module instances for custom configurations. The `sti_pars` argument allows for parameter customization when using string aliases.

```python
import stisim as sti

# By name with defaults
sim = sti.Sim(diseases='hiv')

# By name with custom parameters
sim = sti.Sim(diseases=['hiv', 'ng'], sti_pars=dict(hiv=dict(init_prev=0.1)))

# As module instances
sim = sti.Sim(diseases=[sti.HIV(init_prev=0.1), sti.Gonorrhea()])
```

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

### Implement Partner Notification in Stisim

Source: https://context7.com/starsimhub/stisim/llms.txt

Configures a Partner Notification intervention to trace and test partners of diagnosed individuals. It uses an existing HIV test intervention and specifies the probability of partners accepting testing.

```python
import stisim as sti

# Create testing intervention
hiv_test = sti.HIVTest(name='hiv_test')

# Create partner notification
pn = sti.PartnerNotification(
    eligibility=lambda sim: (sim.diseases.hiv.ti_diagnosed == sim.ti).uids,
    test=hiv_test,
    test_prob=0.5,  # 50% of partners accept testing
)

sexual_net = sti.StructuredSexual(pars=dict(recall_prior=True))
prior_net = sti.PriorPartners()

sim = sti.Sim(
    diseases=['hiv'],
    networks=[sexual_net, prior_net],
    interventions=[hiv_test, sti.ART(), pn],
    n_agents=5000,
)
sim.run()
```

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

### Network Analysis Analyzers for STIsim

Source: https://context7.com/starsimhub/stisim/llms.txt

Provides tools to analyze various aspects of sexual networks in STIsim, including relationship durations, partner counts, age differences, and sexual debut age. These analyzers help in understanding the structural properties of the simulated networks.

```python
import stisim as sti

# Network degree analyzer
degree_analyzer = sti.NetworkDegree(
    year=2020,
    relationship_types=['stable', 'casual'],
)

# Partner age difference analyzer
age_diff_analyzer = sti.partner_age_diff(year=2020)

# Sexual debut age analyzer
debut_analyzer = sti.DebutAge()

sim = sti.Sim(
    diseases=['hiv'],
    analyzers=[degree_analyzer, age_diff_analyzer, debut_analyzer],
    n_agents=5000,
)
sim.run()

# Plot network statistics
degree_analyzer.plot()
age_diff_analyzer.plot()
```

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

### Trichomoniasis Natural History Parameters

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/diseases/trichomoniasis.md

Details the parameters controlling the natural progression of Trichomoniasis infection, including incubation periods, probabilities of developing symptoms, durations of asymptomatic and symptomatic states, and the probability and duration of spontaneous clearance.

```python
Parameters:
  Natural history:
    dur_exp: 0
    p_symp: [0.40, 0.50]
    dur_presymp: F: [1 wk, 12 wk]; M: [0.25 wk, 1 wk]
    dur_asymp2clear: F: [48 mo, 6 mo]; M: [26 wk, 4 wk]
    dur_symp2clear: F: [20 wk, 4 wk]; M: [18 wk, 4 wk]
    p_clear: 0.10
    dur_persist: 100 yr
```

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

### Combining Interventions

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

Demonstrates how to combine multiple interventions into a single simulation.

```APIDOC
## Combining Interventions

### Description
Demonstrates how to combine multiple interventions into a single simulation by passing them as a list to the `Sim` constructor.

### Method
POST (Conceptual - simulation setup)

### Endpoint
N/A (Simulation setup)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **interventions** (list) - Required - A list containing instantiated intervention objects.

### Request Example
```python
import stisim as sti

# Assume 'test' and 'treatment' are pre-defined intervention objects
# e.g., test = sti.STITest(...) 
# e.g., treatment = sti.STITreatment(...)

sim = sti.Sim(
    diseases='ng', # Example disease
    interventions=[test, treatment]
)

sim.run()
```

### Response
#### Success Response (200)
Simulation runs successfully.

#### Response Example
N/A
```

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

### Implement Gonorrhea Treatment

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_interventions.ipynb

This code snippet demonstrates how to add a simple gonorrhea treatment intervention to an STIsim simulation. It compares a baseline simulation without treatment to one where symptomatic individuals seeking care are treated. Requires the stisim, starsim, pandas, numpy, and matplotlib libraries.

```python
import stisim as sti
import starsim as ss
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

# Baseline: no treatment
sim_base = sti.Sim(diseases='ng', n_agents=2000, start=2010, stop=2030)
sim_base.run(verbose=0)

# With treatment: symptomatic care-seekers get treated
ng = sti.Gonorrhea(init_prev=0.01)
ng_tx = sti.GonorrheaTreatment(
    name='ng_tx',
    eligibility=lambda sim: sim.diseases.ng.symptomatic & (sim.diseases.ng.ti_seeks_care == sim.ti),
)
sim_intv = sti.Sim(diseases=ng, interventions=[ng_tx], n_agents=2000, start=2010, stop=2030)
sim_intv.run(verbose=0)

fig, ax = plt.subplots()
ax.plot(sim_base.timevec, sim_base.results.ng.prevalence, label='No treatment')
ax.plot(sim_intv.timevec, sim_intv.results.ng.prevalence, label='Treatment for care-seekers')
ax.set_xlabel('Year')
ax.set_ylabel('NG prevalence')
ax.set_title('Effect of treatment on gonorrhea')
ax.legend()
fig
```

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

### Define Custom HIV Disease Module

Source: https://context7.com/starsimhub/stisim/llms.txt

Demonstrates the instantiation of a specific HIV disease module with custom natural history parameters, including duration of infection stages and ART efficacy. This allows for advanced modeling of treatment impacts.

```python
import stisim as sti
import starsim as ss

# Create HIV disease with custom parameters
hiv = sti.HIV(
    pars=dict(
        beta_m2f=0.05,                    # Per-act transmission probability
        rel_beta_f2m=0.5,                 # Relative F2M transmission
        beta_m2c=ss.permonth(0.025),      # Mother-to-child transmission
        init_prev=ss.bernoulli(p=0.05),   # 5% initial prevalence
        dur_acute=ss.lognorm_ex(ss.months(3), ss.months(1)),
        dur_latent=ss.lognorm_ex(ss.years(10), ss.years(3)),
        rel_trans_acute=ss.normal(loc=6, scale=0.5),  # 6x transmission in acute
        art_efficacy=0.96,                # ART reduces transmission by 96%
    )
)

sim = sti.Sim(diseases=[hiv], n_agents=5000)
sim.run()

# Access HIV-specific results
print(f"Cumulative HIV deaths: {sim.results.hiv.cum_deaths[-1]}")
print(f"People on ART: {sim.results.hiv.n_on_art[-1]}")
```

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

### Target HIV Interventions by Population

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_interventions.ipynb

This code snippet demonstrates how to target interventions to specific sub-populations using the `eligibility` parameter. It implements different HIV testing probabilities for Female Sex Workers (FSWs) and the general population, alongside ART, within a single simulation.

```python
# Higher testing rate for FSWs
fsw_test = sti.HIVTest(
    test_prob_data=0.3,
    start=2000,
    name='fsw_test',
    eligibility=lambda sim: sim.networks.structuredsexual.fsw,
)

# Lower testing rate for the general population
gp_test = sti.HIVTest(
    test_prob_data=0.05,
    start=2000,
    name='gp_test',
    eligibility=lambda sim: ~sim.networks.structuredsexual.fsw,
)

art2 = sti.ART(coverage_data=art_data)

sim = sti.Sim(
    diseases='hiv',
    demographics=[sti.Pregnancy(fertility_rate=20), ss.Deaths(death_rate=10)],
    interventions=[fsw_test, gp_test, art2],
    n_agents=3000,
    start=2000,
    stop=2030,
)
sim.run(verbose=0)
sim.plot(key=['hiv.prevalence', 'hiv.new_infections', 'hiv.p_on_art'])
```

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

### Custom Build Function for STIsim Calibration

Source: https://context7.com/starsimhub/stisim/llms.txt

Defines a custom function to apply calibration parameters to a STIsim simulation, handling specific parameter routing for diseases like HIV and network parameters. It initializes the simulation if not already done and updates parameters based on the provided calibration dictionary.

```python
import stisim as sti

def custom_build_fn(sim, calib_pars, **kwargs):
    """Custom function to apply calibration parameters to simulation."""
    if not sim.initialized:
        sim.init()

    for key, pars in calib_pars.items():
        value = pars.get('value', pars) if isinstance(pars, dict) else pars

        if key.startswith('hiv_'):
            par_name = key[4:]
            sim.diseases.hiv.pars[par_name] = value
        elif key.startswith('nw_'):
            par_name = key[3:]
            sim.networks.structuredsexual.pars[par_name] = value

    return sim

calib = sti.Calibration(
    sim=make_sim(),
    calib_pars=calib_pars,
    data=data,
    build_fn=custom_build_fn,
    total_trials=50,
)
calib.calibrate()
```

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

### Trichomoniasis Transmission Parameters

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/diseases/trichomoniasis.md

Outlines the parameters governing the transmission dynamics of Trichomoniasis. This includes probabilities of transmission between different sexes, mother-to-child, male-to-male, and the efficacy of condoms.

```python
Parameters:
  Transmission:
    beta_m2f: 0.1
    rel_beta_f2m: 0.5
    beta_m2c: None
    beta_m2m: None
    eff_condom: 0.0
    init_prev: 0.01
```

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

### Sex Worker Statistics Analyzer for STIsim

Source: https://context7.com/starsimhub/stisim/llms.txt

Analyzes infections and transmissions specifically among female sex workers (FSW) and their clients within STIsim. This analyzer helps in understanding disease dynamics within this key population and their networks.

```python
import stisim as sti

sw_analyzer = sti.sw_stats(diseases=['hiv', 'ng'])

sim = sti.Sim(
    diseases=['hiv', 'ng'],
    analyzers=[sw_analyzer],
    n_agents=5000,
)
sim.run()

# Access FSW/client results
print(f"Share of HIV infections among FSW: {sim.results.sw_stats.share_new_infections_fsw_hiv[-1]:.1%}")
```

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

### Trichomoniasis Care Seeking Parameters

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/diseases/trichomoniasis.md

Specifies the parameters related to individuals seeking medical care for Trichomoniasis. This includes the probability of seeking care when symptomatic and the time it takes from symptom onset to care seeking.

```python
Parameters:
  Care seeking:
    p_symp_care: [0.39, 0.27]
    dur_symp2care: F: [2 mo, 1 mo]; M: [1 wk, 2 wk]
```

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

### Define Disease States in STIsim

Source: https://github.com/starsimhub/stisim/blob/main/CLAUDE.md

Illustrates how to define states for a disease module within STIsim, using boolean and float array states for tracking infection status and time of infection.

```python
self.define_states(
    ss.BoolState('infected'),
    ss.FloatArr('ti_infected'),
)
```

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

### Define Simulation Results in STIsim

Source: https://github.com/starsimhub/stisim/blob/main/CLAUDE.md

Shows how to define result tracking for a STIsim simulation, including metrics like incidence and prevalence, specifying their data types and scaling behavior.

```python
self.define_results(
    ss.Result('incidence', dtype=int, scale=True),
    ss.Result('prevalence', dtype=float, scale=False),
)
```

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

### Combine Interventions in STISim (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

Interventions are combined and passed to the STISim simulation object as a list. This allows for the simultaneous application of various testing and treatment strategies within the simulation.

```python
sim = sti.Sim(
    diseases='ng',
    interventions=[test, treatment],
)
```

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

### Trichomoniasis Class Definition and Alias

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/diseases/trichomoniasis.md

Defines the Trichomoniasis class within the 'sti' module and its associated alias 'tv'. It inherits from the base 'SEIS' class, indicating its Susceptible-Exposed-Infectious-Susceptible disease progression.

```python
Class: sti.Trichomoniasis | Alias: 'tv' | Base class: SEIS
```

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

### Define a Generic Treatment Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

STITreatment is the base class for treatment interventions. It clears infection for eligible agents with a specified efficacy. Key parameters include the disease(s) to treat, treatment efficacy, and eligibility criteria.

```python
ct_tx = sti.STITreatment(
    diseases='ct',         # Which disease(s) to treat
    treat_eff=0.95,        # 95% efficacy
    name='ct_tx',
)
```

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

### PrEP Intervention

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

Configures Pre-exposure Prophylaxis (PrEP) intervention, typically targeting specific populations like FSWs, and reducing susceptibility.

```APIDOC
## PrEP Intervention

### Description
Configures Pre-exposure Prophylaxis (PrEP) intervention, typically targeting specific populations like FSWs, and reducing susceptibility.

### Method
POST (Conceptual - this is a class instantiation)

### Endpoint
N/A (Class definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **coverage** (list or array) - Required - A list or array specifying the coverage levels of PrEP over time.
- **years** (list or array) - Required - A list or array of years corresponding to the coverage levels.

### Request Example
```python
import stisim as sti

prep = sti.Prep(coverage=[0, 0.5], years=[2020, 2025])
```

### Response
#### Success Response (200)
N/A (Class instantiation)

#### Response Example
N/A
```

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

### Override Connector Parameters (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_cotransmission.ipynb

Demonstrates how to override the default effect parameters for a specific STIsim connector, such as `hiv_ng`. This allows fine-tuning the interaction strength (e.g., relative susceptibility `rel_sus_hiv_ng` and relative transmissibility `rel_trans_hiv_ng`) between two diseases.

```python
sti.hiv_ng(hiv, ng, rel_sus_hiv_ng=2.0, rel_trans_hiv_ng=2.0)
```

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

### Customize Disease Parameters for Multiple STIs (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_cotransmission.ipynb

Allows customization of default parameters for multiple STIs (Gonorrhea, Chlamydia, Trichomoniasis) using `sti_pars`. This enables overriding transmission rates (`beta_m2f`) and initial prevalences (`init_prev`) for each disease before running the simulation and plotting results.

```python
sim = sti.Sim(
    diseases=['ng', 'ct', 'tv'],
    sti_pars=dict(
        ng=dict(beta_m2f=0.08, init_prev=0.03),
        ct=dict(beta_m2f=0.08, init_prev=0.05),
        tv=dict(beta_m2f=0.12, init_prev=0.08),
    ),
    n_agents=2000,
    start=2010,
    stop=2030,
)
sim.run(verbose=0)
sim.plot(key=['ng.prevalence', 'ct.prevalence', 'tv.prevalence'])
```

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

### Compare HIV Acquisition With/Without Coinfection Connectors (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_cotransmission.ipynb

Compares cumulative HIV infections in simulations with and without coinfection connectors (specifically `hiv_ng`). This highlights the impact of STIs on HIV acquisition by running two simulations: one baseline and one with exaggerated connector effects, then plotting the cumulative infections.

```python
import matplotlib.pyplot as plt

def make_diseases():
    """ Helper to create fresh disease modules """
    return sti.HIV(init_prev=0.02, beta_m2f=0.03), sti.Gonorrhea(init_prev=0.15)

# Without connectors
hiv, ng = make_diseases()
s0 = sti.Sim(
    diseases=[hiv, ng],
    n_agents=5000, start=2010, stop=2020,
)
s0.run(verbose=0)

# With connectors (exaggerated effect for illustration)
hiv, ng = make_diseases()
s1 = sti.Sim(
    diseases=[hiv, ng],
    connectors=sti.hiv_ng(hiv, ng, rel_sus_hiv_ng=5, rel_trans_hiv_ng=5),
    n_agents=5000, start=2010, stop=2020,
)
s1.run(verbose=0)

# Compare cumulative HIV infections
fig, ax = plt.subplots()
ax.plot(s0.timevec, s0.results.hiv.cum_infections, label='Without connector')
ax.plot(s1.timevec, s1.results.hiv.cum_infections, label='With hiv_ng connector (5x)')
ax.set_xlabel('Year')
ax.set_ylabel('Cumulative HIV infections')
ax.set_title('Effect of gonorrhea coinfection on HIV acquisition')
ax.legend()
fig
```

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

### Run Multiple Bacterial STIs on a Shared Network (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/tutorials/tut_cotransmission.ipynb

Simulates the transmission of multiple bacterial STIs (Gonorrhea, Chlamydia, Trichomoniasis) on a single sexual network. Each disease has independent transmission, natural history, and clearance dynamics, but shares the same partnerships. The simulation plots the prevalence of each disease over time.

```python
import stisim as sti

sim = sti.Sim(
    diseases=['ng', 'ct', 'tv'],
    n_agents=2000,
    start=2010,
    stop=2030,
)
sim.run(verbose=0)
sim.plot(key=['ng.prevalence', 'ct.prevalence', 'tv.prevalence'])
```

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

### Define Symptomatic Testing Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

SymptomaticTesting implements syndromic management, testing symptomatic care-seekers and routing them to appropriate treatment. It's particularly useful for bacterial STIs where lab confirmation might not be readily available.

```python
syndromic = sti.SymptomaticTesting(
    diseases=[ng, ct, tv],
    treatments=[ng_tx, ct_tx, metro],
    disease_treatment_map={'ng': ng_tx, 'ct': ct_tx, 'tv': metro},
)
```

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

### Define ART Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

The ART intervention implements antiretroviral therapy with CD4-based prioritization and coverage targets. It reduces transmissibility and reconstitutes CD4 counts. Coverage can be specified using a DataFrame with year index and ART numbers or proportions.

```python
art = sti.ART(coverage_data=art_df)  # DataFrame with year index and n_art or p_art column
```

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

### Define VMMC Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

VMMC (Voluntary Medical Male Circumcision) intervention reduces male susceptibility to HIV. The default reduction in susceptibility is 60%. Coverage data should be provided.

```python
vmmc = sti.VMMC(coverage_data=vmmc_df)
```

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

### Define HIV-Specific Testing Intervention (Python)

Source: https://github.com/starsimhub/stisim/blob/main/docs/user_guide/interventions/interventions.md

HIVTest is a specialized testing intervention for HIV. It defaults to testing only undiagnosed agents and using a perfect diagnostic. On a positive result, it sets the 'diagnosed' state for HIV.

```python
hiv_test = sti.HIVTest(test_prob_data=0.1, start=2000)
```
Tokens:
Raw