Results Interface

This module provides an interface to the ResultsManager.

vivarium.engine.framework.results.interface.ResultsUpdater

A Callable that takes existing results and new observations and returns updated results.

alias of Callable[[DataFrame, DataFrame], DataFrame]

vivarium.engine.framework.results.interface.ResultsFormatter

A Callable that takes a measure as a string and a DataFrame of observation results and returns formatted results.

alias of Callable[[str, DataFrame], DataFrame]

vivarium.engine.framework.results.interface.ResultsGatherer

A Callable that optionally takes a possibly stratified population and returns new observation results.

alias of Callable[[DataFrame | DataFrameGroupBy | tuple[str, …] | None], DataFrame]

class vivarium.engine.framework.results.interface.PopulationFilter(query='', include_untracked=False)[source]

Container class for population query string and include_untracked flag.

Parameters:

  • query (str)

  • include_untracked (bool)

query: str

Alias for field number 0

include_untracked: bool

Alias for field number 1

class vivarium.engine.framework.results.interface.ResultsInterface(manager)[source]

Builder interface for the results management system.

The results management system allows users to delegate results production to the simulation framework. This process attempts to roughly mimic the groupby-apply logic commonly done when manipulating pandas DataFrames. Good encapsulation of simulation logic typically has results production separated from the modeling code into specialized Observer components. This often highlights the need for transformations of the simulation state into representations that aren’t needed for modeling, but are required for the stratification of produced results.

The purpose of this interface is to provide controlled access to a results backend by means of the builder object; it exposes methods to register both stratifications and results producers (referred to as “observations”).

Parameters:

manager (ResultsManager)

property name: str
register_stratification(name, categories, excluded_categories=None, mapper=None, is_vectorized=False, requires_attributes=[])[source]

Registers a stratification that can be used by stratified observations.

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 the population attributes specified by the requires_attributes argumnt 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]) – The population attributes that are required by the mapper to produce the stratification.

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

Registers a binned stratification that can be used by stratified observations.

Return type:

None

Parameters:

  • target (str) – Name of the 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_stratified_observation(name, pop_filter='', include_untracked=False, when='collect_metrics', requires_attributes=[], results_updater=<function _required_function_placeholder>, results_formatter=<function _default_stratified_observation_formatter>, additional_stratifications=[], excluded_stratifications=[], aggregator_sources=None, aggregator=<built-in function len>, to_observe=<function ResultsInterface.<lambda>>)[source]

Registers a stratified observation to the results system.

Parameters:

  • name (str) – Name of the observation. It will also be the name of the output results file for this particular observation.

  • pop_filter (str) – A Pandas query filter string to filter the population down to the simulants who should be considered for the observation.

  • include_untracked (bool) – Whether to include simulants who are untracked from this 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 by the aggregator.

  • results_updater (ResultsUpdater) – Function that updates existing raw observation results with newly gathered results.

  • results_formatter (ResultsFormatter) – Function that formats the raw observation results.

  • additional_stratifications (list[str]) – List of additional Stratification names by which to stratify this observation by.

  • excluded_stratifications (list[str]) – List of default Stratification names to remove from this observation.

  • aggregator_sources (list[str] | None) – List of population view columns to be used in the aggregator.

  • aggregator (Callable[[pd.DataFrame], float | pd.Series[Any]]) – Function that computes the quantity for this observation.

  • to_observe (Callable[[Event], bool]) – Function that determines whether to perform an observation on this Event.

Raises:

ValueError – If any required callable arguments are missing.

Return type:

None

register_unstratified_observation(name, pop_filter='', include_untracked=False, when='collect_metrics', requires_attributes=[], results_gatherer=<function _required_function_placeholder>, results_updater=<function _required_function_placeholder>, results_formatter=<function _default_unstratified_observation_formatter>, to_observe=<function ResultsInterface.<lambda>>)[source]

Registers an unstratified observation to the results system.

Return type:

None

Parameters:

  • name (str) – Name of the observation. It will also be the name of the output results file for this particular observation.

  • pop_filter (str) – A Pandas query filter string to filter the population down to the simulants who should be considered for the observation.

  • include_untracked (bool) – Whether to include simulants who are untracked from this 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 by the results_gatherer.

  • results_gatherer (Callable[[DataFrame | DataFrameGroupBy | tuple[str, ...] | None], DataFrame]) – Function that gathers the latest observation results.

  • results_updater (Callable[[DataFrame, DataFrame], DataFrame]) – Function that updates existing raw observation results with newly gathered results.

  • results_formatter (Callable[[str, DataFrame], DataFrame]) – Function that formats the raw observation results.

  • to_observe (Callable[[Event], bool]) – Function that determines whether to perform an observation on this Event.

Raises:

ValueError – If any required callable arguments are missing.

register_adding_observation(name, pop_filter='', include_untracked=False, when='collect_metrics', requires_attributes=[], results_formatter=<function _default_stratified_observation_formatter>, additional_stratifications=[], excluded_stratifications=[], aggregator_sources=None, aggregator=<built-in function len>, to_observe=<function ResultsInterface.<lambda>>)[source]

Registers an adding observation to the results system.

An “adding” observation is one that adds/sums new results to existing result values.

Notes

An adding observation is a specific type of stratified observation.

Parameters:

  • name (str) – Name of the observation. It will also be the name of the output results file for this particular observation.

  • pop_filter (str) – A Pandas query filter string to filter the population down to the simulants who should be considered for the observation.

  • include_untracked (bool) – Whether to include simulants who are untracked from this 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 by the aggregator.

  • results_formatter (ResultsFormatter) – Function that formats the raw observation results.

  • additional_stratifications (list[str]) – List of additional Stratification names by which to stratify this observation by.

  • excluded_stratifications (list[str]) – List of default Stratification names to remove from this observation.

  • aggregator_sources (list[str] | None) – List of population view columns to be used in the aggregator.

  • aggregator (Callable[[pd.DataFrame], int | float | pd.Series[int | float]]) – Function that computes the quantity for this observation.

  • to_observe (Callable[[Event], bool]) – Function that determines whether to perform an observation on this Event.

Return type:

None

register_concatenating_observation(name, pop_filter='', include_untracked=False, when='collect_metrics', requires_attributes=[], results_formatter=<function _default_unstratified_observation_formatter>, to_observe=<function ResultsInterface.<lambda>>)[source]

Registers a concatenating observation to the results system.

A “concatenating” observation is one that concatenates new results to existing results.

Return type:

None

Parameters:

Notes

A concatenating observation is a specific type of unstratified observation.

Parameters:

  • name (str) – Name of the observation. It will also be the name of the output results file for this particular observation.

  • pop_filter (str) – A Pandas query filter string to filter the population down to the simulants who should be considered for the observation.

  • include_untracked (bool) – Whether to include simulants who are untracked from this 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 by the aggregator.

  • results_formatter (Callable[[str, DataFrame], DataFrame]) – Function that formats the raw observation results.

  • to_observe (Callable[[Event], bool]) – Function that determines whether to perform an observation on this Event.

Return type:

None