sim

sim

HPVsim convenience Sim wrapper.

hpv.Sim(location='nigeria', genotypes=[16, 18, 'hi5', 'ohr']) instantiates the default stack — one HPV disease module per genotype, multi-layer SexualNetwork, ss.Births + ss.Deaths + AgeMigration demographics, ss.People with location-specific age pyramid, plus a CrossImmunity connector and an HPVTotal analyzer — and forwards to ss.Sim.

connectors= and analyzers= are append, not override: user-supplied modules are added after the auto-defaults (CrossImmunity, the _ExclusiveSeeder when init_seeding='exclusive', and the HPVTotal analyzer). Other slots (diseases, networks, demographics, people) retain override semantics. diseases= is mutually exclusive with genotypes=. See Sim.__init__ for the full argument set.

Classes

Name	Description
Sim	HPVsim simulation.

Sim

sim.Sim(
    location=None,
    genotypes=None,
    genotype_pars=None,
    init_seeding='exclusive',
    init_hpv_dist=None,
    n_agents=10000,
    start=1990,
    stop=2060,
    dt=0.25,
    total_pop=None,
    ms_agent_ratio=1,
    pars=None,
    v2_compat_demographics=False,
    end=None,
    datafolder=None,
    model_hiv=None,
    hiv_data=None,
    hiv_pars=None,
    nw_pars=None,
    imm_pars=None,
    **kwargs,
)

HPVsim simulation.

The final sim year is stop (Starsim’s name). end is accepted as a deprecated v2 alias — if supplied it overrides stop and warns.

Parameters

Name	Type	Description	Default
init_seeding	str, default \'exclusive\'	'exclusive' — one Bernoulli per agent using the hpv16 age-banded curve as the total HPV prevalence, then exactly one genotype assigned per infected agent. No co-infection at initialisation. 'independent' — each genotype draws from its own per-genotype init_prev curve independently; co-infection at initialisation is possible.	'exclusive'
init_hpv_dist	dict or None, default None	Only used when init_seeding='exclusive'. If None, genotype assignment is uniform. If a dict, keys are canonical genotype names (e.g. {'hpv16': 0.6, 'hpv18': 0.2, 'hi5': 0.1, 'ohr': 0.1}) and values are weights; normalised internally.	None
model_hiv	True, \'incidence\', \'transmission\', or None	Adds HIV co-infection. 'incidence' (the default under True) imposes a per-(age,sex,year) incidence curve (hpv.HIV_incidence) plus a coverage-based sti.ART intervention (ART data is mandatory in this mode); 'transmission' drives HIV via network transmission instead (hpv.HIV_transmit) with no auto-added ART. hiv_data= supplies the input data (a folder path or a dict with {'incidence', 'art_coverage', 'init_prev'}); hiv_pars= overrides the constructed HIV disease’s pars. Mutually exclusive with supplying your own HIV-family disease in diseases=.	None
v2_compat_demographics	bool, default False	Forces discrete integer-age demographics for bit-for-bit compatibility with the v2 discrete-cohort convention. Activates annual-pulse births (hpv.AnnualBirths), disables migration jitter, and floors initial ages to integers. Not recommended for new work — the continuous-age default is preferred.	False

Methods

Name	Description
init	Initialize the sim, then discretize initial ages if v2_compat_demographics is set.
shrink	Shrink the sim for saving; skips the per-module size check by default.

init

sim.Sim.init(**kwargs)

Initialize the sim, then discretize initial ages if v2_compat_demographics is set.

ss.People.init_vals() samples ages continuously from the UN year-band histogram (each agent lands uniformly within its year bin, e.g. an agent in the “age 5” bin gets a float in [5, 6)). When v2_compat_demographics=True, floor all initial agent ages to integers after sampling so the starting cohort lands at exact integer ages.

Note: super().init() runs SexualNetwork.init_post, which pre-forms one batch of partnerships using debut ages sampled against the continuous initial-age distribution. The integer-age floor below runs after that pre-form, so the very first pair graph reflects continuous ages while every subsequent step sees integer ages; this one-off transient at initialisation is negligible.

shrink

sim.Sim.shrink(inplace=True, full=True, size_limit=None, base_size=30, die=True)

Shrink the sim for saving; skips the per-module size check by default.

Identical to ss.Sim.shrink except size_limit defaults to None rather than 1.0. The CrossImmunity connector and HPVTotal analyzer each hold references to the shared disease modules; starsim’s per-module size budget counts those referenced modules against them and raises on a multi-genotype sim, even though sc.save serializes the disease modules once and the actual file is small (~1 MB). Dist and back-reference shrinking still run — only the (double-counting) size check is disabled. Pass size_limit=1.0 to restore it.