tpcp 2.2.1__tar.gz → 2.3.0__tar.gz

{tpcp-2.2.1 → tpcp-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tpcp
-Version: 2.2.1
+Version: 2.3.0
 Summary: Pipeline and Dataset helpers for complex algorithm evaluation.
 Author: Arne Küderle, Robert Richer, Raul C. Sîmpetru, Björn Eskofier
 Author-email: Arne Küderle <arne.kuederle@fau.de>, Robert Richer <robert.richer@fau.de>, Raul C. Sîmpetru <raul.simpetru@fau.de>, Björn Eskofier <bjoern.eskofier@fau.de>

{tpcp-2.2.1 → tpcp-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tpcp"
-version = "2.2.1"
+version = "2.3.0"
 description = "Pipeline and Dataset helpers for complex algorithm evaluation."
 authors = [
     { name = "Arne Küderle", email = "arne.kuederle@fau.de" },
@@ -36,11 +36,22 @@ tpcp = "tpcp._cli:main"
 tpcp_snapshots = "tpcp.testing._regression_utils"
 
 [dependency-groups]
-dev = [
-    "pydata-sphinx-theme>=0.14.1,<0.15",
+test = [
+    "attrs>=22.1.0",
+    "matplotlib>=3.4.3,<4",
+    "numpydoc>=1.4.0,<2",
+    "optuna>=2.10",
     "pytest>=8.4.2,<9",
+    "pytest-xdist>=3.8.0,<4",
+]
+coverage = [
     "pytest-cov>=7.0.0,<8",
-    "poethepoet>=0.10.0,<0.11",
+]
+lint = [
+    "ruff>=0.14.0,<0.15",
+]
+docs = [
+    "pydata-sphinx-theme>=0.14.1,<0.15",
     "pyright>=1.1.230,<2",
     "numpydoc>=1.4.0,<2",
     "sphinx-gallery>=0.14.0,<0.15",
@@ -49,8 +60,13 @@ dev = [
     "matplotlib>=3.4.3,<4",
     "toml>=0.10.2,<0.11",
     "Sphinx>=7.2.6,<8",
-    "ruff>=0.14.0,<0.15",
-    "tensorflow-cpu>=2.18.0rc2,<3; python_full_version < '3.14'",
+]
+dev = [
+    { include-group = "test" },
+    { include-group = "coverage" },
+    { include-group = "lint" },
+    { include-group = "docs" },
+    "poethepoet>=0.10.0,<0.11",
 ]
 
 [tool.uv]
@@ -82,7 +98,7 @@ lint = { cmd = "ruff check src/tpcp --fix", help = "Lint all files with ruff." }
 _lint_ci = "ruff check src/tpcp --output-format=github"
 _check_format = "ruff format . --check"
 ci_check = { sequence = ["_check_format", "_lint_ci"], help = "Check all potential format and linting issues." }
-test = { cmd = "pytest ./tests --cov=tpcp --cov-report=term-missing --cov-report=xml", help = "Run Pytest with coverage." }
+test = { cmd = "pytest ./tests -n 2 --dist=worksteal --cov=tpcp --cov-report=term-missing --cov-report=xml", help = "Run Pytest with coverage." }
 docs = { "script" = "_tasks:task_docs()",  help = "Build the html docs using Sphinx." }
 docs_clean = { "script" = "_tasks:task_docs(clean=True)",  help = "Remove all old build files and build a clean version of the docs." }
 docs_preview = { cmd = "python -m http.server --directory docs/_build/html", help = "Preview the built html docs." }

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/__init__.py

@@ -11,7 +11,7 @@ from tpcp._algorithm_utils import (
     make_optimize_safe,
 )
 from tpcp._base import NOTHING, BaseFactory, BaseTpcpObject, CloneFactory, cf, clone, get_param_names
-from tpcp._dataset import Dataset
+from tpcp._dataset import Dataset, DatasetWrapperMixin
 from tpcp._parameters import (
     HyperPara,
     HyperParameter,
@@ -24,7 +24,7 @@ from tpcp._parameters import (
 )
 from tpcp._pipeline import OptimizablePipeline, Pipeline
 
-__version__ = "2.2.1"
+__version__ = "2.3.0"
 
 
 __all__ = [
@@ -34,6 +34,7 @@ __all__ = [
     "BaseTpcpObject",
     "CloneFactory",
     "Dataset",
+    "DatasetWrapperMixin",
     "HyperPara",
     "HyperParameter",
     "OptiPara",

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/_dataset.py

@@ -3,7 +3,7 @@
 import warnings
 from collections.abc import Iterator, Sequence
 from keyword import iskeyword
-from typing import Generic, Optional, TypeVar, Union, cast, get_args, overload
+from typing import ClassVar, Generic, Optional, TypeVar, Union, cast, get_args, get_origin, overload
 
 import numpy as np
 import pandas as pd
@@ -125,7 +125,7 @@ class _Dataset(BaseTpcpObject, Generic[GroupLabelT]):
             )
 
         # Get the generic type of the dataset
-        group_label_type = get_args(type(self).__orig_bases__[0])[0]
+        group_label_type = self._get_group_label_type()
         # If group label type is a named tuple, we check that the keys are the same as the index columns
         if (label_fields := getattr(group_label_type, "_fields", None)) and label_fields != (
             index_cols := tuple(index_1.columns)
@@ -155,7 +155,7 @@ class _Dataset(BaseTpcpObject, Generic[GroupLabelT]):
 
         For some examples and additional explanation see this :ref:`example <custom_dataset_basics>`.
         """
-        if getattr(group_label_type := get_args(type(self).__orig_bases__[0])[0], "_fields", None):
+        if getattr(group_label_type := self._get_group_label_type(), "_fields", None):
             nd_tuple_name = group_label_type.__name__
         else:
             nd_tuple_name = type(self).__name__ + "GroupLabel"
@@ -198,7 +198,7 @@ class _Dataset(BaseTpcpObject, Generic[GroupLabelT]):
 
     def index_as_tuples(self) -> list[GroupLabelT]:
         """Get all datapoint labels of the dataset (i.e. a list of the rows of the index as named tuples)."""
-        if getattr(group_label_type := get_args(type(self).__orig_bases__[0])[0], "_fields", None):
+        if getattr(group_label_type := self._get_group_label_type(), "_fields", None):
             # If a generic is provided, we actually convert the named tuples.
             return [group_label_type(*row) for row in self.index.itertuples(index=False)]
         return list(self.index.itertuples(index=False, name=type(self).__name__ + "GroupLabel"))
@@ -234,11 +234,22 @@ class _Dataset(BaseTpcpObject, Generic[GroupLabelT]):
             ) from e
 
     def _get_groupby_columns(self) -> list[str]:
-        """Get the groupby columns."""
+        """Get the groupby columns after materializing the dataset index."""
+        # `create_index` may establish the grouping based on the materialized index.
+        index = self.index
         if self.groupby_cols is None:
-            return self.index.columns.to_list()
+            return index.columns.to_list()
         return _ensure_is_list(self.groupby_cols)
 
+    def _get_group_label_type(self):
+        """Find the concrete group-label type in the dataset inheritance hierarchy."""
+        for cls in type(self).__mro__:
+            for generic_base in getattr(cls, "__orig_bases__", ()):
+                origin = get_origin(generic_base)
+                if isinstance(origin, type) and issubclass(origin, _Dataset) and (args := get_args(generic_base)):
+                    return args[0]
+        return None
+
     def _get_unique_groups(self) -> Union[pd.MultiIndex, pd.Index]:
         return self.grouped_index.index.unique()
 
@@ -750,6 +761,81 @@ class Dataset(_Dataset[GroupLabelT], Generic[GroupLabelT]):
         return DatasetAt
 
 
+WrappedDatasetT = TypeVar("WrappedDatasetT", bound="_Dataset")
+
+
+class DatasetWrapperMixin(Generic[WrappedDatasetT]):
+    """Provide common behavior for datasets that wrap another dataset.
+
+    This mixin expands the index of ``wrapped_dataset`` through
+    :meth:`_create_wrapped_index`, links the wrapper's initial grouping to the
+    wrapped dataset, and resolves the source datapoint represented by a wrapper
+    datapoint through :attr:`wrapped_datapoint`.
+
+    The mixin deliberately does not inherit from :class:`Dataset`. A concrete
+    wrapper must inherit from both this mixin and the domain-specific dataset
+    interface implemented by the wrapped dataset.
+
+    .. important::
+        ``DatasetWrapperMixin`` must be listed **before** the dataset base class.
+        The order controls Python's method resolution order and ensures that this
+        mixin's :meth:`create_index` implementation is used. Reversing the bases
+        raises a :class:`TypeError` when the wrapper class is defined.
+
+    Examples
+    --------
+    The mixin comes first and the shared dataset interface comes second::
+
+        class AugmentedDataset(
+            DatasetWrapperMixin[SourceDataset],
+            SourceDataset,
+        ):
+            _wrapper_groupby_cols = ("augmentation",)
+
+            def _create_wrapped_index(self, source_index): ...
+
+    """
+
+    wrapped_dataset: WrappedDatasetT
+    _wrapper_groupby_cols: ClassVar[tuple[str, ...]]
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        """Validate that the mixin precedes the dataset base in the MRO."""
+        super().__init_subclass__(**kwargs)
+        mro = cls.__mro__
+        if _Dataset in mro and mro.index(DatasetWrapperMixin) > mro.index(_Dataset):
+            raise TypeError(
+                "DatasetWrapperMixin must be listed before the Dataset base class so its create_index method takes "
+                "precedence in the method resolution order."
+            )
+
+    def create_index(self) -> pd.DataFrame:
+        """Create the wrapper index and link its initial grouping to the wrapped dataset."""
+        source_index = self.wrapped_dataset.index.copy()
+        dataset = cast("_Dataset", self)
+
+        if dataset.groupby_cols is None:
+            dataset.groupby_cols = [*self.wrapped_dataset._get_groupby_columns(), *self._wrapper_groupby_cols]
+
+        return self._create_wrapped_index(source_index)
+
+    def _create_wrapped_index(self, source_index: pd.DataFrame) -> pd.DataFrame:
+        """Create the wrapper index from a copy of the wrapped dataset index."""
+        raise NotImplementedError
+
+    @property
+    def wrapped_datapoint(self) -> WrappedDatasetT:
+        """Return the wrapped datapoint represented by the current wrapper group."""
+        dataset = cast("_Dataset", self)
+        dataset.assert_is_single_group("wrapped_datapoint")
+
+        source_columns = self.wrapped_dataset.index.columns.to_list()
+        source_index = pd.DataFrame(dataset.index.loc[:, source_columns]).drop_duplicates().reset_index(drop=True)
+        source_groupby = [column for column in dataset._get_groupby_columns() if column in source_columns]
+
+        return self.wrapped_dataset.get_subset(index=source_index).groupby(source_groupby or None)
+
+
 T = TypeVar("T")
 
 

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/_utils/_score.py

@@ -17,6 +17,7 @@ from tpcp._base import clone
 from tpcp._hash import custom_hash
 from tpcp._utils._general import _get_nested_paras
 from tpcp.exceptions import OptimizationError, TestError
+from tpcp.misc import warning_error_context
 
 if TYPE_CHECKING:
     from tpcp._dataset import Dataset
@@ -62,7 +63,6 @@ def _score(
     return_parameters=False,
     return_data_labels=False,
     return_times=False,
-    error_info: Optional[str] = None,
 ) -> _ScoreResults:
     """Set parameters and return score.
 
@@ -104,15 +104,15 @@ def _score(
 
         pipeline = pipeline.set_params(**parameters)
 
-    try:
-        start_time = time.time()
-        agg_scores, single_scores = scorer(pipeline, dataset)
-        score_time = time.time() - start_time
-    except Exception as e:
-        raise TestError(
-            f"Testing the algorithm on the dataset failed with the error above.\n{error_info or ''}\n\n"
-            f"The test-set is:\n{[d.group_labels for d in dataset]}"
-        ) from e
+    score_context: dict[str, Any] = {}
+    with warning_error_context("score", context_provider=lambda: score_context):
+        try:
+            start_time = time.time()
+            score_context = {"data_labels": dataset.group_labels}
+            agg_scores, single_scores = scorer(pipeline, dataset)
+            score_time = time.time() - start_time
+        except Exception as e:
+            raise TestError("Testing failed.") from e
 
     result: _ScoreResults = {
         "scores": agg_scores,
@@ -142,7 +142,6 @@ def _optimize_and_score(
     return_data_labels=False,
     return_times=False,
     memory: Optional[Memory] = None,
-    error_info: Optional[str] = None,
 ) -> _OptimizeScoreResults:
     """Optimize and score the optimized pipeline on the train and test data, respectively.
 
@@ -177,17 +176,17 @@ def _optimize_and_score(
 
     optimize_params_clean: dict = optimize_params or {}
 
-    try:
-        start_time = time.time()
-        optimizer = _cached_optimize(
-            optimizer, train_set, hyperparameters, pure_parameters, memory, optimize_params_clean
-        )
-        optimize_time = time.time() - start_time
-    except Exception as e:
-        raise OptimizationError(
-            f"The optimization on the trainset failed with the error above.\n{error_info or ''}\n\n"
-            f"This optimization used the following trainset:\n{train_set}"
-        ) from e
+    optimize_context: dict[str, Any] = {}
+    with warning_error_context("optimize", context_provider=lambda: optimize_context):
+        try:
+            start_time = time.time()
+            optimize_context = {"data_labels": train_set.group_labels}
+            optimizer = _cached_optimize(
+                optimizer, train_set, hyperparameters, pure_parameters, memory, optimize_params_clean
+            )
+            optimize_time = time.time() - start_time
+        except Exception as e:
+            raise OptimizationError("Optimization failed.") from e
 
     # Now we set the remaining paras.
     # Because, we need to set the parameters on the optimized pipeline and not the input pipeline we strip the
@@ -198,28 +197,27 @@ def _optimize_and_score(
     # beginning.
     optimizer = optimizer.set_params(**pure_parameters)
 
-    try:
-        agg_scores, single_scores = scorer(optimizer.optimized_pipeline_, test_set)
-        score_time = time.time() - optimize_time - start_time
-    except Exception as e:
-        raise TestError(
-            f"Testing the optimized algorithm on the test-set failed with the error above.\n{error_info or ''}\n\n"
-            f"The test-set is:\n{test_set}"
-        ) from e
+    test_score_context: dict[str, Any] = {}
+    with warning_error_context("test_score", context_provider=lambda: test_score_context):
+        try:
+            test_score_context = {"data_labels": test_set.group_labels}
+            agg_scores, single_scores = scorer(optimizer.optimized_pipeline_, test_set)
+            score_time = time.time() - optimize_time - start_time
+        except Exception as e:
+            raise TestError("Testing failed.") from e
 
     result: _OptimizeScoreResults = {
         "test__scores": agg_scores,
         "test__single__scores": single_scores,
     }
     if return_train_score:
-        try:
-            train_agg_scores, train_single_scores = scorer(optimizer.optimized_pipeline_, train_set)
-        except Exception as e:
-            raise TestError(
-                "Running the optimized algorithm on the train-set to calculate the train error failed with the error "
-                f"above.\n{error_info or ''}\n\n"
-                f"The train-set is:\n{[d.group_labels for d in test_set]}"
-            ) from e
+        train_score_context: dict[str, Any] = {}
+        with warning_error_context("train_score", context_provider=lambda: train_score_context):
+            try:
+                train_score_context = {"data_labels": train_set.group_labels}
+                train_agg_scores, train_single_scores = scorer(optimizer.optimized_pipeline_, train_set)
+            except Exception as e:
+                raise TestError("Testing failed.") from e
         result["train__scores"] = train_agg_scores
         result["train__single__scores"] = train_single_scores
     if return_times:

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/caching.py

@@ -14,7 +14,7 @@ from joblib import Memory
 
 from tpcp import Algorithm, get_action_methods_names, get_results, make_action_safe
 from tpcp._hash import custom_hash
-from tpcp.parallel import register_global_parallel_callback, remove_global_parallel_callback
+from tpcp.parallel import _register_tpcp_global_parallel_callback, _remove_tpcp_global_parallel_callback
 
 _ALREADY_WARNED = False
 
@@ -130,7 +130,7 @@ def _register_global_parallel_callback(func, name):
     def _callback():
         return None, wrapper
 
-    register_global_parallel_callback(_callback, name=name)
+    _register_tpcp_global_parallel_callback(name, _callback)
 
 
 def global_disk_cache(  # noqa: C901
@@ -313,7 +313,9 @@ def remove_disk_cache(algorithm_object: type[Algorithm]):
         if getattr(action_method, "__wrapped__", None) is not None:
             setattr(algorithm_object, action_name, action_method.__wrapped__)
             with contextlib.suppress(KeyError):
-                remove_global_parallel_callback(f"global_disk_cache__{algorithm_object.__qualname__}__{action_name}")
+                _remove_tpcp_global_parallel_callback(
+                    f"global_disk_cache__{algorithm_object.__qualname__}__{action_name}"
+                )
     return algorithm_object
 
 
@@ -453,7 +455,7 @@ def remove_ram_cache(algorithm_object: type[Algorithm]):
         if getattr(action_method, "__wrapped__", None) is not None:
             setattr(algorithm_object, action_method_name, action_method.__wrapped__)
             with contextlib.suppress(KeyError):
-                remove_global_parallel_callback(
+                _remove_tpcp_global_parallel_callback(
                     f"global_ram_cache__{algorithm_object.__qualname__}__{action_method_name}"
                 )
 

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/misc/__init__.py

@@ -3,12 +3,24 @@
 from tpcp._hash import custom_hash
 from tpcp.misc._class_utils import classproperty, set_defaults
 from tpcp.misc._typed_iterator import BaseTypedIterator, TypedIterator, TypedIteratorResultTuple
+from tpcp.misc._warning_error_context import (
+    WarningErrorContext,
+    WarningErrorContextRecord,
+    iter_with_warning_error_context,
+    print_with_context,
+    warning_error_context,
+)
 
 __all__ = [
     "BaseTypedIterator",
     "TypedIterator",
     "TypedIteratorResultTuple",
+    "WarningErrorContext",
+    "WarningErrorContextRecord",
     "classproperty",
     "custom_hash",
+    "iter_with_warning_error_context",
+    "print_with_context",
     "set_defaults",
+    "warning_error_context",
 ]

{tpcp-2.2.1 → tpcp-2.3.0}/src/tpcp/misc/_typed_iterator.py

@@ -1,11 +1,13 @@
 import warnings
-from collections.abc import Iterable, Iterator, Sequence
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 from dataclasses import fields, is_dataclass
-from typing import Any, Callable, Generic, Optional, TypeVar
+from typing import Any, Generic, Optional, TypeVar
 
 from typing_extensions import NamedTuple, TypeAlias
 
 from tpcp import Algorithm, cf
+from tpcp.misc._warning_error_context import WarningErrorContext
+from tpcp.misc._warning_error_context import warning_error_context as _warning_error_context
 
 DataclassT = TypeVar("DataclassT")
 InputTypeT = TypeVar("InputTypeT")
@@ -26,6 +28,7 @@ class _NotSet:
 
 
 _NULL_VALUE = _NotSet()
+_NO_PREVIOUS_ITERATION_INDEX = object()
 
 
 class BaseTypedIterator(Algorithm, Generic[InputTypeT, DataclassT]):
@@ -159,6 +162,10 @@ class BaseTypedIterator(Algorithm, Generic[InputTypeT, DataclassT]):
             The result object is a dataclass instance of the type defined in ``self.data_type``.
             All values of the result object are set to ``TypedIterator.NULL_VALUE`` by default.
 
+            To add context to warnings and exceptions from the loop body, explicitly enter
+            :meth:`warning_error_context` inside the loop. Context must not remain active across this generator's
+            ``yield`` boundary.
+
         """
         if not is_dataclass(self.data_type):
             raise TypeError(f"Expected a dataclass as data_type, got {self.data_type}")
@@ -173,13 +180,55 @@ class BaseTypedIterator(Algorithm, Generic[InputTypeT, DataclassT]):
             self._raw_results = []
 
         self.done_[iteration_name] = False
-        for d in iterable:
+        for i, d in enumerate(iterable):
             result_object = self._get_new_empty_object()
-            result_tuple = TypedIteratorResultTuple(iteration_name, d, result_object, iteration_context or {})
+            iteration_context = iteration_context or {}
+            result_tuple = TypedIteratorResultTuple(iteration_name, d, result_object, iteration_context)
             self._report_new_result(result_tuple)
-            yield d, result_object
+            previous_i = getattr(self, "_warning_error_context_i", _NO_PREVIOUS_ITERATION_INDEX)
+            self._warning_error_context_i = i
+            try:
+                yield d, result_object
+            finally:
+                if previous_i is _NO_PREVIOUS_ITERATION_INDEX:
+                    del self._warning_error_context_i
+                else:
+                    self._warning_error_context_i = previous_i
         self.done_[iteration_name] = True
 
+    def warning_error_context(
+        self,
+        name: str,
+        context: Optional[dict[str, Any]] = None,
+        /,
+        *,
+        context_provider: Optional[Callable[[], Mapping[str, Any]]] = None,
+        record_only: bool = False,
+    ) -> WarningErrorContext:
+        """Create explicit warning/error context for an iteration body.
+
+        This convenience method has the same interface as
+        :func:`~tpcp.misc.warning_error_context` and adds the current zero-based
+        iteration index as ``i``. It deliberately does not infer any other context
+        from the iterator or its current item. Enter the returned context manager
+        inside the iteration body and pass all other relevant context explicitly.
+        """
+        context = {} if context is None else context
+        if "i" in context:
+            raise ValueError("The context key 'i' is reserved by TypedIterator.")
+        try:
+            i = self._warning_error_context_i
+        except AttributeError as exc:
+            raise RuntimeError(
+                "warning_error_context must be called inside an active TypedIterator loop body."
+            ) from exc
+        return _warning_error_context(
+            name,
+            {"i": i, **context},
+            context_provider=context_provider,
+            record_only=record_only,
+        )
+
     def _get_new_empty_object(self) -> DataclassT:
         init_dict = {k.name: self.NULL_VALUE for k in fields(self.data_type)}
         return self.data_type(**init_dict)