add docstrings for build_all_lookup_tables custom behavior (#562)

* add docstrings for build_all_lookup_tables custom behavior

* [COPILOT] Add documentation to config defaults

* remove types from data sources args

* my edits to config defaults

* formatting

* remove return blocks

* use consistent structure

* clarify docstring around PAF

* empty commit

* Update CHANGELOG for version 4.3.15

Added documentation for configuration defaults and build_all_lookup_table overrides.

Author: patricktnast

CHANGELOG.rst

@@ -1,3 +1,7 @@
+**4.3.16 - 12/15/25**
+
+  - Add documentation for configuration defaults and build_all_lookup_table overrides
+  
 **4.3.15 - 12/12/25**
 
   - Update PublicHealthObserver to use empty string as default value for required columns

src/vivarium_public_health/disease/model.py

@@ -34,6 +34,18 @@ class DiseaseModel(Machine):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this disease model.
+
+        Configuration structure::
+
+            {disease_name}:
+                data_sources:
+                    cause_specific_mortality_rate:
+                        Source for cause-specific mortality rate (CSMR) data.
+                        Default uses the ``load_cause_specific_mortality_rate``
+                        method which loads from artifact at
+                        ``cause.{cause_name}.cause_specific_mortality_rate``.
+        """
         return {
             f"{self.name}": {
                 "data_sources": {

src/vivarium_public_health/disease/special_disease.py

@@ -97,6 +97,39 @@ def name(self):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this component.
+
+        Configuration structure::
+
+            {component_name}:
+                data_sources:
+                    raw_disability_weight:
+                        Source for disability weight data. Default is the
+                        artifact key ``{cause}.disability_weight``.
+                    cause_specific_mortality_rate:
+                        Source for cause-specific mortality rate data. Default
+                        uses ``load_cause_specific_mortality_rate_data`` method
+                        which loads from artifact if ``mortality`` is True.
+                    excess_mortality_rate:
+                        Source for excess mortality rate data. Default uses
+                        ``load_excess_mortality_rate_data`` method which loads
+                        from artifact if ``mortality`` is True.
+                    population_attributable_fraction:
+                        Source for PAF data. Default is 0, indicating no
+                        mediated effects from other risks.
+                threshold: str or list
+                    Exposure threshold defining disease state. For continuous
+                    risks, provide a string like ``">7"`` or ``"<5"``.
+                    For categorical risks, provide a list of categories
+                    (e.g., ``['cat1', 'cat2']``).
+                mortality: bool
+                    Whether this disease has associated mortality. Default
+                    is True.
+                recoverable: bool
+                    Whether simulants can recover from this disease when
+                    their exposure falls outside the threshold. Default
+                    is True.
+        """
         return {
             self.name: {
                 "data_sources": {

src/vivarium_public_health/disease/state.py

@@ -6,6 +6,7 @@
 This module contains tools to manage standard disease states.
 
 """
+
 import warnings
 from collections.abc import Callable
 from typing import Any
@@ -37,6 +38,24 @@ class BaseDiseaseState(State):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this state.
+
+        Extends the parent State's configuration with disease-specific
+        data sources for prevalence.
+
+        Configuration structure::
+
+            {component_name}:
+                data_sources:
+                    prevalence:
+                        Source for prevalence data used to initialize simulants
+                        into this state. Default is the value set on the instance
+                        (typically 0.0).
+                    birth_prevalence:
+                        Source for birth prevalence data used to initialize
+                        newborn simulants. Default is the value set on the
+                        instance (typically 0.0).
+        """
         configuration_defaults = super().configuration_defaults
         additional_defaults = {
             "prevalence": self.prevalence,
@@ -330,6 +349,42 @@ def initialization_requirements(self) -> list[str | Resource]:
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this disease state.
+
+        Extends BaseDiseaseState's configuration with additional data sources
+        for disease burden metrics.
+
+        Configuration structure::
+
+            {component_name}:
+                data_sources:
+                    prevalence:
+                        Source for prevalence data. Defaults to the
+                        ``prevalence`` constructor argument, or if not
+                        provided, loads from artifact at
+                        ``cause.{state_id}.prevalence``.
+                    birth_prevalence:
+                        Source for birth prevalence data. Defaults to the
+                        ``birth_prevalence`` constructor argument, or if not
+                        provided, loads from artifact at
+                        ``cause.{state_id}.birth_prevalence``.
+                    dwell_time:
+                        Source for dwell time data (minimum time in state
+                        before transition). Defaults to the ``dwell_time``
+                        constructor argument, or if not provided, defaults
+                        to 0 (no minimum dwell time).
+                    disability_weight:
+                        Source for disability weight data used to calculate
+                        years lived with disability (YLDs). Defaults to the
+                        ``disability_weight`` constructor argument, or if not
+                        provided, loads from artifact at
+                        ``cause.{state_id}.disability_weight``.
+                    excess_mortality_rate:
+                        Source for excess mortality rate data. Defaults to the
+                        ``excess_mortality_rate`` constructor argument, or if
+                        not provided, loads from artifact at
+                        ``cause.{state_id}.excess_mortality_rate``.
+        """
         configuration_defaults = super().configuration_defaults
         additional_defaults = {
             "prevalence": self._prevalence_source,

src/vivarium_public_health/disease/transition.py

@@ -6,6 +6,7 @@
 This module contains tools to model transitions between disease states.
 
 """
+
 import warnings
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
@@ -43,6 +44,20 @@ class RateTransition(Transition):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this transition.
+
+        Configuration structure::
+
+            {transition_name}:
+                data_sources:
+                    transition_rate:
+                        Source for transition rate data. The default value is
+                        determined by the ``transition_rate`` constructor argument.
+                rate_conversion_type: str
+                    Method for converting rates to probabilities. Options
+                    are ``"linear"`` (default) or ``"exponential"``. Linear
+                    uses ``rate * dt``, exponential uses ``1 - exp(-rate * dt)``.
+        """
         return {
             f"{self.name}": {
                 "data_sources": {
@@ -202,6 +217,18 @@ class ProportionTransition(Transition):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this transition.
+
+        Configuration structure::
+
+            {transition_name}:
+                data_sources:
+                    proportion:
+                        Source for the proportion of simulants transitioning
+                        at each time step. The default uses the
+                        ``load_proportion`` method which resolves data from
+                        the ``proportion`` constructor argument.
+        """
         return {
             f"{self.name}": {
                 "data_sources": {

src/vivarium_public_health/mslt/delay.py

@@ -95,6 +95,22 @@ class DelayedRisk(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this component.
+
+        Configuration structure::
+
+            {risk_name}:
+                constant_prevalence: bool
+                    If True, smoking prevalence remains constant over time
+                    (no remission). If False, prevalence can change as
+                    simulants quit smoking. Default is False.
+                tobacco_tax: bool
+                    If True, applies tobacco tax intervention effects.
+                    Default is False.
+                delay: int
+                    Number of years of delay before health effects manifest
+                    after exposure changes. Default is 20 years.
+        """
         return {
             self.risk: {
                 "constant_prevalence": False,

src/vivarium_public_health/mslt/disease.py

@@ -149,6 +149,16 @@ class Disease(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this disease model.
+
+        Configuration structure::
+
+            {disease_name}:
+                simplified_no_remission_equations: bool
+                    If True, uses simplified differential equations for
+                    diseases with no remission. This can improve
+                    computational efficiency. Default is False.
+        """
         return {
             self.disease: {
                 "simplified_no_remission_equations": False,

src/vivarium_public_health/mslt/intervention.py

@@ -23,6 +23,17 @@ class ModifyAllCauseMortality(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {intervention_name}:
+                    scale: float
+                        Multiplicative factor applied to all-cause mortality
+                        rate. Values < 1 reduce mortality, values > 1
+                        increase mortality. Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.intervention: {
@@ -65,6 +76,17 @@ class ModifyDiseaseRate(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {intervention_name}:
+                    {disease}_{rate}_scale: float
+                        Multiplicative factor applied to the specified
+                        disease rate. Values < 1 reduce the rate, values > 1
+                        increase it. Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.intervention: {
@@ -147,6 +169,18 @@ class ModifyAcuteDiseaseIncidence(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {intervention_name}:
+                    incidence_scale: float
+                        Multiplicative factor applied to both disability
+                        and mortality rates for the acute disease. Values < 1
+                        reduce incidence, values > 1 increase it.
+                        Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.intervention: {
@@ -190,6 +224,17 @@ class ModifyAcuteDiseaseMorbidity(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {intervention_name}:
+                    yld_scale: float
+                        Multiplicative factor applied to the disability
+                        (YLD) rate. Values < 1 reduce disability, values > 1
+                        increase it. Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.intervention: {
@@ -233,6 +278,17 @@ class ModifyAcuteDiseaseMortality(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {intervention_name}:
+                    mortality_scale: float
+                        Multiplicative factor applied to the acute disease
+                        mortality rate. Values < 1 reduce mortality,
+                        values > 1 increase it. Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.intervention: {
@@ -274,6 +330,16 @@ class TobaccoFreeGeneration(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            tobacco_free_generation:
+                year: int
+                    Year when tobacco initiation stops completely.
+                    Starting from this year, no new tobacco uptake occurs
+                    (incidence rate becomes zero). Default is 2020.
+        """
         return {
             "tobacco_free_generation": {
                 "year": 2020,
@@ -315,6 +381,17 @@ class TobaccoEradication(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            tobacco_eradication:
+                year: int
+                    Year when all tobacco use is eradicated. Starting from
+                    this year, incidence becomes zero (no new uptake) and
+                    remission becomes 100% (all users quit).
+                    Default is 2020.
+        """
         return {
             "tobacco_eradication": {
                 "year": 2020,

src/vivarium_public_health/mslt/magic_wand_components.py

@@ -80,6 +80,18 @@ class ModifyAcuteDiseaseYLD(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {disease_name}:
+                    yld_scale: float
+                        Multiplicative factor applied to the years lived
+                        with disability (YLD) rate. Values < 1 reduce
+                        disability, values > 1 increase it. Must be >= 0.
+                        Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.disease: {
@@ -121,6 +133,17 @@ class ModifyAcuteDiseaseMortality(Component):
 
     @property
     def configuration_defaults(self) -> dict[str, Any]:
+        """Provides default configuration values for this intervention.
+
+        Configuration structure::
+
+            intervention:
+                {disease_name}:
+                    mortality_scale: float
+                        Multiplicative factor applied to the excess mortality
+                        rate. Values < 1 reduce mortality, values > 1
+                        increase it. Must be >= 0. Default is 1.0 (no effect).
+        """
         return {
             "intervention": {
                 self.disease: {