T1 - Getting started¶
Installing and getting started with HPVsim is quite simple.
HPVsim is a Python package that can be pip-installed by typing pip install hpvsim into a terminal. You can then check that the installation was successful by importing HPVsim with import hpvsim as hpv.
The basic design philosophy of HPVsim is: common tasks should be simple. For example:
Defining parameters
Running a simulation
Plotting results
This tutorial walks you through how to do these things.
Click here to open an interactive version of this notebook.
Hello world¶
To create, run, and plot a sim with default options is just:
[1]:
import hpvsim as hpv
sim = hpv.Sim()
sim.run()
fig = sim.plot()
HPVsim 1.1.1 (2023-03-01) — © 2023 by IDM
Loading location-specific demographic data for "nigeria"
Initializing sim with 20000 agents
Loading location-specific data for "nigeria"
Running 1995.0 ( 0/144) (1.02 s) ———————————————————— 1%
Running 1997.5 (10/144) (1.42 s) •——————————————————— 8%
Running 2000.0 (20/144) (1.83 s) ••—————————————————— 15%
Running 2002.5 (30/144) (2.27 s) ••••———————————————— 22%
Running 2005.0 (40/144) (2.75 s) •••••——————————————— 28%
Running 2007.5 (50/144) (3.25 s) •••••••————————————— 35%
Running 2010.0 (60/144) (3.77 s) ••••••••———————————— 42%
Running 2012.5 (70/144) (4.31 s) •••••••••——————————— 49%
Running 2015.0 (80/144) (4.89 s) •••••••••••————————— 56%
Running 2017.5 (90/144) (5.54 s) ••••••••••••———————— 63%
Running 2020.0 (100/144) (6.17 s) ••••••••••••••—————— 70%
Running 2022.5 (110/144) (6.84 s) •••••••••••••••————— 77%
Running 2025.0 (120/144) (7.55 s) ••••••••••••••••———— 84%
Running 2027.5 (130/144) (8.28 s) ••••••••••••••••••—— 91%
Running 2030.0 (140/144) (9.05 s) •••••••••••••••••••— 98%
Simulation summary:
74,687,882 infections
0 dysplasias
0 pre-cins
2,660,347 cin1s
553,327 cin2s
303,902 cin3s
6,916,582 cins
14,421 cancers
0 cancer detections
6,943 cancer deaths
0 detected cancer deaths
62,028,132 reinfections
0 reactivations
665,669,184 number susceptible
83,682,120 number infectious
129,252 number with inactive infection
259,850,416 number with no cellular changes
83,682,120 number with episomal infection
128,718 number with transformation
129,252 number with cancer
83,811,360 number infected
83,811,360 number with abnormal cells
0 number with latent infection
43,536,556 number with precin
18,460,068 number with cin1
3,408,620 number with cin2
2,663,552 number with cin3
1,426,044 number with carcinoma in situ
24,525,296 number with detectable dysplasia
0 number with detected cancer
0 number screened
0 number treated for precancerous lesions
0 number treated for cancer
0 number vaccinated
0 number given therapeutic vaccine
3.74 hpv incidence (/100)
0 cin1 incidence (/100,000)
0 cin2 incidence (/100,000)
0 cin3 incidence (/100,000)
0 dysplasia incidence (/100,000)
11 cancer incidence (/100,000)
9,410,825 births
2,651,268 other deaths
-1,036,152 migration
17 age-adjusted cervical cancer incidence (/100,000)
0 age-adjusted cervical cancer mortality
0 newly vaccinated
0 cumulative number vaccinated
0 new doses
0 cumulative doses
0 new therapeutic vaccine doses
0 newly received therapeutic vaccine
0 cumulative therapeutic vaccine doses
0 total received therapeutic vaccine
0 new screens
0 newly screened
0 new cin treatments
0 newly treated for cins
0 new cancer treatments
0 newly treated for cancer
0 cumulative screens
0 cumulative number screened
0 cumulative cin treatments
0 cumulative number treated for cins
0 cumulative cancer treatments
0 cumulative number treated for cancer
0 detected cancer incidence (/100,000)
5 cancer mortality
259,850,416 number alive
0 crude death rate
0 crude birth rate
10.73 hpv prevalence (/100)
0 pre-cin prevalence (/100,000)
0 cin1 prevalence (/100,000)
0 cin2 prevalence (/100,000)
0 cin3 prevalence (/100,000)
Defining parameters and genotypes, and running simulations¶
Parameters are defined as a dictionary. Some common parameters to modify are the number of agents in the simulation, the genotypes to simulate, and the start and end dates of the simulation. We can define those as:
[2]:
pars = dict(
n_agents = 10e3,
genotypes = [16, 18, 'hrhpv'], # Simulate genotypes 16 and 18, plus all other high-risk HPV genotypes pooled together
start = 1980,
end = 2030,
)
Running a simulation is pretty easy. In fact, running a sim with the parameters we defined above is just:
[3]:
sim = hpv.Sim(pars)
sim.run()
Loading location-specific demographic data for "nigeria"
Loading location-specific demographic data for "nigeria"
Initializing sim with 10000 agents
Loading location-specific data for "nigeria"
Running 1980.0 ( 0/204) (0.04 s) ———————————————————— 0%
Running 1982.5 (10/204) (0.33 s) •——————————————————— 5%
Running 1985.0 (20/204) (0.62 s) ••—————————————————— 10%
Running 1987.5 (30/204) (0.94 s) •••————————————————— 15%
Running 1990.0 (40/204) (1.26 s) ••••———————————————— 20%
Running 1992.5 (50/204) (1.59 s) •••••——————————————— 25%
Running 1995.0 (60/204) (1.94 s) •••••——————————————— 30%
Running 1997.5 (70/204) (2.30 s) ••••••—————————————— 35%
Running 2000.0 (80/204) (2.68 s) •••••••————————————— 40%
Running 2002.5 (90/204) (3.08 s) ••••••••———————————— 45%
Running 2005.0 (100/204) (3.49 s) •••••••••——————————— 50%
Running 2007.5 (110/204) (3.93 s) ••••••••••—————————— 54%
Running 2010.0 (120/204) (4.38 s) •••••••••••————————— 59%
Running 2012.5 (130/204) (4.85 s) ••••••••••••———————— 64%
Running 2015.0 (140/204) (5.33 s) •••••••••••••——————— 69%
Running 2017.5 (150/204) (5.83 s) ••••••••••••••—————— 74%
Running 2020.0 (160/204) (6.35 s) •••••••••••••••————— 79%
Running 2022.5 (170/204) (6.90 s) ••••••••••••••••———— 84%
Running 2025.0 (180/204) (7.47 s) •••••••••••••••••——— 89%
Running 2027.5 (190/204) (8.09 s) ••••••••••••••••••—— 94%
Running 2030.0 (200/204) (8.71 s) •••••••••••••••••••— 99%
Simulation summary:
77,196,281 infections
0 dysplasias
0 pre-cins
3,156,116 cin1s
513,569 cin2s
290,903 cin3s
7,740,889 cins
22,985 cancers
0 cancer detections
10,774 cancer deaths
0 detected cancer deaths
64,950,347 reinfections
0 reactivations
661,182,848 number susceptible
86,624,408 number infectious
158,740 number with inactive infection
260,046,320 number with no cellular changes
86,624,408 number with episomal infection
123,544 number with transformation
158,740 number with cancer
86,783,152 number infected
86,783,152 number with abnormal cells
0 number with latent infection
46,856,912 number with precin
20,112,520 number with cin1
3,658,911 number with cin2
3,082,852 number with cin3
1,930,733 number with carcinoma in situ
27,191,872 number with detectable dysplasia
0 number with detected cancer
0 number screened
0 number treated for precancerous lesions
0 number treated for cancer
0 number vaccinated
0 number given therapeutic vaccine
3.89 hpv incidence (/100)
0 cin1 incidence (/100,000)
0 cin2 incidence (/100,000)
0 cin3 incidence (/100,000)
0 dysplasia incidence (/100,000)
18 cancer incidence (/100,000)
9,416,633 births
2,407,670 other deaths
-1,256,988 migration
25 age-adjusted cervical cancer incidence (/100,000)
0 age-adjusted cervical cancer mortality
0 newly vaccinated
0 cumulative number vaccinated
0 new doses
0 cumulative doses
0 new therapeutic vaccine doses
0 newly received therapeutic vaccine
0 cumulative therapeutic vaccine doses
0 total received therapeutic vaccine
0 new screens
0 newly screened
0 new cin treatments
0 newly treated for cins
0 new cancer treatments
0 newly treated for cancer
0 cumulative screens
0 cumulative number screened
0 cumulative cin treatments
0 cumulative number treated for cins
0 cumulative cancer treatments
0 cumulative number treated for cancer
0 detected cancer incidence (/100,000)
8 cancer mortality
260,046,320 number alive
0 crude death rate
0 crude birth rate
11.10 hpv prevalence (/100)
0 pre-cin prevalence (/100,000)
0 cin1 prevalence (/100,000)
0 cin2 prevalence (/100,000)
0 cin3 prevalence (/100,000)
[3]:
Sim(<no label>; 1980 to 2030; pop: 10000 default; epi: 2.10805e+09⚙, 359139♋︎)
This will generate a results dictionary sim.results. Results by genotype are named things like sim.results['infections'] and stored as arrays where each row corresponds to a genotype, while totals across all genotypes have names like sim.results['infections'] or sim.results['cancers'].
Rather than creating a parameter dictionary, any valid parameter can also be passed to the sim directly. For example, exactly equivalent to the above is:
[4]:
sim = hpv.Sim(n_agents=10e3, start=1980, end=2030)
sim.run()
Loading location-specific demographic data for "nigeria"
Loading location-specific demographic data for "nigeria"
Initializing sim with 10000 agents
Loading location-specific data for "nigeria"
Running 1980.0 ( 0/204) (0.04 s) ———————————————————— 0%
Running 1982.5 (10/204) (0.33 s) •——————————————————— 5%
Running 1985.0 (20/204) (0.63 s) ••—————————————————— 10%
Running 1987.5 (30/204) (0.94 s) •••————————————————— 15%
Running 1990.0 (40/204) (1.26 s) ••••———————————————— 20%
Running 1992.5 (50/204) (1.59 s) •••••——————————————— 25%
Running 1995.0 (60/204) (1.94 s) •••••——————————————— 30%
Running 1997.5 (70/204) (2.29 s) ••••••—————————————— 35%
Running 2000.0 (80/204) (2.66 s) •••••••————————————— 40%
Running 2002.5 (90/204) (3.06 s) ••••••••———————————— 45%
Running 2005.0 (100/204) (3.46 s) •••••••••——————————— 50%
Running 2007.5 (110/204) (3.90 s) ••••••••••—————————— 54%
Running 2010.0 (120/204) (4.35 s) •••••••••••————————— 59%
Running 2012.5 (130/204) (4.83 s) ••••••••••••———————— 64%
Running 2015.0 (140/204) (5.31 s) •••••••••••••——————— 69%
Running 2017.5 (150/204) (5.81 s) ••••••••••••••—————— 74%
Running 2020.0 (160/204) (6.32 s) •••••••••••••••————— 79%
Running 2022.5 (170/204) (6.87 s) ••••••••••••••••———— 84%
Running 2025.0 (180/204) (7.44 s) •••••••••••••••••——— 89%
Running 2027.5 (190/204) (8.07 s) ••••••••••••••••••—— 94%
Running 2030.0 (200/204) (8.68 s) •••••••••••••••••••— 99%
Simulation summary:
77,196,281 infections
0 dysplasias
0 pre-cins
3,156,116 cin1s
513,569 cin2s
290,903 cin3s
7,740,889 cins
22,985 cancers
0 cancer detections
10,774 cancer deaths
0 detected cancer deaths
64,950,347 reinfections
0 reactivations
661,182,848 number susceptible
86,624,408 number infectious
158,740 number with inactive infection
260,046,320 number with no cellular changes
86,624,408 number with episomal infection
123,544 number with transformation
158,740 number with cancer
86,783,152 number infected
86,783,152 number with abnormal cells
0 number with latent infection
46,856,912 number with precin
20,112,520 number with cin1
3,658,911 number with cin2
3,082,852 number with cin3
1,930,733 number with carcinoma in situ
27,191,872 number with detectable dysplasia
0 number with detected cancer
0 number screened
0 number treated for precancerous lesions
0 number treated for cancer
0 number vaccinated
0 number given therapeutic vaccine
3.89 hpv incidence (/100)
0 cin1 incidence (/100,000)
0 cin2 incidence (/100,000)
0 cin3 incidence (/100,000)
0 dysplasia incidence (/100,000)
18 cancer incidence (/100,000)
9,416,633 births
2,407,670 other deaths
-1,256,988 migration
25 age-adjusted cervical cancer incidence (/100,000)
0 age-adjusted cervical cancer mortality
0 newly vaccinated
0 cumulative number vaccinated
0 new doses
0 cumulative doses
0 new therapeutic vaccine doses
0 newly received therapeutic vaccine
0 cumulative therapeutic vaccine doses
0 total received therapeutic vaccine
0 new screens
0 newly screened
0 new cin treatments
0 newly treated for cins
0 new cancer treatments
0 newly treated for cancer
0 cumulative screens
0 cumulative number screened
0 cumulative cin treatments
0 cumulative number treated for cins
0 cumulative cancer treatments
0 cumulative number treated for cancer
0 detected cancer incidence (/100,000)
8 cancer mortality
260,046,320 number alive
0 crude death rate
0 crude birth rate
11.10 hpv prevalence (/100)
0 pre-cin prevalence (/100,000)
0 cin1 prevalence (/100,000)
0 cin2 prevalence (/100,000)
0 cin3 prevalence (/100,000)
[4]:
Sim(<no label>; 1980 to 2030; pop: 10000 default; epi: 2.10805e+09⚙, 359139♋︎)
You can mix and match too – pass in a parameter dictionary with default options, and then include other parameters as keywords (including overrides; keyword arguments take precedence). For example:
[5]:
sim = hpv.Sim(pars, end=2050) # Use parameters defined above, except set the end data to 2050
sim.run()
Loading location-specific demographic data for "nigeria"
Loading location-specific demographic data for "nigeria"
Initializing sim with 10000 agents
Loading location-specific data for "nigeria"
Running 1980.0 ( 0/284) (0.04 s) ———————————————————— 0%
Running 1982.5 (10/284) (0.33 s) ———————————————————— 4%
Running 1985.0 (20/284) (0.62 s) •——————————————————— 7%
Running 1987.5 (30/284) (0.93 s) ••—————————————————— 11%
Running 1990.0 (40/284) (1.25 s) ••—————————————————— 14%
Running 1992.5 (50/284) (1.58 s) •••————————————————— 18%
Running 1995.0 (60/284) (1.93 s) ••••———————————————— 21%
Running 1997.5 (70/284) (2.28 s) •••••——————————————— 25%
Running 2000.0 (80/284) (2.66 s) •••••——————————————— 29%
Running 2002.5 (90/284) (3.07 s) ••••••—————————————— 32%
Running 2005.0 (100/284) (3.47 s) •••••••————————————— 36%
Running 2007.5 (110/284) (3.90 s) •••••••————————————— 39%
Running 2010.0 (120/284) (4.34 s) ••••••••———————————— 43%
Running 2012.5 (130/284) (4.82 s) •••••••••——————————— 46%
Running 2015.0 (140/284) (5.29 s) •••••••••——————————— 50%
Running 2017.5 (150/284) (5.79 s) ••••••••••—————————— 53%
Running 2020.0 (160/284) (6.30 s) •••••••••••————————— 57%
Running 2022.5 (170/284) (6.85 s) ••••••••••••———————— 60%
Running 2025.0 (180/284) (7.41 s) ••••••••••••———————— 64%
Running 2027.5 (190/284) (8.04 s) •••••••••••••——————— 67%
Running 2030.0 (200/284) (8.65 s) ••••••••••••••—————— 71%
Running 2032.5 (210/284) (9.30 s) ••••••••••••••—————— 74%
Running 2035.0 (220/284) (9.99 s) •••••••••••••••————— 78%
Running 2037.5 (230/284) (10.71 s) ••••••••••••••••———— 81%
Running 2040.0 (240/284) (11.44 s) ••••••••••••••••———— 85%
Running 2042.5 (250/284) (12.22 s) •••••••••••••••••——— 88%
Running 2045.0 (260/284) (13.05 s) ••••••••••••••••••—— 92%
Running 2047.5 (270/284) (13.89 s) •••••••••••••••••••— 95%
Running 2050.0 (280/284) (14.79 s) •••••••••••••••••••— 99%
Simulation summary:
119,107,121 infections
0 dysplasias
0 pre-cins
4,558,196 cin1s
913,650 cin2s
545,892 cin3s
12,206,426 cins
25,858 cancers
0 cancer detections
16,520 cancer deaths
0 detected cancer deaths
101,647,921 reinfections
0 reactivations
939,264,512 number susceptible
136,983,648 number infectious
267,200 number with inactive infection
375,166,304 number with no cellular changes
136,983,648 number with episomal infection
183,161 number with transformation
267,200 number with cancer
137,250,848 number infected
137,250,848 number with abnormal cells
0 number with latent infection
73,368,576 number with precin
32,637,862 number with cin1
5,970,331 number with cin2
5,701,695 number with cin3
4,107,836 number with carcinoma in situ
45,732,084 number with detectable dysplasia
0 number with detected cancer
0 number screened
0 number treated for precancerous lesions
0 number treated for cancer
0 number vaccinated
0 number given therapeutic vaccine
4.23 hpv incidence (/100)
0 cin1 incidence (/100,000)
0 cin2 incidence (/100,000)
0 cin3 incidence (/100,000)
0 dysplasia incidence (/100,000)
14 cancer incidence (/100,000)
13,697,573 births
3,347,179 other deaths
-4,776,553 migration
16 age-adjusted cervical cancer incidence (/100,000)
0 age-adjusted cervical cancer mortality
0 newly vaccinated
0 cumulative number vaccinated
0 new doses
0 cumulative doses
0 new therapeutic vaccine doses
0 newly received therapeutic vaccine
0 cumulative therapeutic vaccine doses
0 total received therapeutic vaccine
0 new screens
0 newly screened
0 new cin treatments
0 newly treated for cins
0 new cancer treatments
0 newly treated for cancer
0 cumulative screens
0 cumulative number screened
0 cumulative cin treatments
0 cumulative number treated for cins
0 cumulative cancer treatments
0 cumulative number treated for cancer
0 detected cancer incidence (/100,000)
9 cancer mortality
375,166,304 number alive
0 crude death rate
0 crude birth rate
12.17 hpv prevalence (/100)
0 pre-cin prevalence (/100,000)
0 cin1 prevalence (/100,000)
0 cin2 prevalence (/100,000)
0 cin3 prevalence (/100,000)
[5]:
Sim(<no label>; 1980 to 2050; pop: 10000 default; epi: 4.09351e+09⚙, 808782♋︎)
Plotting results¶
As you saw above, plotting the results of a simulation is rather easy too:
[6]:
fig = sim.plot()
Full usage example¶
Many of the details of this example will be explained in later tutorials, but to give you a taste, here’s an example of how you would run two simulations to determine the impact of a custom intervention aimed at protecting the elderly.
[7]:
import hpvsim as hpv
# Custom vaccination intervention
def custom_vx(sim):
if sim.yearvec[sim.t] == 2000:
target_group = (sim.people.age>9) * (sim.people.age<14)
sim.people.peak_imm[0, target_group] = 1
pars = dict(
location = 'tanzania', # Use population characteristics for Japan
n_agents = 10e3, # Have 50,000 people total in the population
start = 1980, # Start the simulation in 1980
n_years = 50, # Run the simulation for 50 years
burnin = 10, # Discard the first 20 years as burnin period
verbose = 0, # Do not print any output
)
# Running with multisims -- see Tutorial 3
s1 = hpv.Sim(pars, label='Default')
s2 = hpv.Sim(pars, interventions=custom_vx, label='Custom vaccination')
msim = hpv.MultiSim([s1, s2])
msim.run()
fig = msim.plot(['cancers', 'dysplasias'])
Loading location-specific demographic data for "nigeria"
Loading location-specific demographic data for "tanzania"
Loading location-specific demographic data for "nigeria"
Loading location-specific demographic data for "tanzania"
<Figure size 640x480 with 0 Axes>
[ ]: