analysis

analysis

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

Classes

Name	Description
Analyzer	Base class for analyzers. Based on the Intervention class. Analyzers are used
age_causal_infection	Determine the age at which people with cervical cancer were causally infected and
age_pyramid	Constructs an age/sex pyramid at specified points within the sim. Can be used with data
age_results	Constructs results by age at specified points within the sim. Can be used with data
dalys	Analyzer for computing DALYs.
snapshot	Analyzer that takes a “snapshot” of the sim.people array at specified points

Analyzer

analysis.Analyzer(label=None)

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

Name	Type	Description	Default
label	str	a label for the Analyzer (used for ease of identification)	None

Methods

Name	Description
apply	Apply analyzer at each time point. The analyzer has full access to the
finalize	Finalize analyzer
initialize	Initialize the analyzer, e.g. convert date strings to integers.
reduce	Create a reduced analyzer from a list of analyzers, using
shrink	Remove any excess stored data from the intervention; for use with sim.shrink().
to_json	Return JSON-compatible representation

apply

analysis.Analyzer.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

Name	Type	Description	Default
sim		the Sim instance	required

finalize

analysis.Analyzer.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)

initialize

analysis.Analyzer.initialize(sim=None)

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

reduce

analysis.Analyzer.reduce(analyzers, use_mean=False)

Create a reduced analyzer from a list of analyzers, using

Parameters

Name	Type	Description	Default
analyzers		list of analyzers	required
use_mean	bool	whether to use medians (the default) or means to create the reduced analyzer	False

shrink

analysis.Analyzer.shrink(in_place=False)

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

Parameters

Name	Type	Description	Default
in_place	bool	whether to shrink the intervention (else shrink a copy)	False

to_json

analysis.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

Name	Type	Description
		JSON-serializable representation

age_causal_infection

analysis.age_causal_infection(start_year=None, **kwargs)

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

Methods

Name	Description
finalize	Convert things to arrays

finalize

analysis.age_causal_infection.finalize(sim=None)

Convert things to arrays

age_pyramid

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

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

Parameters

Name	Type	Description	Default
timepoints	list	list of ints/strings/date objects, the days on which to take the snapshot	None
die	bool	whether or not to raise an exception if a date is not found (default true)	False
kwargs	dict	passed to Analyzer()	{}

Example::

sim = hpv.Sim(analyzers=hpv.age_pyramid('2015', '2020'))
sim.run()
age_pyramid = sim['analyzers'][0]

Methods

Name	Description
plot	Plot the age pyramids
reduce	Create an averaged age pyramid from a list of age pyramid analyzers

plot

analysis.age_pyramid.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

Name	Type	Description	Default
m_color	hex or rgb	the color of the bars for males	'#4682b4'
f_color	hex or rgb	the color of the bars for females	'#ee7989'
fig_args	dict	passed to pl.figure()	None
axis_args	dict	passed to pl.subplots_adjust()	None
data_args	dict	‘width’, ‘color’, and ‘offset’ arguments for the data	None
percentages	bool	whether to plot the pyramid as percentages or numbers	True
do_save	bool	whether to save	None
fig_path	str or filepath	filepath to save to	None
do_show	bool	whether to show the figure	True
kwargs	dict	passed to hpv.options.with_style(); see that function for choices	{}

reduce

analysis.age_pyramid.reduce(
    analyzers,
    use_mean=False,
    bounds=None,
    quantiles=None,
)

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

age_results

analysis.age_results(result_args=None, die=False, **kwargs)

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

Parameters

Name	Type	Description	Default
result_args	dict	dict of results to generate and associated years/age-bins to generate each result as well as whether to compute_fit	None
die	bool	whether or not to raise an exception if errors are found	False
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]

Methods

Name	Description
apply	Calculate age results
compute_mismatch	Compute mismatch between analyzer results and datafile
convert_rname_flows	Helper function for converting flow result names to people attributes
convert_rname_stocks	Helper function for converting stock result names to people attributes
get_to_plot	Get number of plots to make
plot	Plot the age results
plot_single	Function to plot a single age result for a single date. Requires an axis as
reduce	Create an averaged age result from a list of age result analyzers
validate_variables	Check that the variables in result_args are valid, and initialize the result structure

apply

analysis.age_results.apply(sim)

Calculate age results

compute_mismatch

analysis.age_results.compute_mismatch(key)

Compute mismatch between analyzer results and datafile

convert_rname_flows

analysis.age_results.convert_rname_flows(rname)

Helper function for converting flow result names to people attributes

convert_rname_stocks

analysis.age_results.convert_rname_stocks(rname)

Helper function for converting stock result names to people attributes

get_to_plot

analysis.age_results.get_to_plot()

Get number of plots to make

plot

analysis.age_results.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

Name	Type	Description	Default
fig_args	dict	passed to pl.figure()	None
axis_args	dict	passed to pl.subplots_adjust()	None
plot_args	dict	passed to plot_single	None
scatter_args	dict	passed to plot_single	None
do_save	bool	whether to save	None
fig_path	str or filepath	filepath to save to	None
do_show	bool	whether to show the figure	True
kwargs	dict	passed to hpv.options.with_style(); see that function for choices	{}

plot_single

analysis.age_results.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.

reduce

analysis.age_results.reduce(
    analyzers,
    use_mean=False,
    bounds=None,
    quantiles=None,
)

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

validate_variables

analysis.age_results.validate_variables(sim)

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

dalys

analysis.dalys(start=None, life_expectancy=84, *args, **kwargs)

Analyzer for computing DALYs.

Attributes

Name	Description
av_disutility	The average disability weight over duration of cancer

snapshot

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

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

Name	Type	Description	Default
timepoints	list	list of ints/strings/date objects, the days on which to take the snapshot	None
die	bool	whether or not to raise an exception if a date is not found (default true)	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

Methods

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

get

analysis.snapshot.get(key=None)

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