Add section to lookup.rst about configuring source via component (#694)

* Add section to lookup.rst about configuring source via component

* add blank line

* adjustments for feedback

* add nitpick exceptions

* update references and backticks

* update method references

* remove nitpick exceptions

* fix model spec file link

* add backticks for listeners, add logger ref

* fix ref to artifactmanager

* add ref to pop view

* add note about data sources in config defaults

* changelog

* update class reference

* add links

* fix link formatting

* Update CHANGELOG date for version 3.6.4

Author: patricktnast

CHANGELOG.rst

@@ -1,3 +1,7 @@
+**3.6.4 - 12/16/25**
+
+  - Add documentation for Component LookupTable configuration
+  
 **3.6.3 - 11/20/25**
 
   - Raise ValueError if null values are present in probabilities in RandomnessStream.filter_for_probability()

docs/nitpick-exceptions

@@ -51,9 +51,19 @@ py:class vivarium.framework.utilities.T
 
 # layered_config_tree
 py:class layered_config_tree.main.LayeredConfigTree
-py:class LayeredConfigTree
 py:exc layered_config_tree.exceptions.ConfigurationError
 
+# Special methods that Sphinx can't resolve
+py:meth __init__
+py:meth __repr__
+
+# vivarium internal references that may not be in the docs
+py:class vivarium.framework.population.PopulationView
+py:class vivarium.framework.lookup.LookupTable
+py:class vivarium.framework.artifact.ArtifactManager
+py:meth vivarium.framework.artifact.ArtifactInterface.load
+py:class Component
+
 # TODO: Need to revisit this. Nitpicking here to avoid failing builds on 3.9
 py:class Logger
 py:class Path

docs/source/concepts/lookup.rst

@@ -142,16 +142,200 @@ Female  40         60       30
 Female  60         100      27
 ======  =========  =======  ======
 
+Constructing Lookup Tables from a Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Components can register lookup tables to be built by specifying
+a ``data_sources`` block in their :attr:`~vivarium.component.Component.configuration_defaults` property. 
+As a basic example, DiseaseModel in ``vivarium_public_health`` has the following
+``data_sources`` configuration:
+
+.. code-block:: python
+
+    @property
+    def configuration_defaults(self) -> dict[str, Any]:
+        return {
+            f"{self.name}": {
+                "data_sources": {
+                    "cause_specific_mortality_rate": self.load_cause_specific_mortality_rate,
+                },
+            },
+        }
+
+which specifies a single lookup table named
+``cause_specific_mortality_rate`` whose data is provided by the component's
+``load_cause_specific_mortality_rate`` method.
+
+Each entry in ``data_sources`` maps a table name to a data source from one of
+several supported types (see `Data Source Types`_). Barring edge cases (see
+`Limitations and When to Override`_), one should specify all of a component's
+lookup tables via ``data_sources``, instead of accessing the builder's lookup
+interface directly.
+
+When a component configures ``data_sources``, the base
+:class:`~vivarium.component.Component` class automatically builds
+the lookup tables before the component's :meth:`~vivarium.component.Component.setup` method is called. The
+resulting tables are stored in the component's :attr:`~vivarium.component.Component.lookup_tables` dictionary,
+keyed by the name specified in ``data_sources``. 
+
+This approach separates the *what* (which tables to build and where to get data) from the
+*how* (the mechanics of table construction), making components easier to
+write and configure. It also allows users to override data sources in model specification files
+without modifying component code. Following the example above, a model specification could adjust the 
+``cause_specific_mortality_rate`` data source to point to different data or a scalar value:
+
+.. code-block:: yaml
+
+    configuration:
+        disease_model:
+            data_sources:
+                cause_specific_mortality_rate: 0.02
+
+Data Source Types
+^^^^^^^^^^^^^^^^^
+
+Each entry in ``data_sources`` maps a table name to a data source. The
+following data source types are supported:
+
+**Artifact key (string without** ``::`` **):**
+    A string path to data in the artifact, e.g.,
+    ``"cause.all_causes.cause_specific_mortality_rate"``. The data is loaded
+    via :meth:`builder.data.load() <vivarium.framework.artifact.interface.ArtifactInterface.load>`. Strings with ``::`` are reserved for method
+    or function references (see below).
+
+**Callable:**
+    Any callable (function, lambda, or bound method) that accepts a ``builder``
+    argument and returns the data.
+
+**Scalar value:**
+    A numeric value (``int``, ``float``), ``datetime``, or ``timedelta`` that
+    will be broadcast over the population index when the table is called.
+
+**Method reference (string with** ``self::`` **):**
+    A string of the form ``"self::method_name"`` that references a method on
+    the component itself. The method should accept a ``builder`` argument and
+    return the data. This is primarily for use in
+    :ref:`model specification YAML files <model_specification_concept>` where
+    direct method references are not possible.
+
+**External function reference (string with** ``module.path::`` **):**
+    A string of the form ``"module.path::function_name"`` that references a
+    function in another module. The function should accept a ``builder``
+    argument and return the data. This is primarily for use in
+    :ref:`model specification YAML files <model_specification_concept>` where
+    direct method references are not possible.
+
+
+
+Column Detection
+^^^^^^^^^^^^^^^^
+
+When building a lookup table from a :class:`pandas.DataFrame` using ``data_sources``,
+the component automatically determines key columns, parameter columns, and value columns
+based on the data structure:
+
+- **Value columns** are assumed by the structure of the artifact to be ``["value"]``. In principle,
+  this could be configured by implementing a custom :class:`~vivarium.framework.artifact.manager.ArtifactManager`.
+- **Parameter columns** are detected by finding columns ending in ``_start``
+  that have corresponding ``_end`` columns (e.g., ``age_start``/``age_end``).
+- **Key columns** are all remaining columns that are neither value columns
+  nor parameter bin edge columns.
+
+See the `Construction Parameters`_ section for definitions of these
+column types.
+
+Example: Writing a Component with Data Sources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A more complete example is reproduced from the `Mortality <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/api_reference/population/mortality.html>`_ component in `vivarium_public_health <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/>`_:
+
+.. code-block:: python
+
+    from vivarium import Component
+
+    class Mortality(Component):
+
+        @property
+        def configuration_defaults(self) -> dict[str, Any]:
+            return {
+                "mortality": {
+                    "data_sources": {
+                        # Artifact key - loaded via builder.data.load()
+                        "all_cause_mortality_rate": "cause.all_causes.cause_specific_mortality_rate",
+                        # Method reference - calls self.load_unmodeled_csmr(builder)
+                        "unmodeled_cause_specific_mortality_rate": self.load_unmodeled_csmr,
+                        # Another artifact key
+                        "life_expectancy": "population.theoretical_minimum_risk_life_expectancy",
+                    },
+                    "unmodeled_causes": [],
+                },
+            }
+
+Example: Configuring Data Sources as a User
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users can override the default data sources in a :ref:`model specification <model_specification_concept>`
+file. This allows changing where data comes from without modifying component
+code:
+
+.. code-block:: yaml
+
+    configuration:
+        mortality:
+            data_sources:
+                # Override with a scalar value instead of artifact data
+                all_cause_mortality_rate: 0.01
+                # point to a module function
+                unmodeled_cause_specific_mortality_rate: "my_module.data::load_unmodeled_csmr"
+                # Or point to different artifact data
+                life_expectancy: "alternative.life_expectancy.data"
+
+Limitations and When to Override
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The automatic ``data_sources`` mechanism works well for straightforward cases,
+but some situations require overriding the :meth:`~vivarium.component.Component.build_all_lookup_tables` method:
+
+**Non-standard value columns:**
+    The component defaults to ``["value"]`` as the value column name. If your
+    data has differently named value columns or multiple value columns, you
+    must call :meth:`~vivarium.component.Component.build_lookup_table` directly with explicit
+    ``value_columns``.
+
+**Complex data transformations:**
+    When data requires transformation before building tables (e.g., pivoting,
+    computing derived parameters, combining multiple data sources), override
+    :meth:`~vivarium.component.Component.build_all_lookup_tables` to perform the transformation first.
+
+**Delegation to sub-components:**
+    When lookup tables should be built by sub-components rather than the
+    parent component, override :meth:`~vivarium.component.Component.build_all_lookup_tables` to skip the
+    default behavior.
+
+Examples of these patterns can be found in `vivarium_public_health <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/>`_:
+
+- `RateTransition <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/api_reference/disease/transition.html>`_ and `DiseaseState <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/api_reference/disease/state.html>`_ in `vivarium_public_health.disease <https://vivarium.readthedocs.io/projects/vivarium-public-health/en/latest/api_reference/disease/>`_
+  demonstrate the basic ``data_sources`` pattern with various data source types.
+- ``Risk`` in ``vivarium_public_health.risks`` overrides :meth:`~vivarium.component.Component.build_all_lookup_tables`
+  to delegate table construction to its exposure distribution sub-component.
+
+Using the Lookup Interface Directly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For cases not covered by ``data_sources``, or when working in an interactive
+context, you can build lookup tables directly using the builder's lookup
+interface. 
+
 Example Usage
 ~~~~~~~~~~~~~
 
 The following is an example of creating and calling a lookup table in an
-:ref:`interactive setting <interactive_tutorial>` using the data above. The
-interface and process are the same when integrating a lookup table into a
-:term:`component <Component>`, which is primarily how they are used. Assuming
-you have a valid simulation object named ``sim`` and the data from the above
-table in a :class:`pandas.DataFrame` named ``data``, you can construct a
-lookup table in the following way, using the interface from the builder.
+:ref:`interactive setting <interactive_tutorial>` using the data from 
+`Construction Parameters`_ above. The interface and process are the same when 
+integrating a lookup table into a :term:`component <Component>`, which is primarily 
+how they are used. Assuming you have a valid simulation object named ``sim`` and 
+the data from the above table in a :class:`pandas.DataFrame` named ``data``, you 
+can construct a lookup table in the following way, using the interface from the builder.
 
 .. code-block:: python