Add ref_key method to DataReference for generating sanitized keys from metadata attributes; update related documentation and examples

Author: dwr-psandhu

dvue/catalog.py

@@ -144,6 +144,34 @@ def matches(self, **criteria: Any) -> bool:
                 return False
         return True
 
+    def ref_key(self) -> str:
+        """Return a string key derived from this reference's metadata attributes.
+
+        The default implementation joins all string-representable attribute values
+        with ``"_"`` separators, sanitising spaces and non-identifier characters
+        to underscores.  The result is intended to be a valid Python identifier
+        so it can be used as a variable name inside :class:`MathDataReference`
+        expression strings.
+
+        Override in subclasses to produce a more readable, domain-specific key
+        from a chosen subset of attributes.
+
+        Examples
+        --------
+        >>> ref = DataReference(df, name="r", station="A", variable="wind", interval="hourly")
+        >>> ref.ref_key()
+        'A_wind_hourly'
+        """
+        parts = []
+        for value in self._attributes.values():
+            if not isinstance(value, (str, int, float, bool)):
+                continue
+            sanitized = re.sub(r"[^a-zA-Z0-9]+", "_", str(value).strip())
+            sanitized = sanitized.strip("_")
+            if sanitized:
+                parts.append(sanitized)
+        return "_".join(parts)
+
     # ------------------------------------------------------------------
     # Data loading
     # ------------------------------------------------------------------

dvue/dataui.py

@@ -57,11 +57,11 @@ class DataProvider(param.Parameterized):
 
     Catalog integration
     -------------------
-    The preferred approach is to override the :attr:`catalog` property to
+    The preferred approach is to override the :attr:`data_catalog` property to
     return a :class:`~dvue.catalog.DataCatalog`.  When set:
 
     * :meth:`get_data_catalog` automatically calls
-      ``catalog.to_dataframe().reset_index()``.
+      ``data_catalog.to_dataframe().reset_index()``.
     * :meth:`get_data_reference` automatically looks up
       :class:`~dvue.catalog.DataReference` objects by name.
     * :meth:`get_data` automatically yields ``ref.getData()`` for each
@@ -70,7 +70,11 @@ class DataProvider(param.Parameterized):
     Manual override
     ---------------
     Override :meth:`get_data_catalog` and :meth:`get_data` directly for
-    full control without a DataCatalog.
+    full control without a DataCatalog.  This is the pattern used by
+    existing subclasses such as ``TimeSeriesDataUIManager`` subclasses that
+    store the catalog as a plain :class:`pandas.DataFrame` attribute and
+    override ``get_data_catalog()`` to return it directly — that pattern
+    continues to work unchanged.
 
     Example – catalog-based provider
     ---------------------------------
@@ -86,7 +90,7 @@ def __init__(self, data_dir, **params):
                 )
 
             @property
-            def catalog(self):
+            def data_catalog(self):
                 return self._catalog
 
         provider = HydroProvider("/data/hydro")
@@ -96,12 +100,19 @@ def catalog(self):
     """
 
     @property
-    def catalog(self) -> DataCatalog | None:
+    def data_catalog(self) -> DataCatalog | None:
         """Return the underlying :class:`~dvue.catalog.DataCatalog`, or ``None``.
 
         Override this property to expose a :class:`~dvue.catalog.DataCatalog`
         to the UI layer.  When ``None`` (the default), :meth:`get_data_catalog`
         and :meth:`get_data` must be overridden manually.
+
+        .. note::
+            This property is intentionally named ``data_catalog`` (not
+            ``catalog``) so that subclasses remain free to use ``self.catalog``
+            as a plain instance attribute — which is the established pattern
+            for :class:`~dvue.tsdataui.TimeSeriesDataUIManager` subclasses
+            that store the catalog as a :class:`pandas.DataFrame`.
         """
         return None
 
@@ -119,9 +130,9 @@ def get_data_catalog(self) -> pd.DataFrame:
         Raises
         ------
         NotImplementedError
-            When neither :attr:`catalog` nor a subclass override are provided.
+            When neither :attr:`data_catalog` nor a subclass override are provided.
         """
-        cat = self.catalog
+        cat = self.data_catalog
         if cat is not None:
             return cat.to_dataframe().reset_index()
         raise NotImplementedError(
@@ -150,13 +161,13 @@ def get_data_reference(self, row: pd.Series) -> DataReference:
         Raises
         ------
         NotImplementedError
-            When :attr:`catalog` is not set and this method is not overridden.
+            When :attr:`data_catalog` is not set and this method is not overridden.
         KeyError
             When the resolved name is not in the catalog.
         ValueError
             When the reference name cannot be determined from *row*.
         """
-        cat = self.catalog
+        cat = self.data_catalog
         if cat is None:
             raise NotImplementedError(
                 "Override get_data_reference() or implement the catalog property in your subclass."
@@ -235,10 +246,11 @@ class DataUIManager(DataProvider):
     -------------------------------------------------
     Override **one** of the following strategies:
 
-    * Set :attr:`~DataProvider.catalog` property → automatic DataFrame + data
-      retrieval from a :class:`~dvue.catalog.DataCatalog`.
+    * Set :attr:`~DataProvider.data_catalog` property → automatic DataFrame +
+      data retrieval from a :class:`~dvue.catalog.DataCatalog`.
     * Override :meth:`~DataProvider.get_data_catalog` directly → supply your
-      own DataFrame.
+      own DataFrame (the established pattern for
+      :class:`~dvue.tsdataui.TimeSeriesDataUIManager` subclasses).
 
     Additional overrides available:
 

examples/ex_catalog_reader.py

@@ -6,7 +6,7 @@
    PatternCSVDirectoryReader.
 2. Writing a minimal custom DataCatalogReader for a new source type.
 3. Connecting a DataCatalog to a DataUIManager (and DataUI) via the
-   DataProvider.catalog property.
+   DataProvider.data_catalog property.
 4. Using DataProvider standalone (no UI) for scripted data access.
 
 Run individual sections with ``# %%`` in VS Code (Jupyter-style cells).
@@ -111,7 +111,7 @@ def __init__(self, data_store: dict, **params):
         self._cat = DataCatalog().add_source(data_store)
 
     @property
-    def catalog(self) -> DataCatalog:
+    def data_catalog(self) -> DataCatalog:
         return self._cat
 
     def build_station_name(self, r: pd.Series) -> str:
@@ -158,7 +158,7 @@ def build_station_name(self, r: pd.Series) -> str:
 #
 #     # ── DataProvider (data layer) ──────────────────────────────────────────
 #     @property
-#     def catalog(self) -> DataCatalog:
+#     def data_catalog(self) -> DataCatalog:
 #         return self._catalog
 #
 #     def build_station_name(self, r):