add blurbs about NonLogLinearRiskEffect

CHANGELOG.rst

@@ -1,10 +1,15 @@
-**3.0.3- 08/20/24**
+**3.0.4 - 08/28/24**
+
+ - Strengthen results docstrings and clean up others throughout
+ - Add mention of NonLogLinearRiskEffect class to risk exposure tutorial
+
+**3.0.3 - 08/20/24**
 
  - Use external script to find matching dependency branches
  - Fix bug when excluding all but one causes of disability from results
  - Update FertilityAgeSpecificRates for new data format of age specific fertility rates
 
-**3.0.2- 08/19/24**
+**3.0.2 - 08/19/24**
 
  - Parameterize the script to find matching dependency branches
 

docs/source/tutorials/risk_exposure.rst

@@ -2,24 +2,28 @@
 Non-standard Risk Exposure and Effect Models
 ============================================
 
-:mod:`vivarium_public_health` provides two components for modeling the impact
+:mod:`vivarium_public_health` provides three components for modeling the impact
 of some health attributes on others:
 
 - :class:`~vivarium_public_health.risks.base_risk.Risk`: Model of the
   underlying exposure based on a continuous or categorical distribution.
 - :class:`~vivarium_public_health.risks.effect.RiskEffect`: Model of the
   impact of different exposure levels on another health attribute.
+- :class:`~vivarium_public_health.risks.effect.NonLogLinearRiskEffect`: 
+  Special-case risk effect model where the risk factors are parameterized
+  by exposure levels.
 
 The standard model is to think of exposure to environmental, metabolic, and
 behavioral risk factors and their impact on disease incidence rates. However,
 we've found many situations to extend this model to other attributes, such as
 interventions and their impacts on other risks, diseases, or mortality itself.
 
 In order to support these extended models, we've made the
-:class:`~vivarium_public_health.risks.base_risk.Risk` and
-:class:`~vivarium_public_health.risks.effect.RiskEffect` components
+:class:`~vivarium_public_health.risks.base_risk.Risk`, 
+:class:`~vivarium_public_health.risks.effect.RiskEffect`, and
+:class:`~vivarium_public_health.risks.effect.NonLogLinearRiskEffect` components
 configurable. This tutorial explains the various configuration options you can
-use with these two components.
+use with these components.
 
 .. contents:
    :local:
@@ -29,7 +33,7 @@ Exposure Models
 ---------------
 
 We model exposure using the
-:class:`~vivarium_public_health.risks.base_risk.Risk` component.
+:class:`~vivarium_public_health.risks.base_risk.Risk` or component.
 Consider its configuration options:
 
 - ``"exposure"``: This option represents the exposure data source. It defaults
@@ -217,12 +221,22 @@ Effect Models
 -------------
 
 Non-standard effect models can **only** be used with dichotomous exposure
-models (models where someone is either exposed or not exposed. The available
+models (models where someone is either exposed or not exposed). The available
 configuration options all correspond to generating a relative risk for
 the exposed population from a set of parameters.
 
 We model exposure effects using the
-:class:`~vivarium_public_health.risks.effect.RiskEffect` component.
+:class:`~vivarium_public_health.risks.effect.RiskEffect` or
+:class:`~vivarium_public_health.risks.effect.NonLogLinearRiskEffect` components.
+
+For this tutorial, we'll focus on the ``RiskEffect`` component. The
+``NonLogLinearRiskEffect`` component is a special case of the ``RiskEffect``
+component where the risk factors are parameterized by exposure levels.
+
+.. todo::
+
+   Add details on how to use the ``NonLogLinearRiskEffect`` component.
+
 Let's look at its configuration options:
 
 - ``"relative_risk"``: Option for specifying a relative risk value directly.

src/vivarium_public_health/risks/effect.py

@@ -17,8 +17,6 @@
 from layered_config_tree import ConfigurationError
 from vivarium import Component
 from vivarium.framework.engine import Builder
-from vivarium.framework.event import Event
-from vivarium.framework.population import SimulantData
 
 from vivarium_public_health.risks import Risk
 from vivarium_public_health.risks.data_transformations import (
@@ -30,8 +28,7 @@
 
 
 class RiskEffect(Component):
-    """A component to model the impact of a risk factor on the target rate of
-    some affected entity.
+    """A component to model the effect of a risk factor on an affected entity's target rate.
 
     This component can source data either from builder.data or from parameters
     supplied in the configuration.
@@ -62,9 +59,7 @@ def get_name(risk: EntityString, target: TargetString) -> str:
 
     @property
     def configuration_defaults(self) -> Dict[str, Any]:
-        """A dictionary containing the defaults for any configurations managed by
-        this component.
-        """
+        """Default values for any configurations managed by this component."""
         return {
             self.name: {
                 "data_sources": {
@@ -324,8 +319,10 @@ def _get_risk_exposure_class(self, builder: Builder) -> Risk:
 
 
 class NonLogLinearRiskEffect(RiskEffect):
-    """A component to model the impact of an exposure-parametrized risk factor on
-    the target rate of some affected entity.
+    """A component to model the exposure-parametrized effect of a risk factor.
+
+    More specifically, this models the effect of the risk factor on the target rate of
+    some affected entity.
 
     This component:
     1) reads TMRED data from the artifact and define the TMREL
@@ -337,6 +334,7 @@ class NonLogLinearRiskEffect(RiskEffect):
     of the RR bin containing a simulant's exposure
     5) uses this LookupTable to modify the target pipeline by linearly interpolating
     a simulant's RR value and multiplying it by the intended target rate
+
     """
 
     ##############
@@ -345,9 +343,7 @@ class NonLogLinearRiskEffect(RiskEffect):
 
     @property
     def configuration_defaults(self) -> Dict[str, Any]:
-        """A dictionary containing the defaults for any configurations managed by
-        this component.
-        """
+        """Default values for any configurations managed by this component."""
         return {
             self.name: {
                 "data_sources": {
@@ -490,6 +486,7 @@ def adjust_target(index: pd.Index, target: pd.Series) -> pd.Series:
     ##############
 
     def validate_rr_data(self, rr_data: pd.DataFrame) -> None:
+        """Validate the relative risk data."""
         # check that rr_data has numeric parameter data
         parameter_data_is_numeric = rr_data["parameter"].dtype.kind in "biufc"
         if not parameter_data_is_numeric: