analyzers

analyzers

HPVsim analyzers built on starsim’s ss.Analyzer.

Classes

Name	Description
age_causal_infection	Age at causal infection / CIN2+ / cancer, and dwell times, per cancer.
age_pyramid	Age/sex pyramid (scale-weighted histograms) at requested timepoints.
by_age	Age-binned per-timestep results, stored as `ss.Result` per (key, bin).
dalys	Incidence-based DALYs (YLL + YLD) from cervical cancer, by calendar year.
snapshot	Deep-copy `sim.people` at requested timepoints.

age_causal_infection

analyzers.age_causal_infection(start=None, **kwargs)

Age at causal infection / CIN2+ / cancer, and dwell times, per cancer.

For each cervical-cancer DETECTION, back-traces to the age at the causal (current persistent) HPV infection and at CIN2+, and records the dwell times precin (causal->CIN), cin (CIN->cancer detection), and total. This matches the 'cancers' fitting target — dwell times therefore include the dur_undetected lag between biological cancer onset and clinical recognition. Reads live agents on the standard code path: on the grow multiscale engine, extra cancers are real fine agents in sim.people (fine=True, scale=1/ratio), so every cancer is captured at any ms_agent_ratio and weighted by people.scale.

Parameters

Name	Type	Description	Default
start		ss.date-coercible; only count cancers at/after this date. Defaults to sim start.	`None`

Methods

Name	Description
plot	Plot age-at-causal/CIN/cancer histograms (see plotting.plot_age_causal_infection).

plot

analyzers.age_causal_infection.plot(fig=None)

Plot age-at-causal/CIN/cancer histograms (see plotting.plot_age_causal_infection).

age_pyramid

analyzers.age_pyramid(
    timepoints=None,
    edges=None,
    age_labels=None,
    datafile=None,
    die=False,
    **kwargs,
)

Age/sex pyramid (scale-weighted histograms) at requested timepoints.

Parameters

Name	Type	Description	Default
timepoints		ss.date-coercible scalar/list; defaults to sim end.	`None`
edges		age bin edges; defaults to `np.linspace(0, 100, 11)`.	`None`
age_labels		optional bin labels; auto-generated if omitted.	`None`
datafile		optional path/dataframe of observed data (stored on `self.data` for the later plotting layer; not plotted here).	`None`
die	bool	raise if a requested timepoint is past the sim end (otherwise it is skipped).	`False`

Output: self.age_pyramids is an sc.odict keyed by ss.date, each value an (nbins, 2) array with columns [male, female].

Methods

Name	Description
plot	Plot this age pyramid (see hpvsim.plotting.plot_age_pyramid).
to_dataframe	Tidy long-form (date, age_bin, sex, count).

plot

analyzers.age_pyramid.plot(date=None, fig=None)

Plot this age pyramid (see hpvsim.plotting.plot_age_pyramid).

to_dataframe

analyzers.age_pyramid.to_dataframe()

Tidy long-form (date, age_bin, sex, count).

by_age

analyzers.by_age(keys=None, years=None, edges=None, **kwargs)

Age-binned per-timestep results, stored as ss.Result per (key, bin).

Records per-timestep age-binned outputs as one 1D ss.Result per age bin (e.g. cancers_20_25, cancers_25_30, …). This lets starsim’s finalize_results handle pop_scale multiplication automatically for count-shaped results (scale=True), and lets each per-bin timeseries be annualized via ss.Result.annualize().

Supported keys:

count (scale=True, annualize mean): n_cancerous, n_cin, n_precin, n_infected, hpv
demographic denominators (scale=True, annualize mean): n_alive, n_females, n_males
annual event flows (scale=True, annualize sum): cancers, cins
prevalences (scale=False, annualize mean, ratio in [0, 1]): hpv_prevalence, cin_prevalence, cancer_prevalence, precin_prevalence

After the sim runs, convenience 2D arrays are populated on the analyzer: self.cancers has shape (npts, n_bins), self.hpv_prevalence likewise. to_dataframe(key) annualizes and returns a DataFrame indexed by year with age-bin columns.

Parameters

Name	Description	Default
keys	result key (`'cancers'`) or list of keys.	`None`
years	reporting-only filter for `to_dataframe`. Storage is always per-timestep so `ss.Result.annualize` can be applied. Scalar or list of ints. Default None -> all sim years.	`None`
edges	age bin edges. Default `np.arange(0, 101, 5)`.	`None`

Example::

ar = hpv.by_age('cancers', years=2020)
sim = hpv.Sim(location='nigeria', analyzers=[ar])
sim.run()
df = ar.to_dataframe('cancers')          # year x age-bin df
arr = ar.cancers                         # 2D (npts, n_bins)
sim.results.by_age.cancers_20_25         # 1D ss.Result

Methods

Name	Description
to_dataframe	Annualize per-bin Results and return a year x age-bin DataFrame.

to_dataframe

analyzers.by_age.to_dataframe(key)

Annualize per-bin Results and return a year x age-bin DataFrame.

Method per key type: FLOW keys (cancers, cins) sum across the calendar year; COUNT and PREV keys average. When years= was supplied at construction, only those years are returned.

dalys

analyzers.dalys(
    start=None,
    life_expectancy=84,
    disability_weights=None,
    **kwargs,
)

Incidence-based DALYs (YLL + YLD) from cervical cancer, by calendar year.

YLL and YLD are attributed at the year of cancer onset (incidence-based), weighted by people.scale and multiplied by sim.pars.pop_scale at finalize so the emitted arrays are in real-population units. Reads live agents on the standard code path: on the grow multiscale engine, extra cancers are real fine agents (scale=1/ratio) in sim.people, so all onsets are captured at any ms_agent_ratio.

Parameters

Name	Description	Default
start	ss.date-coercible; only count onsets at/after this year.	`None`
life_expectancy	reference life expectancy for YLL (default 84; pass a country-specific value where available).	`84`
disability_weights	objdict/dict with `weights` and `time_fraction` lists (one entry per cancer stage). Defaults to GBD2017; pass your own to use different disability weights.	`None`

Methods

Name	Description
plot	Plot stacked YLL/YLD over time (see plotting.plot_dalys).

plot

analyzers.dalys.plot(fig=None)

Plot stacked YLL/YLD over time (see plotting.plot_dalys).

snapshot

analyzers.snapshot(timepoints=None, die=True, **kwargs)

Deep-copy sim.people at requested timepoints.

Parameters

Name	Type	Description	Default
timepoints		ss.date-coercible scalar/list (year ints, floats, strings, or ss.date). Defaults to the sim end date.	`None`
die	bool	raise if a requested timepoint is past the sim end.	`True`

Example::

snap = hpv.snapshot(timepoints=['2015', 2020])
sim = hpv.Sim(analyzers=[snap]); sim.run()
people_2020 = sim.analyzers['snapshot'].get(2020)

Methods

Name	Description
get	Retrieve a snapshot by ss.date-coercible key (nearest match).

get

analyzers.snapshot.get(key=None)

Retrieve a snapshot by ss.date-coercible key (nearest match).

If key is None, returns the first recorded snapshot.

Functions

Name	Description
results_by_genotype	Stack a per-genotype HPV result into a year-indexed DataFrame.

results_by_genotype

analyzers.results_by_genotype(sim, key='cum_cancers', normalize=False)

Stack a per-genotype HPV result into a year-indexed DataFrame.

Columns are genotype names; index is sim.timevec.years. With normalize=True, each row is divided by its total (genotype distribution of key), leaving all-zero rows as zeros.

Parameters

Name	Type	Description	Default
sim		a run hpv.Sim.	required
key		a result name present on each HPV module (e.g. ‘cum_cancers’, ‘new_cancers’, ‘cum_cancer_deaths’).	`'cum_cancers'`
normalize	bool	row-normalize to a distribution.	`False`