utils

utils

HPVsim utility helpers.

The progression / severity math (logf2, compute_severity, …) is pure: it doesn’t depend on starsim or any module state, so calibration code, future genotype extensions, and visualisation scripts (e.g. tests/regression/methods_fig1.py) can import it without pulling in the disease module.

iter_hpv_modules / find_genotype_module / any_genotype_cancer are the sim-dependent helpers here — shared genotype-module walkers used by products / interventions (and anything else that needs to resolve or scan HPV modules). They late-import HPV so this module stays import-light.

Functions

Name	Description
any_genotype_cancer	Return a BoolArr OR-ing module.cancerous across all HPV modules.
compute_severity
compute_severity_integral	Process functional form and parameters into values:
find_genotype_module	Return the HPV disease module in sim matching genotype, or None.
get_asymptotes	Get upper asymptotes for logistic functions
indef_int_logf2	Indefinite integral of logf2; see definition there for arguments
intlogf2	Integral of logf2 between 0 and the limit given by upper
iter_hpv_modules	Yield each HPV disease module registered in sim, in registration order.
logf2	Logistic function constrained to pass through (0,0) and (ttc,y_max).
logf3	Logistic function passing through (0,0) and (ttc,y_max).
transform_prob	Returns transformation probability given dysplasia

any_genotype_cancer

utils.any_genotype_cancer(sim)

Return a BoolArr OR-ing module.cancerous across all HPV modules.

Used to gate cancer-status eligibility: treat_cancer=True interventions require this BoolArr be True; the inverse (~any_genotype_cancer(sim)) gates non-cancer treatments.

compute_severity

utils.compute_severity(t, rel_sev=None, pars=None)

This function is used for two types of calculation related to disease progression

1. to model the probability of progressing to further disease stages
2. to model the ‘severity’ of dysplasia on a scale from 0-1, historically interpreted as the percentage of the epithelium affected by dysplasia.

Args: t: array of durations that women have been in their current health state rel_sev: array of individual relative severity values pars: dict with required key ‘form’, which dictates which subfunction will be used.

Notes

If the pars dict contains the key ‘cin_integral’, then this function will call compute_severity_integral to determine the progression probabilities.

compute_severity_integral

utils.compute_severity_integral(t, rel_sev=None, pars=None)

Process functional form and parameters into values:

find_genotype_module

utils.find_genotype_module(sim, genotype)

Return the HPV disease module in sim matching genotype, or None.

Shared so products / interventions resolve modules the same way (and so future per-genotype lookups have one home).

get_asymptotes

utils.get_asymptotes(k, x_infl, s=1, y_max=1, ttc=25)

Get upper asymptotes for logistic functions

indef_int_logf2

utils.indef_int_logf2(x, k, x_infl, ttc=25, y_max=1)

Indefinite integral of logf2; see definition there for arguments

intlogf2

utils.intlogf2(upper, k, x_infl, ttc=25, y_max=1)

Integral of logf2 between 0 and the limit given by upper

iter_hpv_modules

utils.iter_hpv_modules(sim)

Yield each HPV disease module registered in sim, in registration order.

Identifies HPV modules by isinstance — the same convention CrossImmunity uses to discover genotype modules. The shared base for find_genotype_module / any_genotype_cancer and for products / interventions that need to scan all genotypes.

logf2

utils.logf2(x, k, x_infl, y_max=1, ttc=25)

Logistic function constrained to pass through (0,0) and (ttc,y_max). This version is derived from the 5-parameter version here: https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ Since it’s constrained to pass through 2 points, there are 3 free parameters remaining, and this verison fixes s=1 Args: k: growth rate, equivalent to b in https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ x_infl: point of inflection, equivalent to C in https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ ttc (time to cancer): x value for which the curve passes through 1. For x values beyond this, the function returns 1

logf3

utils.logf3(x, k, x_infl, s=1, y_max=1, ttc=25)

Logistic function passing through (0,0) and (ttc,y_max). This version is derived from the 5-parameter version here: https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ However, since it’s constrained to pass through 2 points, there are 3 free parameters remaining. Args: k: growth rate, equivalent to b in https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ x_infl: a location parameter, equivalent to C in https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ s: asymmetry parameter, equivalent to s in https://www.r-bloggers.com/2019/11/five-parameters-logistic-regression/ ttc (time to cancer): x value for which the curve passes through 1. For x values beyond this, the function returns 1

transform_prob

utils.transform_prob(tp, dysp)

Returns transformation probability given dysplasia Using formula for half an ellipsoid: V = 1/2 * 4/3 * pi * abc = 2 * abc = 2* dysp * (dysp/2)2, assuming that b = c = 1/2 a = 1/2 * dysp3