Fixes for doc building; minor docstring updates (#467)

.gitignore

@@ -115,3 +115,6 @@ notebooks/
 
 # Version file
 src/vivarium/_version.py
+
+# macOS
+*.DS_Store

docs/nitpick-exceptions

@@ -6,6 +6,7 @@ py:class pandas._libs.tslibs.timedeltas.Timedelta
 py:class pandas.core.frame.DataFrame
 py:class pandas.core.series.Series
 py:class pandas.core.generic.PandasObject
+py:class pandas.core.groupby.generic.DataFrameGroupBy
 
 #scipy
 py:class scipy.stats._distn_infrastructure.rv_continuous
@@ -21,6 +22,8 @@ py:class Time
 py:class vivarium.framework.time.Time
 py:class Timedelta
 py:class vivarium.framework.time.Timedelta
+py:exc ResultsConfigurationError
+py:exc vivarium.framework.results.exceptions.ResultsConfigurationError
 
 # layered_config_tree
 py:class layered_config_tree.main.LayeredConfigTree

docs/source/api_reference/framework/results/context.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.context

docs/source/api_reference/framework/results/index.rst

@@ -0,0 +1,11 @@
+==================
+Results Processing
+==================
+
+.. automodule:: vivarium.framework.results
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/api_reference/framework/results/interface.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.interface

docs/source/api_reference/framework/results/manager.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.manager

docs/source/api_reference/framework/results/observation.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.observation

docs/source/api_reference/framework/results/observer.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.observer

docs/source/api_reference/framework/results/stratification.rst

@@ -0,0 +1 @@
+.. automodule:: vivarium.framework.results.stratification

docs/source/concepts/results.rst

@@ -0,0 +1,9 @@
+.. _results_concept:
+
+==================
+Simulation Results
+==================
+
+.. todo::
+
+   Everything here.

src/vivarium/framework/artifact/artifact.py

@@ -37,7 +37,7 @@ def __init__(self, path: Union[str, Path], filter_terms: List[str] = None):
             The path to the artifact file.
         filter_terms
             A set of terms suitable for usage with the ``where`` kwarg
-            for :func:`pd.read_hdf`.
+            for :func:`pandas.read_hdf`.
 
         """
         self._path = Path(path)
@@ -76,7 +76,7 @@ def create_hdf_with_keyspace(path: Path):
                 "Attempting to construct an Artifact from a malformed existing file. "
                 "This can occur when constructing an Artifact from an existing file when "
                 "the existing file was generated by some other hdf writing mechanism "
-                "(e.g. pd.to_hdf) rather than generating the the file using this class "
+                "(e.g. pandas.to_hdf) rather than generating the the file using this class "
                 "and a non-existent or empty hdf file."
             )
         if not keys:

src/vivarium/framework/artifact/hdf.py

@@ -404,7 +404,7 @@ def _get_valid_filter_terms(filter_terms, colnames):
     ----------
     filter_terms
         A list of terms formatted so as to be used in the `where` argument of
-        :func:`pd.read_hdf`.
+        :func:`pandas.read_hdf`.
     colnames :
         A list of column names present in the data that will be filtered.
 

src/vivarium/framework/lookup/interpolation.py

@@ -99,7 +99,7 @@ def __call__(self, interpolants: pd.DataFrame) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame
+        pandas.DataFrame
             A table with the interpolated values for the given interpolants.
         """
 
@@ -316,7 +316,7 @@ def __call__(self, interpolants: pd.DataFrame) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame
+        pandas.DataFrame
             A table with the interpolated values for the given interpolants.
 
         """

src/vivarium/framework/population/population_view.py

@@ -475,7 +475,7 @@ def _update_column_and_ensure_dtype(
 
         Returns
         -------
-        pd.Series
+        pandas.Series
             The column with the provided update applied
 
         """

src/vivarium/framework/randomness/index_map.py

@@ -73,7 +73,7 @@ def _parse_new_keys(self, new_keys: pd.DataFrame) -> Tuple[pd.MultiIndex, pd.Mul
 
         Returns
         -------
-        Tuple[pd.MultiIndex, pd.MultiIndex]
+        Tuple[pandas.MultiIndex, pandas.MultiIndex]
             A tuple of the new mapping index and the final mapping index. Both are pandas
             indices with a level for the index assigned by the population system and
             additional levels for the key columns associated with the simulant index. The
@@ -108,7 +108,7 @@ def _build_final_mapping(
 
         Returns
         -------
-        pd.Series
+        pandas.Series
             The new mapping incorporating the updates from the new mapping index and
             resolving collisions.
 
@@ -140,7 +140,7 @@ def _resolve_collisions(
 
         Returns
         -------
-        pd.Series
+        pandas.Series
             The new mapping incorporating the updates from the new mapping index and
             resolving collisions.
 

src/vivarium/framework/results/context.py

@@ -4,13 +4,11 @@
 ===============
 """
 
-from __future__ import annotations
-
 from collections import defaultdict
-from typing import Any, Callable, Generator, List, Optional, Tuple, Type, Union
+from typing import Callable, Generator, List, Optional, Tuple, Type, Union
 
 import pandas as pd
-from pandas.core.groupby import DataFrameGroupBy
+from pandas.core.groupby.generic import DataFrameGroupBy
 
 from vivarium.framework.engine import Builder
 from vivarium.framework.event import Event
@@ -29,8 +27,8 @@ class ResultsContext:
 
     This context object is wholly contained by :class:`ResultsManager <vivarium.framework.results.manager.ResultsManager>`.
     Stratifications and observations can be added to the context through the manager via the
-    :meth:`vivarium.framework.results.context.ResultsContext.add_stratification` and
-    :meth:`vivarium.framework.results.context.ResultsContext.register_observation` methods, respectively.
+    :meth:`add_stratification <vivarium.framework.results.context.ResultsContext.add_stratification>` and
+    :meth:`register_observation <vivarium.framework.results.context.ResultsContext.register_observation>` methods, respectively.
 
     Attributes
     ----------
@@ -101,7 +99,7 @@ def add_stratification(
         excluded_categories: Optional[List[str]],
         mapper: Optional[
             Union[
-                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series[str]],
+                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series],
                 Callable[[ScalarValue], str],
             ]
         ],
@@ -132,9 +130,11 @@ def add_stratification(
         Raises
         ------
         ValueError
-            - If the stratification `name` is already used.
-            - If there are duplicate `categories`.
-            - If any `excluded_categories` are not in `categories`.
+            If the stratification `name` is already used.
+        ValueError
+            If there are duplicate `categories`.
+        ValueError
+            If any `excluded_categories` are not in `categories`.
         """
         already_used = [
             stratification

src/vivarium/framework/results/interface.py

@@ -1,16 +1,14 @@
 """
-==========================
-Vivarium Results Interface
-==========================
+=================
+Results Interface
+=================
 
 This module provides a :class:`ResultsInterface <ResultsInterface>` class with
 methods to register stratifications and results producers (referred to as "observations")
 to a simulation.
 """
 
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Union
 
 import pandas as pd
 
@@ -74,7 +72,7 @@ def register_stratification(
         excluded_categories: Optional[List[str]] = None,
         mapper: Optional[
             Union[
-                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series[str]],
+                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series],
                 Callable[[ScalarValue], str],
             ]
         ] = None,
@@ -182,7 +180,7 @@ def register_stratified_observation(
         additional_stratifications: List[str] = [],
         excluded_stratifications: List[str] = [],
         aggregator_sources: Optional[List[str]] = None,
-        aggregator: Callable[[pd.DataFrame], Union[float, pd.Series[float]]] = len,
+        aggregator: Callable[[pd.DataFrame], Union[float, pd.Series]] = len,
         to_observe: Callable[[Event], bool] = lambda event: True,
     ) -> None:
         """Registers a stratified observation to the results system.
@@ -323,7 +321,7 @@ def register_adding_observation(
         additional_stratifications: List[str] = [],
         excluded_stratifications: List[str] = [],
         aggregator_sources: Optional[List[str]] = None,
-        aggregator: Callable[[pd.DataFrame], Union[float, pd.Series[float]]] = len,
+        aggregator: Callable[[pd.DataFrame], Union[float, pd.Series]] = len,
         to_observe: Callable[[Event], bool] = lambda event: True,
     ) -> None:
         """Registers an adding observation to the results system; that is,

src/vivarium/framework/results/manager.py

@@ -4,11 +4,9 @@
 ======================
 """
 
-from __future__ import annotations
-
 from collections import defaultdict
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Tuple, Union
 
 import pandas as pd
 
@@ -31,7 +29,7 @@ class ResultsManager(Manager):
     """Backend manager object for the results management system.
 
     This class contains the public methods used by the :class:`ResultsInterface <vivarium.framework.results.interface.ResultsInterface>`
-    to register stratifications and observations as well as the :method:`get_results`
+    to register stratifications and observations as well as the :meth:`get_results <get_results>`
     method used to retrieve formatted results by the :class:`ResultsContext <vivarium.framework.results.context.ResultsContext>`.
     """
 
@@ -66,7 +64,7 @@ def get_results(self) -> Dict[str, pd.DataFrame]:
 
         Returns
         -------
-        Dict[str, pd.DataFrame]
+        Dict[str, pandas.DataFrame]
             A dictionary of formatted results for each measure.
         """
         formatted = {}
@@ -167,7 +165,7 @@ def gather_results(self, lifecycle_phase: str, event: Event) -> None:
     # Stratification methods #
     ##########################
 
-    def set_default_stratifications(self, builder: Builder) -> None:
+    def set_default_stratifications(self, builder: "Builder") -> None:
         """Set the default stratifications for the results context.
 
         This passes the default stratifications from the configuration to the
@@ -189,7 +187,7 @@ def register_stratification(
         excluded_categories: Optional[List[str]],
         mapper: Optional[
             Union[
-                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series[str]],
+                Callable[[Union[pd.Series, pd.DataFrame]], pd.Series],
                 Callable[[ScalarValue], str],
             ]
         ],