Results Context

class vivarium.engine.framework.results.context.ResultsContext[source]

Manager for organizing observations and their required stratifications.

This context object is wholly contained by ResultsManager. Stratifications and observations can be added to the context through the manager via the add_stratification and register_observation methods, respectively.

default_stratifications: List of column names to use for stratifying results.

stratifications: List of Stratification objects to be applied to results.

excluded_categories: Dictionary of possible per-metric stratification values to be excluded from results processing.

observations: Dictionary of Observation objects to be produced keyed by the observation name.

grouped_observations: Dictionary of observation details. It is of the format {lifecycle_state: {PopulationFilter: {stratifications: list[Observation]}}}. Allowable lifecycle_states are “time_step__prepare”, “time_step”, “time_step__cleanup”, and “collect_metrics”.

logger: Logger for the results context.

property name: str

setup(builder)[source]

Sets up the results context.

This method is called by the ResultsManager during the setup phase of that object.

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

set_default_stratifications(default_grouping_columns)[source]

Sets the default stratifications to be used by stratified observations.

Return type:: None
Parameters:: default_grouping_columns (list[str]) – List of stratifications to be used.
Raises:: ResultsConfigurationError – If the self.default_stratifications attribute has already been set.

set_stratifications()[source]

Sets stratifications on all Observers.

Emits a warning if any registered stratifications are not being used by any observation.

Return type:: None

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

Adds a stratification to the results context.

Return type:

None

Parameters:

name (str) – Name of the stratification.
requires_attributes (list[str]) – The population attributes needed as input for the mapper.
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 the population attributes specified by requires_attributes 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.

Raises:

ValueError –

If the stratification name is already used. - If there are duplicate categories. - If any excluded_categories are not in categories.

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

Adds an observation to the results context.

Return type:

Observation

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 state the observation should happen. Valid values are: “time_step__prepare”, “time_step”, “time_step__cleanup”, or “collect_metrics”.
**kwargs (Any) – Additional keyword arguments to be passed to the observation’s constructor.
requires_attributes (list[str])
stratifications (tuple[str, ...] | None)
**kwargs

Returns:

The instantiated Observation object.

Raises:

ValueError – If the observation name is already used.

gather_results(population, lifecycle_state, event_observations)[source]

Generates and yields current results for all observations at this lifecycle state and event.

Each set of results are stratified and grouped by all registered stratifications as well as filtered by their respective observation’s pop_filter.

Return type:

Generator[tuple[DataFrame, str, Callable[[DataFrame, DataFrame], DataFrame]], None, None]

Parameters:

population (DataFrame) – The current population DataFrame.
lifecycle_state (str) – The current lifecycle state.
event_observations (list[Observation]) – List of observations to be gathered for this specific event. Note that this excludes all observations whose to_observe method returns False.

Yields:

A tuple containing each observation’s newly observed results, the name of
the observation, and the observations results updater function. Note that
it yields (None, None, None) if the filtered population is empty.

Raises:

ValueError – If a stratification’s temporary column name already exists in the population DataFrame.

get_observations(event)[source]

Gets all observations for a given event.

Return type:: list[Observation]
Parameters:: event (Event) – The current Event.
Returns:: A list of Observations for the given event. Only includes observations whose to_observe method returns True.

get_stratifications(observations)[source]

Gets all stratifications for a given set of observations.

Return type:: list[Stratification]
Parameters:: observations (list[Observation]) – The observations to gather stratifications from.
Returns:: A list of Stratifications used by at least one of the observations.

get_required_attributes(observations, stratifications)[source]

Gets all population attributes required for producing results for a given Event.

Return type:

list[str]

Parameters:

observations (list[Observation]) – List of observations to be gathered for this specific event. Note that this excludes all observations whose to_observe method returns False.
stratifications (list[Stratification]) – List of stratifications to be gathered for this specific event. This only includes stratifications which are needed by the observations which will be made during this Event.

Returns:

All population attributes required for producing results for the given Event.