hpvsim.analysis module

Additional analysis functions that are not part of the core workflow, but which are useful for particular investigations.

class Analyzer(label=None)[source]

Bases: prettyobj

Base class for analyzers. Based on the Intervention class. Analyzers are used to provide more detailed information about a simulation than is available by default – for example, pulling states out of sim.people on a particular timestep before it gets updated in the next timestep.

To retrieve a particular analyzer from a sim, use sim.get_analyzer().

Parameters

label (str) – a label for the Analyzer (used for ease of identification)

initialize(sim=None)[source]

Initialize the analyzer, e.g. convert date strings to integers.

finalize(sim=None)[source]

Finalize analyzer

This method is run once as part of sim.finalize() enabling the analyzer to perform any final operations after the simulation is complete (e.g. rescaling)

apply(sim)[source]

Apply analyzer at each time point. The analyzer has full access to the sim object, and typically stores data/results in itself. This is the core method which each analyzer object needs to implement.

Parameters

sim – the Sim instance

shrink(in_place=False)[source]

Remove any excess stored data from the intervention; for use with sim.shrink().

Parameters

in_place (bool) – whether to shrink the intervention (else shrink a copy)

static reduce(analyzers, use_mean=False)[source]

Create a reduced analyzer from a list of analyzers, using

Parameters
  • analyzers – list of analyzers

  • use_mean (bool) – whether to use medians (the default) or means to create the reduced analyzer

to_json()[source]

Return JSON-compatible representation

Custom classes can’t be directly represented in JSON. This method is a one-way export to produce a JSON-compatible representation of the intervention. This method will attempt to JSONify each attribute of the intervention, skipping any that fail.

Returns

JSON-serializable representation

class snapshot(timepoints, *args, die=True, **kwargs)[source]

Bases: Analyzer

Analyzer that takes a “snapshot” of the sim.people array at specified points in time, and saves them to itself. To retrieve them, you can either access the dictionary directly, or use the get() method.

Parameters
  • timepoints (list) – list of ints/strings/date objects, the days on which to take the snapshot

  • die (bool) – whether or not to raise an exception if a date is not found (default true)

  • kwargs (dict) – passed to Analyzer

Example:

sim = hpv.Sim(analyzers=hpv.snapshot('2015.4', '2020'))
sim.run()
snapshot = sim['analyzers'][0]
people = snapshot.snapshots[0]            # Option 1
people = snapshot.snapshots['2020']       # Option 2
people = snapshot.get('2020')             # Option 3
people = snapshot.get(34)                 # Option 4
people = snapshot.get()                   # Option 5
initialize(sim)[source]
apply(sim)[source]
finalize(sim)[source]
get(key=None)[source]

Retrieve a snapshot from the given key (int, str, or date)

class age_pyramid(timepoints, edges=None, age_labels=None, datafile=None, die=False, **kwargs)[source]

Bases: Analyzer

Constructs an age/sex pyramid at specified points within the sim. Can be used with data

Parameters
  • timepoints (list) – list of ints/strings/date objects, the days on which to take the snapshot

  • die (bool) – whether or not to raise an exception if a date is not found (default true)

  • kwargs (dict) – passed to Analyzer()

Example:

sim = hpv.Sim(analyzers=hpv.age_pyramid('2015', '2020'))
sim.run()
age_pyramid = sim['analyzers'][0]
initialize(sim)[source]
apply(sim)[source]
finalize(sim)[source]
static reduce(analyzers, use_mean=False, bounds=None, quantiles=None)[source]

Create an averaged age pyramid from a list of age pyramid analyzers

plot(m_color='#4682b4', f_color='#ee7989', fig_args=None, axis_args=None, data_args=None, percentages=True, do_save=None, fig_path=None, do_show=True, **kwargs)[source]

Plot the age pyramids

Parameters
  • m_color (hex or rgb) – the color of the bars for males

  • f_color (hex or rgb) – the color of the bars for females

  • fig_args (dict) – passed to pl.figure()

  • axis_args (dict) – passed to pl.subplots_adjust()

  • data_args (dict) – ‘width’, ‘color’, and ‘offset’ arguments for the data

  • percentages (bool) – whether to plot the pyramid as percentages or numbers

  • do_save (bool) – whether to save

  • fig_path (str or filepath) – filepath to save to

  • do_show (bool) – whether to show the figure

  • kwargs (dict) – passed to hpv.options.with_style(); see that function for choices

class age_results(result_keys, die=False, **kwargs)[source]

Bases: Analyzer

Constructs results by age at specified points within the sim. Can be used with data

Parameters
  • result_keys (dict) – dictionary with keys of results to generate and associated timepoints/age-bins to generate each result as well as whether to compute_fit

  • die (bool) – whether or not to raise an exception if errors are found

  • kwargs (dict) – passed to Analyzer

Example:

sim = hpv.Sim(analyzers=hpv.age_results(
result_keys=sc.objdict(
    hpv_prevalence=sc.objdict(
        timepoints=['1990'],
        edges=np.array([0.,20.,25.,30.,40.,45.,50.,55.,65.,100.]),
    ),
    hpv_incidence=sc.objdict(
        timepoints=['1990'],
        edges=np.array([0.,20.,30.,40.,50.,60.,70.,80.,100.])
    )
)
)
sim.run()
age_results = sim['analyzers'][0]
initialize(sim)[source]
validate_results(sim)[source]
convert_rname_stocks(rname)[source]

Helper function for converting stock result names to people attributes

convert_rname_flows(rname)[source]

Helper function for converting flow result names to people attributes

apply(sim)[source]

Calculate age results

finalize(sim)[source]
static reduce(analyzers, use_mean=False, bounds=None, quantiles=None)[source]

Create an averaged age result from a list of age result analyzers

compute(key)[source]
plot(fig_args=None, axis_args=None, data_args=None, width=0.8, do_save=None, fig_path=None, do_show=True, **kwargs)[source]

Plot the age results

Parameters
  • fig_args (dict) – passed to pl.figure()

  • axis_args (dict) – passed to pl.subplots_adjust()

  • data_args (dict) – ‘width’, ‘color’, and ‘offset’ arguments for the data

  • width (float) – width of the bars

  • do_save (bool) – whether to save

  • fig_path (str or filepath) – filepath to save to

  • do_show (bool) – whether to show the figure

  • kwargs (dict) – passed to hpv.options.with_style(); see that function for choices

class age_causal_infection(start_year=None, **kwargs)[source]

Bases: Analyzer

Determine the age at which people with cervical cancer were causally infected and time spent between infection and cancer.

initialize(sim)[source]
apply(sim)[source]
class cancer_detection(symp_prob=0.01, treat_prob=0.01, product=None, **kwargs)[source]

Bases: Analyzer

Cancer detection via symptoms

Parameters
  • symp_prob – Probability of having cancer detected via symptoms, rather than screening

  • treat_prob – Probability of receiving treatment for those with symptom-detected cancer

initialize(sim)[source]
apply(sim)[source]

Check for new cancer detection, treat subset of detected cancers