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)

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)

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

finalize(sim=None)

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)

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)

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)

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()

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=None, *args, die=True, **kwargs)

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)

apply(sim)

finalize(sim)

get(key=None)

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

class age_pyramid(timepoints=None, *args, edges=None, age_labels=None, datafile=None, die=False, **kwargs)

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)

apply(sim)

finalize(sim)

static reduce(analyzers, use_mean=False, bounds=None, quantiles=None)

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)

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_args=None, die=False, **kwargs)

Bases: Analyzer

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

Parameters:

• result_args (dict) – dict of results to generate and associated years/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:

result_args=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, 2000],
        edges=np.array([0.,20.,30.,40.,50.,60.,70.,80.,100.])
    )
sim = hpv.Sim(analyzers=hpv.age_results(result_args=result_args))
sim.run()
age_results = sim['analyzers'][0]

initialize(sim)

validate_variables(sim)

Check that the variables in result_args are valid, and initialize the result structure

convert_rname_stocks(rname)

Helper function for converting stock result names to people attributes

convert_rname_flows(rname)

Helper function for converting flow result names to people attributes

apply(sim)

Calculate age results

finalize(sim)

static reduce(analyzers, use_mean=False, bounds=None, quantiles=None)

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

compute_mismatch(key)

Compute mismatch between analyzer results and datafile

get_to_plot()

Get number of plots to make

plot_single(ax, rkey, date, by_genotype, plot_args=None, scatter_args=None)

Function to plot a single age result for a single date. Requires an axis as input and will generally be called by a helper function rather than directly.

plot(fig_args=None, axis_args=None, plot_args=None, scatter_args=None, do_save=None, fig_path=None, do_show=True, fig=None, ax=None, **kwargs)

Plot the age results

Parameters:

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

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

• plot_args (dict) – passed to plot_single

• scatter_args (dict) – passed to plot_single

• 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)

Bases: Analyzer

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

initialize(sim)

apply(sim)

finalize(sim=None)

Convert things to arrays

class cancer_detection(symp_prob=0.01, treat_prob=0.01, product=None, **kwargs)

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)

apply(sim)

Check for new cancer detection, treat subset of detected cancers

class daly_computation(start, **kwargs)

Bases: Analyzer

Analyzer for computing DALYs.

Produces a dataframe by year storing:

• Cases/deaths: number of new cancer cases and cancer deaths

• Average age of new cases, average age of deaths, average age of noncancer death

initialize(sim)

apply(sim)

finalize(sim)