HPVsim follows individual women and men through sexual partnerships, infection with one or more HPV genotypes, and — in women — the path from infection to precancer to invasive cervical cancer. On top of that it delivers vaccination, screening and treatment, and can carry HIV infection alongside HPV.
HPVsim covers cervical cancer only. HPV also causes anal, oropharyngeal, penile, vaginal and vulvar cancers — the first three of these also occur in men — but none of them are in the model.
Each agent stands for many real people. When you give a location, HPVsim looks up that country’s population size and sets pop_scale = total_pop / n_agents, so results come out in real-population units. A run with 2,000 agents representing Nigeria in 1990 has each agent standing for about 48,000 people. This is what makes a country projection tractable on a laptop.
The layers
A simulation is a set of modules that share one population. Each layer answers a different question.
Layer
What it does
Classes
Population
Holds age, sex and every per-agent state; adds births, removes deaths, pins the age pyramid to the country’s trajectory
One disease module per genotype is the central design choice. Genotypes differ in how well they transmit, how fast they progress, and how well vaccines cover them, and each of those needs its own per-agent record. Because the modules share one population, a woman can carry HPV16 and HPV18 at the same time — and when one genotype takes her to cancer, the other genotypes’ pending progression is cancelled, so she is counted as one cancer case, not two.
What happens in a timestep
The default timestep is three months (dt=0.25). Within each one, the order is fixed:
Demographics. Births are added, deaths removed. Once a year, migration adds or removes people so the age and sex composition matches the country’s projected pyramid.
Progression. Each genotype moves its infected women along: infections clear (or turn latent), precancer becomes CIN, CIN becomes cancer, and women with cancer die.
Immunity. The cross-immunity module reads the antibody and cell-mediated immunity each woman has accumulated and writes this timestep’s susceptibility and severity factors for every genotype.
Partnerships. The network dissolves the pairs whose duration has run out and forms new ones.
Interventions. Vaccines, screening tests and treatments are delivered.
Transmission. Each genotype passes along the partnerships formed in step 4.
Bookkeeping. The dead are removed, results are recorded, analyzers run.
Two consequences of that order are worth holding onto. Immunity is applied before interventions, so a woman vaccinated in one timestep is protected from the next one onwards — a three-month lag at the default dt. And transmission uses the partnerships formed in the same timestep, so partnership turnover and transmission are never more than one timestep out of step.
Not every module runs on the sim’s clock. Migration and hpv.AnnualBirths run once per calendar year; the HIV modules run quarterly whatever dt you choose.
Reading the results
Results are grouped by the module that produced them: sim.results.hpv16.new_cancers for one genotype, sim.results.all_hpv.cum_cancers for the pooled total, sim.results.agemigration.new_immigrants for migration flows. Anything counted in people is multiplied by pop_scale; anything that is a proportion is not. See Results and analyzers.