Results Manager

class vivarium.engine.framework.results.manager.ResultsManager[source]

Backend manager object for the results management system.

This class contains the public methods used by the ResultsInterface to register stratifications and observations as well as the get_results method used to retrieve formatted results by the ResultsContext.

CONFIGURATION_DEFAULTS: dict[str, Any] = {'stratification': {'default': [], 'excluded_categories': {}}}: A dictionary containing the defaults for any configurations managed by this manager. An empty dictionary indicates no managed configurations.

property name: str

get_results()[source]

Gets the measure-specific formatted results in a dictionary.

Return type:: dict[str, DataFrame]
Returns:: A dictionary of measure-specific formatted results. The keys are the measure names and the values are the respective results.

setup(builder)[source]

Sets up the results manager.

Return type:: None
Parameters:: builder (Builder)

on_post_setup(_)[source]

Sets stratifications on observations and initializes results for each measure.

Return type:: None
Parameters:: _ (Event)

on_time_step_prepare(event)[source]

Defines the listener callable for the time_step__prepare phase.

Return type:: None
Parameters:: event (Event)

on_time_step(event)[source]

Defines the listener callable for the time_step phase.

Return type:: None
Parameters:: event (Event)

on_time_step_cleanup(event)[source]

Defines the listener callable for the time_step__cleanup phase.

Return type:: None
Parameters:: event (Event)

on_collect_metrics(event)[source]

Defines the listener callable for the collect_metrics phase.

Return type:: None
Parameters:: event (Event)

gather_results(event)[source]

Updates existing results with any new results.

Return type:: None
Parameters:: event (Event)

set_default_stratifications(builder)[source]

Sets the default stratifications for the results context.

This passes the default stratifications from the configuration to the ResultsContext set_default_stratifications() method to be set.

Return type:: None
Parameters:: builder (Builder) – The builder object for the simulation.

register_stratification(name, categories, excluded_categories, mapper, is_vectorized, requires_attributes=[])[source]

Registers a stratification that can be used by stratified observations.

Adds a stratification to the ResultsContext as well as the stratification’s required resources to this manager.

Return type:

None

Parameters:

name (str) – Name of the stratification.
categories (list[str]) – Exhaustive list of all possible stratification values.
excluded_categories (list[str] | None) – List of possible stratification values to exclude from results processing. If None (the default), will use exclusions as defined in the configuration.
mapper (Callable[[DataFrame], Series] | Callable[[Series], str] | None) – A callable that maps population attributes specified by the requires_attributes argument to the stratification categories. It can either map the entire population or an individual simulant. A simulation will fail if the mapper ever produces an invalid value.
is_vectorized (bool) – True if the mapper function will map the entire population, and False if it will only map a single simulant.
requires_attributes (list[str]) – A list of the state table columns that are required by the mapper to produce the stratification.

register_binned_stratification(target, binned_column, bin_edges, labels, excluded_categories, **cut_kwargs)[source]

Registers a continuous target quantity to observe into bins in a binned_column.

Return type:

None

Parameters:

target (str) – Name of population attribute to be binned.
binned_column (str) – Name of the (binned) stratification.
bin_edges (Sequence[int | float]) – List of scalars defining the bin edges, passed to :meth: pandas.cut. The length must be equal to the length of labels plus 1.
labels (list[str]) – List of string labels for bins. The length must be equal to the length of bin_edges minus 1.
excluded_categories (list[str] | None) – List of possible stratification values to exclude from results processing. If None (the default), will use exclusions as defined in the configuration.
**cut_kwargs (int | str | bool) – Keyword arguments for :meth: pandas.cut.

register_observation(observation_type, name, population_filter, when, requires_attributes, **kwargs)[source]

Registers an observation to the results system.

Return type:

None

Parameters:

observation_type (type[Observation]) – Specific class type of observation to register.
name (str) – Name of the observation. It will also be the name of the output results file for this particular observation.
population_filter (PopulationFilter) – A named tuple of population filtering details. The first item is a Pandas query string to filter the population down to the simulants who should be considered for the observation. The second item is a boolean indicating whether to include untracked simulants from the observation.
when (str) – Name of the lifecycle phase the observation should happen. Valid values are: “time_step__prepare”, “time_step”, “time_step__cleanup”, or “collect_metrics”.
requires_attributes (list[str]) – The population attributes that are required to compute the observation.
**kwargs (Any) – Additional keyword arguments to be passed to the observation’s constructor.