HPVsim is a flexible agent-based model for simulation HPV transmission and progression through cervical disease to cancer. The model can be parameterized with country-specific vital dynamics, structured sexual networks, co-transmitting HPV genotypes, B- and T-cell mediated immunity, and high-resolution disease natural history. HPVsim is designed with a user-first lens: it is implemented in pure Python, has built-in tools for simulating commonly-used interventions, has been extensively tested and documented, and runs in a matter of seconds to minutes on a laptop.
Version 3.0 of HPVsim is built on the Starsim modeling architecture. This is a significant shift from the v2 series: the disease model, sexual network, demographics, interventions, and analyzers are now Starsim modules, and the API changed accordingly. The science is preserved — see the migration guide for a full v2→v3 walkthrough. The v2 series is frozen aside from critical bugfixes.
The scientific paper describing HPVsim is available at https://doi.org/10.1371/journal.pcbi.1012181. The recommended citation is:
HPVsim: An agent-based model of HPV transmission and cervical disease (2024). Stuart RM, Cohen JA, Kerr CC, Mathur P , NDMC India, Zimmermann M, Rao DW, Boudreau MC, Lee S, Yang L, Klein DJ. PLOS Computational Biology 20(7): e1012181. https://doi.org/10.1371/journal.pcbi.1012181
HPVsim has been used for analyses in several countries. Academic papers that have been written using HPVsim include:
- Inferring the natural history of HPV from global cancer registries: insights from a multi-country calibration (2024). Stuart RM, Cohen JA, Abeysuriya RG, Sanz-Leon P, Kerr CC, Rao DW, Klein DJ. Sci Rep 14, 15875. https://doi.org/10.1038/s41598-024-65842-3
- HPV DNA Screening and Vaccination Strategies in Tunisia (2025). Lahdhiri A, Benzina B, Ennaifer E, Tounsi H, Gzara A, Rammeh-Rommani S, Laraj O, Arfaoui H, Stuart RM Kebir, A, BenMiled S (2025). Sci Rep, forthcoming.
- Can pruning improve agent-based models’ calibration? An application to HPVsim (2025). Sturman F, Swallow B, Kerr CC, Stuart RM, Panovska-Griffiths J. Journal of Theoretical Biology, forthcoming.
The easiest way to install is simply via pip: pip install hpvsim.
Alternatively, you can clone this repository, then run
pip install -e . (don't forget the dot!) in this folder to install
hpvsim and its dependencies. This will make hpvsim available on the
Python path. The first time HPVsim is imported, it will automatically
download the required data files (~30 MB). You can also download the
data manually by running hpvsim-download-data from the terminal.
Documentation is available at https://docs.hpvsim.org, including
tutorials. Additional usage
examples are available in the examples folder.
If you wish to contribute, please follow the Starsim style guide at: https://github.com/starsimhub/styleguide. See the code of conduct readme for more information.
The code in this repository was developed by IDM, the Burnet Institute,
and other collaborators to support our joint research on HPV. 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. Note that HPVsim depends on a number of
user-installed Python packages that can be installed automatically via
pip install. 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 contemplated under
the MIT License.