Basic Observers

This module contains convenience classes for building concrete observers in public health models.

class vivarium_public_health.results.observer.PublicHealthObserver[source]

A convenience class for typical public health observers.

It exposes a method for registering the most common observation type (adding observation) as well methods for formatting public health results in a standardized way (to be overwritten as necessary).

register_adding_observation(builder, name, pop_filter='', include_untracked=False, when='collect_metrics', requires_attributes=[], additional_stratifications=[], excluded_stratifications=[], aggregator=<built-in function len>, to_observe=<function PublicHealthObserver.<lambda>>)[source]

Register an adding observation to the results system.

An “adding” observation is one that adds/sums new results to existing result values. It is the most common type of observation used in public health models.

Parameters:

builder (Builder) – The builder object.
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 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 by the aggregator.
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 (Callable[[DataFrame], float | Series]) – Function that computes the quantity for this observation.
to_observe (Callable[[Event], bool]) – Function that takes an event and returns a boolean indicating whether the observation should be performed for that event.

Return type:

None

format_results(measure, results)[source]

Format results by calling standard sub-methods.

Public health observations typically require four columns in addition to any stratifications and results columns: ‘measure’, ‘entity_type’, ‘entity’, and ‘sub_entity’. This method provides a standardized way to format results by providing five sub-methods to be overwritten as necessary: - format() - get_measure_column() - get_entity_type_column() - get_entity_column() - get_sub_entity_column()

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

DataFrame

Returns:

The formatted results.

format(measure, results)[source]

Format results.

This method can be overwritten in subclasses to provide custom formatting for the results.

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

DataFrame

Returns:

The formatted results.

get_measure_column(measure, results)[source]

Get the ‘measure’ column.

This method can be overwritten in subclasses to provide the ‘measure’ column.

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

Series

Returns:

The ‘measure’ column values.

get_entity_type_column(measure, results)[source]

Get the ‘entity_type’ column.

This method can be overwritten in subclasses to provide the ‘entity_type’ column.

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

Series

Returns:

The ‘entity_type’ column values.

get_entity_column(measure, results)[source]

Get the ‘entity’ column.

This method can be overwritten in subclasses to provide the ‘entity’ column.

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

Series

Returns:

The ‘entity’ column values.

get_sub_entity_column(measure, results)[source]

Get the ‘sub_entity’ column.

This method can be overwritten in subclasses to provide the ‘sub_entity’ column.

Parameters:

measure (str) – The measure name.
results (DataFrame) – The raw results.

Return type:

Series

Returns:

The ‘sub_entity’ column values.