monitors
Define “passive” observation methods that do not interfere with the course of a disease or with a simulation.
These classes are derived from starsim’s Analyzers anyway because they need to be executed in a specific part of the simulation workflow.
This module exists to emphasize a functional distinction between classes that only subsamples and/or aggregates simulated data (monitors), and classes that can optionally take as input empirical data and perform additional calculations and be used as “components” or “steps” in an optimization process.
Classes
| Name | Description |
|---|---|
| histogram_by_vaccination_status | This class exist to avoid slowing down the parent class if there are no |
| histograms_by_age_sex_monitor | A class used to record statistics (counts) by age and sex for each timestep, |
| states_consistency_monitor | Analyzer to track everything – use for debug purposes |
| track_individuals_monitor | A class used to record a certain state of a group of agents at each time |
histogram_by_vaccination_status
monitors.histogram_by_vaccination_status(track_vaccinated=True, **kwargs)This class exist to avoid slowing down the parent class if there are no vaccination interventions.
histograms_by_age_sex_monitor
monitors.histograms_by_age_sex_monitor(
age_bins=None,
age_bin_labels=None,
to_record=None,
record_from=None,
record_until=None,
aggregate_sex=False,
aggregate_time=None,
scaling=1.0,
resampling_period=None,
name=None,
)A class used to record statistics (counts) by age and sex for each timestep, or a user-defined sampling period.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| age_bins | list | The bins to use for age. Defaults to None. |
None |
| age_bin_labels | list | Labels for the age bins. Defaults to None. |
None |
| to_record | dict | nested dictionary with the path to the quantity to record: For instance: dict(ti_acute=dict(path=(“diseases”, “typhoid”), label=“cases”)) If None (default), it records the main states of typhoid, both new cases in a given time step, and total number of people in that state at each timestep. | None |
| record_from | float | Time to start recording from, assumes it’s time expressed in years in float representation. If None, it records from the start of the simulation. | None |
| record_until | int | Time until which to record. Assumes it’s time expressed in years in float representation. If None, it records until the end of the simulation. The monitor records on semiopen interval [record_from, record_until), such that if we had two monitors, A: [record_from_a, record_until_a), and B: [record_from_b, record_until_b), and record_until_a == record_from_b, then that time point would not be counted twice. | None |
| aggregate_sex | bool | Whether to record each quantity separetely by sex. Defaults to False, ie, records the quantities in to_record separately for females and males. |
False |
| aggregate_time | str | If the monitor downsamples results with respect to the original simulation resoliution, tell the monitor how to downsample. Options are “subsample”, “mean”, “median”, “min”, “max”, “sum”. | None |
| resampling_period | float | New sampling period of the output/results of this monitor. | None |
| scaling | float | Scaling factor for adjusting the counts. Defaults to 1.0. This is a crude way to scale down counts to mimic imperfect observation/reporting processes such as testing. | 1.0 |
| name | str | The name of the monitor. Defaults to None. |
None |
Note
Scaling factor value example: 0.6 * 0.75 * reporting_rate (emod parameter) is used for 60% blood culture sensitivity and 75% healthcare seeking in Pakistan simulations with EMOD. By default, scaling=1.0, as if we had perfect sampling of the whole population.
Methods
| Name | Description |
|---|---|
| plot | Plot all results in the Sim object after the simulation has run |
| plot_waterfall | Plot a waterfall plot showing the evolution of the distribution of |
| set_observation_interval | Set the correction endpoints of the observation period recorded by this monitor |
| to_df | Transform results to a pandas dataframe |
plot
monitors.histograms_by_age_sex_monitor.plot(
key=None,
t_index=None,
fig=None,
style='fancy',
fig_kw=None,
plot_kw=None,
)Plot all results in the Sim object after the simulation has run
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str | the results key to plot (by default, all) | None |
| t_index | int | the time index in the monitor’s timevec vector | None |
| fig | Figure |
if provided, plot results into an existing figure | None |
| style | str | the plotting style to use (default “fancy”; other options are “simple”, None, or any Matplotlib style) | 'fancy' |
| fig_kw | dict | passed to plt.subplots() |
None |
| plot_kw | dict | passed to plt.plot() |
None |
plot_waterfall
monitors.histograms_by_age_sex_monitor.plot_waterfall(
key=None,
max_timepoints=16,
fig=None,
style='fancy',
fig_kw=None,
plot_kw=None,
)Plot a waterfall plot showing the evolution of the distribution of a given metric (ie, number of new acute cases) with respect to age.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str | the results key to plot (by default, all) | None |
| max_timepoints | int | The maximum number of timepoints to plot, defaults to 16. | 16 |
| fig | Figure |
if provided, plot results into an existing figure | None |
| style | str | the plotting style to use (default “fancy”; other options are “simple”, None, or any Matplotlib style) | 'fancy' |
| fig_kw | dict | passed to plt.subplots() |
None |
| plot_kw | dict | passed to plt.plot() |
None |
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.
set_observation_interval
monitors.histograms_by_age_sex_monitor.set_observation_interval(sim)Set the correction endpoints of the observation period recorded by this monitor
to_df
monitors.histograms_by_age_sex_monitor.to_df()Transform results to a pandas dataframe
states_consistency_monitor
monitors.states_consistency_monitor(*args, **kwargs)Analyzer to track everything – use for debug purposes
Methods
| Name | Description |
|---|---|
| step | Checks states that should be mutually exlusive and collectively exhaustive |
step
monitors.states_consistency_monitor.step()Checks states that should be mutually exlusive and collectively exhaustive
track_individuals_monitor
monitors.track_individuals_monitor(
to_record=None,
eligibility=None,
eligibility_kwargs=None,
name=None,
**kwargs,
)A class used to record a certain state of a group of agents at each time step. This monitor is meant to be used for debugging purposes and with a population that does not change size, though agents could age.
Methods
| Name | Description |
|---|---|
| plot_ridge | Plot each individual’s timeseries of the given state. |
plot_ridge
monitors.track_individuals_monitor.plot_ridge(
uids=None,
num_agents=32,
key=None,
y_scaling=1.0,
style='fancy',
fig_kw=None,
plot_kw=None,
)Plot each individual’s timeseries of the given state. Individual traces are vertically stacked.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str | the results key to plot (by default, all, and can be a lot of figs, be warned) | None |
| max_timepoints | int | The maximum number of timepoints to plot, defaults to 16. | required |
| style | str | the plotting style to use (default “fancy”; other options are “simple”, None, or any Matplotlib style) | 'fancy' |
| fig_kw | dict | passed to plt.subplots() |
None |
| plot_kw | dict | passed to plt.plot() |
None |
Returns
| Name | Type | Description |
|---|---|---|
| a list of figures |