analyzers
Specify the core analyzers available in FPsim. Other analyzers can be defined by the user by inheriting from these classes.
Classes
| Name | Description |
|---|---|
| age_pyramids | Records age pyramids for each timestep. |
| cpr_by_age | Analyzer that records the contraceptive prevalence rate (CPR) by age at each timestep. |
| education_recorder | Analyzer records all education attributes of females + pregnancy + living status |
| lifeof_recorder | Analyzer records sexual and reproductive history, and contraceptions |
| method_mix_by_age | Record the method mix by age at the end of the simulation. |
| method_mix_over_time | Track the number of women on each method at every timestep. |
| snapshot | Analyzer that takes a “snapshot” of the sim.people array at specified points |
| state_tracker | Record the number of living women in a given boolean state each timestep. |
| track_as | Record age-specific versions of the standard results. |
age_pyramids
analyzers.age_pyramids(bins=None)Records age pyramids for each timestep.
Attributes:
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.Methods
| Name | Description |
|---|---|
| init_pre | Initializes bins and data with proper shapes. |
| plot | Plots self.data as 2D pyramid plot |
| plot3d | Plots self.data as 3D pyramid plot |
| step | Records histogram of ages of all alive individuals at a timestep such that |
init_pre
analyzers.age_pyramids.init_pre(sim, force=False)Initializes bins and data with proper shapes.
plot
analyzers.age_pyramids.plot()Plots self.data as 2D pyramid plot
plot3d
analyzers.age_pyramids.plot3d()Plots self.data as 3D pyramid plot
step
analyzers.age_pyramids.step()Records histogram of ages of all alive individuals at a timestep such that self.data[timestep] = list of proportions where index signifies age
cpr_by_age
analyzers.cpr_by_age(**kwargs)Analyzer that records the contraceptive prevalence rate (CPR) by age at each timestep.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kwargs | dict | passed to Analyzer() | {} |
Example::
sim = fp.Sim(analyzers=fps.cpr_by_age())
sim.run()
final_cpr = sim.analyzers.cpr_by_age.results['total'][-1]education_recorder
analyzers.education_recorder(**kwargs)Analyzer records all education attributes of females + pregnancy + living status for all timesteps. Made for debugging purposes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| args | list | additional timestep(s) | required |
| kwargs | dict | passed to Analyzer() | {} |
Methods
| Name | Description |
|---|---|
| finalize | Process data in snapshots so we can plot it easily |
| plot | Plots time series of each state as a line graph |
| plot_waterfall | Plot a waterfall plot showing the evolution of education objective and attainment over time |
| step | Apply snapshot at each timestep listed in timesteps and |
finalize
analyzers.education_recorder.finalize(sim=None)Process data in snapshots so we can plot it easily
plot
analyzers.education_recorder.plot(index=0, fig_args=None, pl_args=None)Plots time series of each state as a line graph Args: index: index of the female individual, must be less the analyzer’s max_pop_size
plot_waterfall
analyzers.education_recorder.plot_waterfall(
max_timepoints=30,
min_age=18,
max_age=40,
fig_args=None,
pl_args=None,
)Plot a waterfall plot showing the evolution of education objective and attainment over time for a specified age group.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| max_timepoints | int | The maximum number of timepoints to plot, defaults to 30. | 30 |
| min_age | int | The minimum age for the age group, defaults to 18. | 18 |
| max_age | int | The maximum age for the age group, defaults to 40. | 40 |
Returns
| Name | Type | Description |
|---|---|---|
| figure handle |
The function generates uses kernel density estimation to visualize the data. If there’s not data for the min max age specified, for a specific time step (ie, there are no agents in that age group), it adds a textbox. This is an edge case that can happen for a simulation with very few agents, and a very narrow age group.
step
analyzers.education_recorder.step()Apply snapshot at each timestep listed in timesteps and save result at snapshot[str(timestep)]
lifeof_recorder
analyzers.lifeof_recorder(**kwargs)Analyzer records sexual and reproductive history, and contraceptions females, plus age and living status for all timesteps. Made for debugging purposes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| args | list | additional timestep(s) | required |
| kwargs | dict | passed to Analyzer() | {} |
Methods
| Name | Description |
|---|---|
| finalize | Process data in snapshots so we can plot it easily |
| plot | Plots time series of each state as a line graph |
| step | Apply snapshot at each timestep listed in timesteps and |
finalize
analyzers.lifeof_recorder.finalize(sim=None)Process data in snapshots so we can plot it easily
plot
analyzers.lifeof_recorder.plot(index=0, fig_args=None, pl_args=None)Plots time series of each state as a line graph Args: index: index of the female individual, must be less the analyzer’s max_pop_size
step
analyzers.lifeof_recorder.step()Apply snapshot at each timestep listed in timesteps and save result at snapshot[str(timestep)]
method_mix_by_age
analyzers.method_mix_by_age(**kwargs)Record the method mix by age at the end of the simulation.
Produces a single end-of-run snapshot, so use it to compare method mix across age groups against survey data. For a time series instead, use method_mix_over_time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kwargs | dict | passed to ss.Analyzer |
{} |
Example:
```python
import fpsim as fp
sim = fp.Sim(location='kenya', analyzers=fp.method_mix_by_age())
sim.run()
mix = sim.analyzers[0]
```method_mix_over_time
analyzers.method_mix_over_time(**kwargs)Track the number of women on each method at every timestep.
Use this to see how method mix evolves, for example after introducing a new method with add_method. For an end-of-run snapshot by age instead, use method_mix_by_age.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kwargs | dict | passed to ss.Analyzer |
{} |
Example:
```python
import fpsim as fp
sim = fp.Sim(location='kenya', analyzers=fp.method_mix_over_time())
sim.run()
sim.analyzers[0].plot()
```Methods
| Name | Description |
|---|---|
| plot | Plot method mix over time |
plot
analyzers.method_mix_over_time.plot(
style=None,
share=False,
methods=None,
stacked=False,
)Plot method mix over time
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| style | str | plotting style | None |
| share | bool | if True, plot share (%) instead of absolute numbers | False |
| methods | list | list of method names to plot; if None, plots all methods | None |
| stacked | bool | if True, create a stacked area plot | False |
snapshot
analyzers.snapshot(timesteps, *args, die=True, **kwargs)Analyzer that takes a “snapshot” of the sim.people array at specified points in time, and saves them to itself.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| timesteps | list | list of timesteps on which to take the snapshot | required |
| args | list | additional timestep(s) | () |
| 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 = fp.Sim(analyzers=fps.snapshot('2020-04-04', '2020-04-14'))
sim.run()
snapshot = sim.pars['analyzers'][0]
people = snapshot.snapshots[0]Methods
| Name | Description |
|---|---|
| step | Apply snapshot at each timestep listed in timesteps and |
step
analyzers.snapshot.step()Apply snapshot at each timestep listed in timesteps and save result at snapshot[str(timestep)]
state_tracker
analyzers.state_tracker(
state_name=None,
module_name=None,
min_age=fpd.min_age,
max_age=fpd.max_age,
**kwargs,
)Record the number of living women in a given boolean state each timestep.
Use this to track any boolean state without writing a custom analyzer, for example how many women live in urban settings or are currently postpartum.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| state_name | str | name of the boolean state to track, e.g. 'urban' |
None |
| module_name | str | module the state belongs to, e.g. 'fp'; omit for states on People |
None |
| min_age | float | youngest age to include | fpd.min_age |
| max_age | float | oldest age to include | fpd.max_age |
| kwargs | dict | passed to ss.Analyzer |
{} |
Example:
```python
import fpsim as fp
tracker = fp.state_tracker(state_name='urban') # urban is a People state
sim = fp.Sim(location='kenya', analyzers=tracker)
sim.run()
```Methods
| Name | Description |
|---|---|
| init_post | Initializes bins and data with proper shapes |
| plot | Plots self.data as a line |
| step | Records histogram of ages of all alive individuals at a timestep such that |
init_post
analyzers.state_tracker.init_post()Initializes bins and data with proper shapes
plot
analyzers.state_tracker.plot(style=None)Plots self.data as a line
step
analyzers.state_tracker.step()Records histogram of ages of all alive individuals at a timestep such that self.data[timestep] = list of proportions where index signifies age
track_as
analyzers.track_as()Record age-specific versions of the standard results.
Adds age stratification to results that are otherwise reported for the whole population, such as fertility and contraceptive use.
Note
This analyzer assigns a plain dict to self.results, which Starsim 3.6.0 locks, so it currently raises AttributeError on init. It needs porting to ss.Results.
Methods
| Name | Description |
|---|---|
| log_age_split | Method called if age-specific results are being tracked. Separates results by age. |
| step | Apply the analyzer |
log_age_split
analyzers.track_as.log_age_split(
binned_ages_t,
channel,
numerators,
denominators=None,
)Method called if age-specific results are being tracked. Separates results by age.
step
analyzers.track_as.step()Apply the analyzer Note: much of the logic won’t work because the sim doesn’t record the time at which events occur (!), so attributes like ppl.ti_pregnant won’t exist. These are all slated to be added as part of the V3 refactor. For now, this is a placeholder.