Results docs cleanup

CHANGELOG.rst

@@ -1,3 +1,9 @@
+**3.0.5 - 08/29/24**
+
+ - Add missing results module-level docstrings
+ - Strengthen the SimpleCause docstring
+ - Rename the SimpleCause class method
+
 **3.0.4 - 08/28/24**
 
  - Strengthen results docstrings and clean up others throughout

src/vivarium_public_health/results/disability.py

@@ -1,7 +1,7 @@
 """
-===================
-Disability Observer
-===================
+====================
+Disability Observers
+====================
 
 This module contains tools for observing years lived with disability (YLDs)
 in the simulation.
@@ -102,7 +102,7 @@ def set_causes_of_disability(self, builder: Builder) -> None:
         )
         # Convert to SimpleCause instances and add on all_causes
         causes_of_disability = [
-            SimpleCause.create_from_disease_state(cause) for cause in causes_of_disability
+            SimpleCause.create_from_specific_cause(cause) for cause in causes_of_disability
         ] + [SimpleCause("all_causes", "all_causes", "cause")]
 
         excluded_causes = (

src/vivarium_public_health/results/disease.py

@@ -1,7 +1,7 @@
 """
-================
-Disease Observer
-================
+=================
+Disease Observers
+=================
 
 This module contains tools for observing disease incidence and prevalence
 in the simulation.

src/vivarium_public_health/results/mortality.py

@@ -1,7 +1,7 @@
 """
-==================
-Mortality Observer
-==================
+===================
+Mortality Observers
+===================
 
 This module contains tools for observing cause-specific and
 excess mortality in the simulation, including "other causes".
@@ -130,7 +130,7 @@ def set_causes_of_death(self, builder: Builder) -> None:
 
         # Convert to SimpleCauses and add on other_causes and not_dead
         self.causes_of_death = [
-            SimpleCause.create_from_disease_state(cause) for cause in causes_of_death
+            SimpleCause.create_from_specific_cause(cause) for cause in causes_of_death
         ] + [
             SimpleCause("not_dead", "not_dead", "cause"),
             SimpleCause("other_causes", "other_causes", "cause"),

src/vivarium_public_health/results/observer.py

@@ -1,3 +1,13 @@
+"""
+===============
+Basic Observers
+===============
+
+This module contains convenience classes for building concrete observers in
+public health models.
+
+"""
+
 from typing import Callable, List, Optional, Union
 
 import pandas as pd

src/vivarium_public_health/results/simple_cause.py

@@ -1,12 +1,21 @@
+"""
+============
+Simple Cause
+============
+
+This module contains tools for creating a minimal representation of a cause
+as required by observers.
+
+"""
+
 from dataclasses import dataclass
 
 
 @dataclass
 class SimpleCause:
-    """A simple dataclass to represent the bare minimum information needed
-    for observers, e.g. 'all_causes' as a cause of disability.
+    """A simple dataclass to represent the bare minimum information needed by observers.
 
-    It also includes a class method to convert a provided disease state into a
+    It also includes a class method to convert a provided cause into a
     ``SimpleCause`` instance.
 
     """
@@ -19,6 +28,16 @@ class SimpleCause:
     """The cause type of the cause."""
 
     @classmethod
-    def create_from_disease_state(cls, disease_state: type) -> "SimpleCause":
-        """Create a SimpleCause instance from a"""
-        return cls(disease_state.state_id, disease_state.model, disease_state.cause_type)
+    def create_from_specific_cause(cls, cause: type) -> "SimpleCause":
+        """Create a SimpleCause instance from a more specific cause.
+
+        Parameters
+        ----------
+        cause
+            The cause to be converted into a SimpleCause instance.
+
+        Returns
+        -------
+            A SimpleCause instance.
+        """
+        return cls(cause.state_id, cause.model, cause.cause_type)