parameters

parameters

HPV simulation parameters.

SimPars subclasses ss.SimPars with HPV-specific defaults. GenotypePars holds per-genotype natural-history defaults (durations, severity functions, immunity, age risk) consumed by HPV(ss.Infection); get_genotype_pars(genotype) is the factory multi-genotype consumers use to look up defaults by name. Supports the four canonical genotypes: hpv16, hpv18, hi5 (high-risk-5 pool), and ohr (other high-risk pool).

Classes

Name	Description
GenotypePars	Per-genotype natural-history defaults for HPV.
NetworkPars	Default parameters for hpv.SexualNetwork.
SimPars	HPV-specific defaults on top of ss.SimPars.

GenotypePars

parameters.GenotypePars(genotype='hpv16', **kwargs)

Per-genotype natural-history defaults for HPV.

Each call returns fresh distribution instances so per-genotype RNG state stays independent. Supported genotypes: hpv16, hpv18, hi5, ohr.

Notes

• beta is per-sex-act; SexualNetwork applies per-act via 1 - (1-p)**acts.
• Female natural-history durations are lognormal in years; males clear via dur_inf_male without entering CIN/cancer.
• cancer_fn carries cin_fn’s keys so the cin_integral branch can call compute_severity_integral on the same logf2.
• imm_init / cell_imm_init are per-agent uniform draws sampled each clearance and stored into nab_imm / cell_imm (read by the CrossImmunity Connector). sero_prob gates the first-clearance nab_imm sample per genotype.
• age_risk['age']-and-older women get dur_cin scaled by age_risk['risk'], shifting cancer onset to older ages.
• transf2m / transm2f are sex-directional per-act scalars — same across genotypes (act-level, not genotype-level).

NetworkPars

parameters.NetworkPars(**overrides)

Default parameters for hpv.SexualNetwork.

All values are location-agnostic (HPVsim ships demographic data per country but not network calibration). Analysis scripts supply per-country overrides.

Naming convention: per-layer pars carry a _marital / _casual suffix; per-sex pars carry a _f / _m suffix. All Dist-typed pars are ss.Dist instances directly (no v2 {'dist': ..., 'par1': ...} dicts).

Per-agent, per-layer partner-count targets are always shifted by +1 in the network’s sampling code (set_network_states). A participating agent in a layer wants at least one partner by definition; the lam values below govern only the tail of additional concurrent partners.

Keys

m_cross_layer, f_cross_layer: scalar annual probability of male/female cross-layer concurrency. debut_f, debut_m: per-sex debut-age ss.Dist. {sex}_partners_{layer}: per-layer per-sex partner-count Dist (ss.poisson; sampled value has +1 added at use). acts_{layer}: per-partnership annual act-count Dist. dur_pship_{layer}: partnership duration Dist (years). age_act_pars_{layer}: per-layer age-based act modulation (peak, retirement, debut_ratio, retirement_ratio) dict. mixing_{layer}: age-mixing matrix; rows = male age band, columns 1..N = female age band, and column 0 holds each row’s male age-band label. M[male_bin, female_bin + 1] is the relative weight males in that band give females in that band. layer_probs_{layer}: (3, N) array of age-band participation: row 0 = age-bin lower bounds, rows 1/2 = annual f/m prob.

SimPars

parameters.SimPars(**kwargs)

HPV-specific defaults on top of ss.SimPars.

location defaults to None to match hpv.Sim’s own default: a bare hpv.Sim() is a natural-history playground (uniform ages 0-60, no births/deaths/migration, pop_scale=1). Pass a country name for a real population, or call hpv.demo() for the canonical Nigeria sim.

Functions

Name	Description
expanddict	Convert a flat {‘a.b.c’: value} dict to nested {‘a’: {‘b’: {‘c’: value}}}.
get_genotype_pars	Return per-genotype natural-history defaults.
par_registry	Category -> par-name-set (built lazily; lightweight).
route_pars	Route a nested {key: value} dict of overrides onto sim’s modules.

expanddict

parameters.expanddict(flat)

Convert a flat {‘a.b.c’: value} dict to nested {‘a’: {‘b’: {‘c’: value}}}. The inverse of sc.flattendict. A key with no ‘.’ becomes a plain top-level entry.

get_genotype_pars

parameters.get_genotype_pars(genotype='hpv16')

Return per-genotype natural-history defaults.

par_registry

parameters.par_registry()

Category -> par-name-set (built lazily; lightweight).

No ‘hiv’ category: HIV’s pars overlap HPV’s on ‘beta’/‘init_prev’ (both inherited from stisim’s BaseSTIPars), so a bare-key broadcast would silently also flip on HIV transmission (e.g. bare beta= turning on hiv.pars.beta from its 0 default). The scoped hiv=dict(…) form in route_pars does NOT consult this registry – it dispatches directly by instance name – so scoped/hiv_pars= routing is unaffected.

route_pars

parameters.route_pars(
    sim,
    pars=None,
    calib_pars=None,
    verbose=True,
    strict=True,
    **_,
)

Route a nested {key: value} dict of overrides onto sim’s modules.

A top-level key is either

• Scoped: matches a live HPV genotype’s name, the HIV disease’s name ('hiv'), or cross_immunity/network (aliases crossimmunity/sexualnetwork). Routed to that instance’s pars via ONE instance.pars.update(value) call – starsim’s own Pars.update() handles arbitrarily nested overrides natively (merging into ss.Pars-typed sub-pars, calling .set() on Dist leaves, preserving TimePar units). Applied AFTER broadcast keys, so a scoped override always wins regardless of input dict ordering.
• A bare registry key: broadcast to every matching category (sim, hpv, hiv, connector, network) via instance.pars.update({key: value}). Applied FIRST.
• calib_pars (flat dotted) is converted to nested via expanddict before anything else runs.