diff --git a/docs/source/concepts/results.rst b/docs/source/concepts/results.rst index 3581aed5..4463a7fb 100644 --- a/docs/source/concepts/results.rst +++ b/docs/source/concepts/results.rst @@ -303,7 +303,7 @@ A couple other more specific and commonly used observations are provided as well that gathers new results and concatenates them to any existing results. Ideally, all concrete classes should inherit from the -:class:`BaseObservation ` +:class:`Observation ` abstract base class, which contains the common attributes between observation types: .. list-table:: **Common Observation Attributes** @@ -312,40 +312,40 @@ abstract base class, which contains the common attributes between observation ty * - Attribute - Description - * - | :attr:`name ` + * - | :attr:`name ` - | Name of the observation. It will also be the name of the output results file | for this particular observation. - * - | :attr:`pop_filter ` + * - | :attr:`pop_filter ` - | A Pandas query filter string to filter the population down to the simulants | who should be considered for the observation. - * - | :attr:`when ` + * - | :attr:`when ` - | Name of the lifecycle phase the observation should happen. Valid values are: | "time_step__prepare", "time_step", "time_step__cleanup", or "collect_metrics". - * - | :attr:`results_initializer ` + * - | :attr:`results_initializer ` - | Method or function that initializes the raw observation results | prior to starting the simulation. This could return, for example, an empty | DataFrame or one with a complete set of stratifications as the index and | all values set to 0.0. - * - | :attr:`results_gatherer ` + * - | :attr:`results_gatherer ` - | Method or function that gathers the new observation results. - * - | :attr:`results_updater ` + * - | :attr:`results_updater ` - | Method or function that updates existing raw observation results with newly | gathered results. - * - | :attr:`results_formatter ` + * - | :attr:`results_formatter ` - | Method or function that formats the raw observation results. - * - | :attr:`stratifications ` + * - | :attr:`stratifications ` - | Optional tuple of column names for the observation to stratify by. - * - | :attr:`to_observe ` + * - | :attr:`to_observe ` - | Method or function that determines whether to perform an observation on this Event. -The **BaseObservation** also contains the -:meth:`observe ` +The **Observation** also contains the +:meth:`observe ` method which is called at each :ref:`event ` and :ref:`time step ` to determine whether or not the observation should be recorded, and if so, gathers the results and stores them in the results system. .. note:: - All four observation types discussed above inherit from the **BaseObservation** + All four observation types discussed above inherit from the **Observation** abstract base class. What differentiates them are the assigned attributes (e.g. defining the **results_updater** to be an adding method for the **AddingObservation**) or adding other attributes as necessary (e.g. diff --git a/src/vivarium/framework/results/context.py b/src/vivarium/framework/results/context.py index cee07d48..119bebe0 100644 --- a/src/vivarium/framework/results/context.py +++ b/src/vivarium/framework/results/context.py @@ -17,7 +17,7 @@ from vivarium.framework.engine import Builder from vivarium.framework.event import Event from vivarium.framework.results.exceptions import ResultsConfigurationError -from vivarium.framework.results.observation import BaseObservation +from vivarium.framework.results.observation import Observation from vivarium.framework.results.stratification import ( Stratification, get_mapped_col_name, @@ -58,7 +58,7 @@ def __init__(self) -> None: self.stratifications: list[Stratification] = [] self.excluded_categories: dict[str, list[str]] = {} self.observations: defaultdict[ - str, defaultdict[tuple[str, tuple[str, ...] | None], list[BaseObservation]] + str, defaultdict[tuple[str, tuple[str, ...] | None], list[Observation]] ] = defaultdict(lambda: defaultdict(list)) @property @@ -186,7 +186,7 @@ def add_stratification( def register_observation( self, - observation_type: Type[BaseObservation], + observation_type: Type[Observation], name: str, pop_filter: str, when: str, diff --git a/src/vivarium/framework/results/manager.py b/src/vivarium/framework/results/manager.py index b9db068c..ee686476 100644 --- a/src/vivarium/framework/results/manager.py +++ b/src/vivarium/framework/results/manager.py @@ -14,7 +14,7 @@ from vivarium.framework.event import Event from vivarium.framework.results.context import ResultsContext -from vivarium.framework.results.observation import BaseObservation +from vivarium.framework.results.observation import Observation from vivarium.framework.values import Pipeline from vivarium.manager import Manager from vivarium.types import ScalarValue @@ -302,7 +302,7 @@ def _bin_data(data: Union[pd.Series, pd.DataFrame]) -> pd.Series: def register_observation( self, - observation_type: Type[BaseObservation], + observation_type: Type[Observation], is_stratified: bool, name: str, pop_filter: str, diff --git a/src/vivarium/framework/results/observation.py b/src/vivarium/framework/results/observation.py index 8bf081b3..8037573f 100644 --- a/src/vivarium/framework/results/observation.py +++ b/src/vivarium/framework/results/observation.py @@ -6,7 +6,7 @@ An observation is a class object that records simulation results; they are responsible for initializing, gathering, updating, and formatting results. -The provided :class:`BaseObservation` class is an abstract base class that should +The provided :class:`Observation` class is an abstract base class that should be subclassed by concrete observations. While there are no required abstract methods to define when subclassing, the class does provide common attributes as well as an `observe` method that determines whether to observe results for a given event. @@ -36,7 +36,7 @@ @dataclass -class BaseObservation(ABC): +class Observation(ABC): """An abstract base dataclass to be inherited by concrete observations. This class includes an :meth:`observe ` method that determines whether @@ -100,7 +100,7 @@ def observe( return self.results_gatherer(df, stratifications) -class UnstratifiedObservation(BaseObservation): +class UnstratifiedObservation(Observation): """Concrete class for observing results that are not stratified. The parent class `stratifications` are set to None and the `results_initializer` @@ -182,7 +182,7 @@ def create_empty_df( return pd.DataFrame() -class StratifiedObservation(BaseObservation): +class StratifiedObservation(Observation): """Concrete class for observing stratified results. The parent class `results_initializer` and `results_gatherer` methods are diff --git a/src/vivarium/framework/results/observer.py b/src/vivarium/framework/results/observer.py index 7a37a5db..a04c71b2 100644 --- a/src/vivarium/framework/results/observer.py +++ b/src/vivarium/framework/results/observer.py @@ -5,7 +5,7 @@ ========= An observer is a component that is responsible for registering -:class:`observations ` +:class:`observations ` to the simulation. The provided :class:`Observer` class is an abstract base class that should be subclassed