Add flexible metadata system

.gitignore

@@ -19,6 +19,10 @@ build
 # VSCode
 .vscode
 
+# Virtual environments
+.venv
+.env
+
 # Testing
 .tox
 .coverage
@@ -34,5 +38,6 @@ htmlcov
 
 # Folders that are temporarily created when building the documentation
 docs/_autosummary
+docs/_build
 docs/examples
 docs/sdk

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
 - API diagram in user guide
+- `Metadata` and `MeasurableMetadata` classes providing optional information for BayBE
+  objects
+- `Objective` now has a `metadata` attribute as well as a `description` property
+- `Target` and `Parameter` now have a `metadata` attribute as well as `description` and
+  `unit` properties
 
 ### Fixed
 - `Campaign` no longer allows overlapping names between parameters and targets

CONTRIBUTORS.md

@@ -31,4 +31,6 @@
 - Fabian Liebig (Merck KGaA, Darmstadt, Germany):\
   Benchmarking structure and persistence capabilities for benchmarking results
 - Alexander Wieczorek (Swiss Federal Institute for Materials Science and Technology, Dübendorf, Switzerland):\
-  SHAP explainers for insights
+  SHAP explainers for insights
+- Tobias Plötz (Merck KGaA, Darmstadt, Germany):\
+  Metadata system

baybe/objectives/base.py

@@ -6,7 +6,7 @@
 
 import cattrs
 import pandas as pd
-from attrs import define
+from attrs import define, field
 
 from baybe.serialization.core import (
     converter,
@@ -15,6 +15,7 @@
 )
 from baybe.serialization.mixin import SerialMixin
 from baybe.targets.base import Target
+from baybe.utils.metadata import Metadata, to_metadata
 
 # TODO: Reactive slots in all classes once cached_property is supported:
 #   https://github.com/python-attrs/attrs/issues/164
@@ -27,6 +28,18 @@ class Objective(ABC, SerialMixin):
     is_multi_output: ClassVar[bool]
     """Class variable indicating if the objective produces multiple outputs."""
 
+    metadata: Metadata = field(
+        factory=Metadata,
+        converter=lambda x: to_metadata(x, Metadata),
+        kw_only=True,
+    )
+    """Optional metadata containing description and other information."""
+
+    @property
+    def description(self) -> str | None:
+        """The description of the objective."""
+        return self.metadata.description
+
     @property
     @abstractmethod
     def targets(self) -> tuple[Target, ...]:

baybe/parameters/__init__.py

@@ -12,12 +12,14 @@
     NumericalDiscreteParameter,
 )
 from baybe.parameters.substance import SubstanceParameter
+from baybe.utils.metadata import MeasurableMetadata
 
 __all__ = [
     "CategoricalEncoding",
     "CategoricalParameter",
     "CustomDiscreteParameter",
     "CustomEncoding",
+    "MeasurableMetadata",
     "NumericalContinuousParameter",
     "NumericalDiscreteParameter",
     "SubstanceEncoding",

baybe/parameters/base.py

@@ -22,6 +22,7 @@
     unstructure_base,
 )
 from baybe.utils.basic import to_tuple
+from baybe.utils.metadata import MeasurableMetadata, to_metadata
 
 if TYPE_CHECKING:
     from baybe.searchspace.continuous import SubspaceContinuous
@@ -48,6 +49,13 @@ class Parameter(ABC, SerialMixin):
     name: str = field(validator=(instance_of(str), min_len(1)))
     """The name of the parameter"""
 
+    metadata: MeasurableMetadata = field(
+        factory=MeasurableMetadata,
+        converter=lambda x: to_metadata(x, MeasurableMetadata),
+        kw_only=True,
+    )
+    """Optional metadata containing description, unit, and other information."""
+
     @abstractmethod
     def is_in_range(self, item: Any) -> bool:
         """Return whether an item is within the parameter range.
@@ -88,6 +96,16 @@ def to_searchspace(self) -> SearchSpace:
     def summary(self) -> dict:
         """Return a custom summarization of the parameter."""
 
+    @property
+    def description(self) -> str | None:
+        """The description of the parameter."""
+        return self.metadata.description
+
+    @property
+    def unit(self) -> str | None:
+        """The unit of measurement for the parameter."""
+        return self.metadata.unit
+
 
 @define(frozen=True, slots=False)
 class DiscreteParameter(Parameter, ABC):

baybe/parameters/enum.py

@@ -27,7 +27,7 @@ class CustomEncoding(ParameterEncoding):
 class SubstanceEncoding(ParameterEncoding):
     """Available encodings for substance parameters from `scikit-fingerprints`_ package.
 
-    .. _scikit-fingerprints: https://scikit-fingerprints.github.io/scikit-fingerprints/
+    .. _scikit-fingerprints: https://scikit-fingerprints.readthedocs.io/
     """
 
     ATOMPAIR = "ATOMPAIR"

baybe/targets/__init__.py

@@ -3,9 +3,11 @@
 from baybe.targets.binary import BinaryTarget
 from baybe.targets.enum import TargetMode, TargetTransformation
 from baybe.targets.numerical import NumericalTarget
+from baybe.utils.metadata import MeasurableMetadata
 
 __all__ = [
     "BinaryTarget",
+    "MeasurableMetadata",
     "NumericalTarget",
     "TargetMode",
     "TargetTransformation",

baybe/targets/base.py

@@ -16,6 +16,7 @@
     get_base_structure_hook,
     unstructure_base,
 )
+from baybe.utils.metadata import MeasurableMetadata, to_metadata
 
 if TYPE_CHECKING:
     from baybe.objectives import SingleTargetObjective
@@ -31,6 +32,23 @@ class Target(ABC, SerialMixin):
     name: str = field()
     """The name of the target."""
 
+    metadata: MeasurableMetadata = field(
+        factory=MeasurableMetadata,
+        converter=lambda x: to_metadata(x, MeasurableMetadata),
+        kw_only=True,
+    )
+    """Optional metadata containing description, unit, and other information."""
+
+    @property
+    def description(self) -> str | None:
+        """The description of the target."""
+        return self.metadata.description
+
+    @property
+    def unit(self) -> str | None:
+        """The unit of measurement for the target."""
+        return self.metadata.unit
+
     def to_objective(self) -> SingleTargetObjective:
         """Create a single-task objective from the target."""
         from baybe.objectives.single import SingleTargetObjective

baybe/utils/metadata.py

@@ -0,0 +1,118 @@
+"""Generic metadata system for BayBE objects."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import cattrs
+from attrs import AttrsInstance, define, field, fields
+from attrs.validators import deep_mapping, instance_of
+from attrs.validators import optional as optional_v
+from typing_extensions import override
+
+from baybe.serialization import SerialMixin, converter
+from baybe.utils.basic import classproperty
+
+_TMetaData = TypeVar("_TMetaData", bound="Metadata")
+
+
+@define(frozen=True)
+class Metadata(SerialMixin):
+    """Metadata class providing basic information for BayBE objects."""
+
+    description: str | None = field(
+        default=None, validator=optional_v(instance_of(str))
+    )
+    """A description of the object."""
+
+    misc: dict[str, Any] = field(
+        factory=dict,
+        validator=deep_mapping(
+            mapping_validator=instance_of(dict),
+            key_validator=instance_of(str),
+            # FIXME: https://github.com/python-attrs/attrs/issues/1246
+            value_validator=lambda *x: None,
+        ),
+        kw_only=True,
+    )
+    """Additional user-defined metadata."""
+
+    @misc.validator
+    def _validate_misc(self, _, value: dict[str, Any]) -> None:
+        if inv := set(value).intersection(self._explicit_fields):
+            raise ValueError(
+                f"Miscellaneous metadata cannot contain the following fields: {inv}. "
+                f"Use the corresponding attributes instead."
+            )
+
+    @classproperty
+    def _explicit_fields(cls: type[AttrsInstance]) -> set[str]:
+        """The explicit metadata fields."""  # noqa: D401
+        flds = fields(cls)
+        return {fld.name for fld in flds if fld.name != flds.misc.name}
+
+    @property
+    def is_empty(self) -> bool:
+        """Check if metadata contains any meaningful information."""
+        return self.description is None and not self.misc
+
+
+@define(frozen=True)
+class MeasurableMetadata(Metadata):
+    """Class providing metadata for BayBE :class:`Parameter` objects."""
+
+    unit: str | None = field(default=None, validator=optional_v(instance_of(str)))
+    """The unit of measurement for the parameter."""
+
+    @override
+    @property
+    def is_empty(self) -> bool:
+        """Check if metadata contains any meaningful information."""
+        return super().is_empty and self.unit is None
+
+
+def to_metadata(
+    value: dict[str, Any] | _TMetaData, cls: type[_TMetaData], /
+) -> _TMetaData:
+    """Convert a dictionary to :class:`Metadata` (with :class:`Metadata` passthrough).
+
+    Args:
+        value: The metadata input.
+        cls: The specific :class:`Metadata` subclass to convert to.
+
+    Returns:
+        The created metadata instance of the requested :class:`Metadata` subclass.
+
+    Raises:
+        TypeError: If the input is not a dictionary or of the specified
+            :class:`Metadata` type.
+    """
+    if isinstance(value, cls):
+        return value
+
+    if not isinstance(value, dict):
+        raise TypeError(
+            f"The input must be a dictionary or a '{cls.__name__}' instance. "
+            f"Got: {type(value)}"
+        )
+
+    # Separate known fields from unknown ones
+    return converter.structure(value, cls)
+
+
+@converter.register_structure_hook
+def _separate_metadata_fields(dct: dict[str, Any], cls: type[Metadata]) -> Metadata:
+    """Separate known fields from miscellaneous metadata."""
+    dct = dct.copy()
+    explicit = {fld: dct.pop(fld, None) for fld in cls._explicit_fields}
+    return cls(**explicit, misc=dct)
+
+
+@converter.register_unstructure_hook
+def _flatten_misc_metadata(metadata: Metadata) -> dict[str, Any]:
+    """Flatten the metadata for serialization."""
+    cls = type(metadata)
+    fn = cattrs.gen.make_dict_unstructure_fn(cls, converter)
+    dct = fn(metadata)
+    dct = dct | dct.pop(fields(Metadata).misc.name)
+    return dct

docs/conf.py

@@ -263,7 +263,7 @@
     "python": ("https://docs.python.org/3", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
     "polars": ("https://docs.pola.rs/api/python/stable/", None),
-    "skfp": ("https://scikit-fingerprints.github.io/scikit-fingerprints/", None),
+    "skfp": ("https://scikit-fingerprints.readthedocs.io/latest/", None),
     "sklearn": ("https://scikit-learn.org/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "torch": ("https://pytorch.org/docs/main/", None),

docs/userguide/parameters.md

@@ -5,7 +5,7 @@
 [`TaskParameter`]: baybe.parameters.categorical.TaskParameter
 [`CustomDiscreteParameter`]: baybe.parameters.custom.CustomDiscreteParameter
 [`SubstanceEncoding`]: baybe.parameters.enum.SubstanceEncoding
-[scikit-fingerprints]: https://scikit-fingerprints.github.io/scikit-fingerprints/
+[scikit-fingerprints]: https://scikit-fingerprints.readthedocs.io
 
 # Parameters
 

tests/hypothesis_strategies/metadata.py

@@ -0,0 +1,40 @@
+"""Hypothesis strategies for metadata."""
+
+import hypothesis.strategies as st
+from hypothesis import assume
+
+from baybe.utils.metadata import MeasurableMetadata, Metadata
+
+_descriptions = st.one_of(st.none(), st.text(min_size=0))
+"""A strategy generating metadata descriptions."""
+
+
+@st.composite
+def _miscs(draw: st.DrawFn, cls: type[Metadata]):
+    """Generates miscellaneous metadata for various metadata classes."""
+    misc = draw(
+        st.dictionaries(
+            st.text(min_size=0),
+            st.one_of(st.text(), st.integers(), st.floats(allow_nan=False)),
+            max_size=5,
+        )
+    )
+    assume(not cls._explicit_fields.intersection(misc))
+    return misc
+
+
+@st.composite
+def metadata(draw: st.DrawFn):
+    """Generate :class:`baybe.utils.metadata.Metadata`."""
+    description = draw(_descriptions)
+    misc = draw(_miscs(Metadata))
+    return Metadata(description=description, misc=misc)
+
+
+@st.composite
+def measurable_metadata(draw: st.DrawFn):
+    """Generate :class:`baybe.parameters.base.MeasurableMetadata`."""
+    description = draw(_descriptions)
+    unit = draw(st.one_of(st.none(), st.text(min_size=0)))
+    misc = draw(_miscs(MeasurableMetadata))
+    return MeasurableMetadata(description=description, unit=unit, misc=misc)