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)

../_images/tutorials_tut_intro_3_1.svg

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()
../_images/tutorials_tut_intro_13_0.svg

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"
../_images/tutorials_tut_intro_15_1.svg
<Figure size 640x480 with 0 Axes>
[ ]: