fpsim.analyzers module

Specify the core analyzers available in FPsim. Other analyzers can be defined by the user by inheriting from these classes.

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

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(timesteps, *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.

Parameters:

• timesteps (list) – list of timesteps on which to take the snapshot

• args (list) – additional timestep(s)

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

• kwargs (dict) – passed to Analyzer()

Example:

sim = fp.Sim(analyzers=fps.snapshot('2020-04-04', '2020-04-14'))
sim.run()
snapshot = sim.pars['analyzers'][0]
people = snapshot.snapshots[0]

apply(sim)

Apply snapshot at each timestep listed in timesteps and save result at snapshot[str(timestep)]

class timeseries_recorder

Bases: Analyzer

Record every attribute in people as a timeseries.

self.i

The list of timesteps (ie, 0 to 261 steps).

self.t

The time elapsed in years given how many timesteps have passed (ie, 25.75 years).

self.y

The calendar year of timestep (ie, 1975.75).

self.keys

A list of people states excluding ‘dobs’.

self.data

A dictionary where self.data[state][timestep] is the mean of the state at that timestep.

Initializes self.i/t/y as empty lists and self.data as empty dictionary

initialize(sim)

Initializes self.keys from sim.people

apply(sim)

Applies recorder at each timestep

plot(x='y', fig_args=None, pl_args=None)

Plots time series of each state as a line graph

class age_pyramids(bins=None)

Bases: Analyzer

Records age pyramids for each timestep.

self.bins

A list of ages, default is a sequence from 0 to max_age + 1.

self.data

A matrix of shape (number of timesteps, number of bins - 1) containing age pyramid data.

Initializes bins and data variables

initialize(sim)

Initializes bins and data with proper shapes

apply(sim)

Records histogram of ages of all alive individuals at a timestep such that self.data[timestep] = list of proportions where index signifies age

plot()

Plots self.data as 2D pyramid plot

plot3d()

Plots self.data as 3D pyramid plot

class verbose_sim(to_csv=False, custom_csv_tables=None, to_file=False)

Bases: Analyzer

Initializes a verbose_sim analyzer which extends the logging functionality of the sim with calculated channels, total state results of a sim run, the story() feature, and configurable file formatting for results

apply(sim)

Logs data for total_results and events at each timestep.

Output:

self.total_results::dict

Dictionary of all individual results formatted as {timestep: attribute: [values]} keys correspond to fpsim.defaults debug_states

self.events::dict

Dictionary of events correponding to self.channels formatted as {timestep: channel: [indices]}.

save(to_csv=True, to_json=False, custom_csv_tables=None)

At the end of sim run, stores total_results as either a json or feather file.

Inputs

self.to_csv::bool

If True, writes results to csv files in /sim_output where each state’s history is a separate file

self.to_json::bool

If True, writes results to json file

custom_csv_tables::list

List of states that the user wants to write to csv, default is all

Outputs:

Either a json file at “sim_output/total_results.json” or a csv file for each state at “sim_output/{state}_state.csv”

story(index, output=False, debug=False)

Prints a story of all major events in an individual’s life based on calculated verbose_sim channels, base Sim channels, and statistics calculated within the function such as year of birth of individual.

Parameters:

• index (int) – index of the individual, must be less than population

• output (bool) – return as output string rather than print

• debug (bool) – print additional information

Outputs:

printed display of each major event in the individual’s life