STIsim

STIsim is an agent-based modeling framework in which users can design and configure simulations of co-circulating sexually-transmitted diseases. STIsim uses the Starsim architecture, and belongs to the Starsim model suite which also includes Covasim, HPVsim, and FPsim.

Requirements

Python 3.9-3.14 or R.

We recommend, but do not require, installing STIsim in a virtual environment, such as Miniconda.

Installation

Python

STIsim is most easily installed via PyPI:

pip install stisim

Or with uv:

uv init example
cd example
uv add stisim

STIsim can also be installed locally (including optional dependencies for testing and documentation). To do this, clone first this repository, then run:

pip install -e .[dev]

For users without Python

If you don't already have Python set up, the install/ folder contains standalone installers that handle Miniforge (conda-forge) and STIsim in one step:

• Linux / macOS: curl -LsSf https://stisim.org/install.sh | sh
• Windows: download install.bat and double-click it.

See install/README.md for details.

R

STIsim can be used from R via rstarsim, which calls the Python engine through reticulate. The Python packages are required regardless of whether you use the R or Python interface.

Install the R packages:

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

On first use, rstarsim will set up a conda environment automatically if needed. To use an existing environment instead:

library(starsim)
load_starsim("my_env_name")

See r.starsim.org for more information on using Starsim from R.

AI plugin (optional)

STIsim ships with stisim.ai, a Claude Code plugin with skills for scoping, building, and calibrating STIsim/HIVsim analyses. After installing STIsim, register it with Claude Code:

python -m stisim.ai install

Then reload Claude Code (exit and relaunch claude, or in VS Code run Developer: Reload Window). The skills are available as /stisim:<skill-name> (e.g. /stisim:analysis-intake). Use python -m stisim.ai status to check the registration and python -m stisim.ai uninstall to remove it. See the AI plugin user guide for more information.

Usage and documentation

Documentation, including tutorials and a user guide, is available at https://docs.stisim.org. Additional resources:

1. The examples below show how to set up, calibrate, and run country-level models
2. Read the articles that have been published about analyses using STIsim (see references below)
3. Email us: info@starsim.org

Development roadmap

The roadmap for future model development can be viewed here.

References

Publications using STIsim include:

1. Reduction in overtreatment of gonorrhoea and chlamydia through point-of-care testing compared with syndromic management for vaginal discharge: a modelling study for Zimbabwe (2026). Stuart RM, Newman LM, Manguro G, Dziva Chikwari C, Marks M, Peters RPH, Klein D, Snyder L, Kerr C, Rao DW. Sex Transm Infect https://doi.org/10.1136/sextrans-2025-056646. Preprint: https://doi.org/10.21203/rs.3.rs-8843262/v1

2. Point-of-care testing to strengthen sexually transmitted infection case management in resource-constrained settings (2026). Peters RPH, Manguro G, Ong'wen PA, Mdingi MM, Applegate TL, Stuart R, Harding-Esch EM, Manabe YC, Ndowa F, Van Der Pol B. Sex Transm Infect, https://doi.org/10.1136/sextrans-2025-056833.

3. Estimating the value of novel tests for active syphilis in Zimbabwe: how much overtreatment can be avoided? (2026). Stuart RM, Marks M, Dziva Chikwari C, Muellenmeister AM, Abeysuriya RG, Manguro G, Peters RPH, Rao DW, Newman LM. Forthcoming in STD (accepted May 3, 2026). Preprint: https://doi.org/10.21203/rs.3.rs-9559421/v1

Examples

The following repositories contain end-to-end analyses built with STIsim, and are a good starting point for understanding how to set up, calibrate, and run country-level models:

• hiv_kenya -- HIV transmission model for Kenya with structured sexual networks, testing (FSW-targeted and general population), ART, and PrEP. Includes both Python and R interfaces and Optuna-based calibration.
• hiv_zambia -- HIV transmission model for Zambia. Similar structure to the Kenya model, useful for comparing how the same framework is adapted to a different country context.
• stisim_vddx_zim -- Multi-STI model (gonorrhea, chlamydia, trichomoniasis, BV) for Zimbabwe evaluating point-of-care diagnostics vs. syndromic management for vaginal discharge. Demonstrates co-circulating STIs, intervention comparison, and scenario analysis.
• syph_dx_zim -- Joint HIV-syphilis model for Zimbabwe evaluating syphilis diagnostic algorithms. Features coinfection connectors, stage-specific syphilis transmission, congenital syphilis, and treatment pathway analysis.
• hiv_vmb_southafrica -- HIV-vaginal microbiome transmission model calibrated to South Africa. This model was developed to evaluate novel products to shift the vaginal microbiome and their impact on HIV and pre-term birth.

Contributing

We welcome all contributions to STIsim! Please refer to our code of conduct and contributors's guide. You'll find information there about our style guide, which is essential reading prior to contributing. Questions or comments can be directed to info@starsim.org, or on this project's GitHub page.

See .github/workflows/README.md for details on publishing new releases of STIsim.

Disclaimer

The code in this repository was developed by IDM, the Burnet Institute, and other collaborators to support our joint research on flexible agent-based modeling. We've made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as permitted under the MIT License.