tpcp 3.2.0__tar.gz → 3.3.0__tar.gz

{tpcp-3.2.0 → tpcp-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tpcp
-Version: 3.2.0
+Version: 3.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-3.2.0 → tpcp-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tpcp"
-version = "3.2.0"
+version = "3.3.0"
 description = "Pipeline and Dataset helpers for complex algorithm evaluation."
 requires-python = ">=3.11,<4.0"
 readme = "README.md"

{tpcp-3.2.0 → tpcp-3.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "tpcp"
-version = "3.2.0"
+version = "3.3.0"
 description = "Pipeline and Dataset helpers for complex algorithm evaluation."
 authors = [
     { name = "Arne Küderle", email = "arne.kuederle@fau.de" },

{tpcp-3.2.0 → tpcp-3.3.0}/src/tpcp/__init__.py

@@ -24,7 +24,7 @@ from tpcp._parameters import (
 )
 from tpcp._pipeline import OptimizablePipeline, Pipeline
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"
 
 
 __all__ = [

{tpcp-3.2.0 → tpcp-3.3.0}/src/tpcp/validate/__init__.py

@@ -1,6 +1,6 @@
 """Module for all helper methods to evaluate algorithms."""
 
-from tpcp.validate._composed_splitters import CombinedSplitter, NoSplit
+from tpcp.validate._composed_splitters import CombinedSplitter, NoSplit, SubsetSplitter
 from tpcp.validate._cross_val_helper import BaseDatasetSplitter, DatasetSplitter
 from tpcp.validate._scorer import (
     Aggregator,
@@ -23,6 +23,7 @@ __all__ = [
     "NoSplit",
     "Scorer",
     "ScorerTypes",
+    "SubsetSplitter",
     "cross_validate",
     "mean_agg",
     "no_agg",

{tpcp-3.2.0 → tpcp-3.3.0}/src/tpcp/validate/_composed_splitters.py

@@ -71,61 +71,115 @@ class NoSplit(BaseDatasetSplitter):
             yield train.copy(), test.copy()
 
 
+class SubsetSplitter(BaseDatasetSplitter):
+    """Select a subset of the current dataset, then split it into train/test group labels.
+
+    This is a dataset splitter itself, usable directly as ``cv`` or as a named child of
+    :class:`CombinedSplitter`. The selector is evaluated for each ``get_n_splits`` or ``split``
+    call, so it should return the same subset for the same input when the calls are paired.
+
+    Parameters
+    ----------
+    selector
+        Callable receiving the current dataset and returning a subset whose group labels belong to it.
+    splitter
+        A native tpcp splitter or any input accepted by :class:`DatasetSplitter`, including raw sklearn
+        splitters and explicit lists of positional folds. Raw inputs are adapted to group labels
+        when used. Pass :class:`DatasetSplitter` explicitly when grouping or stratification by
+        dataset index columns is needed.
+    """
+
+    def __init__(self, selector: DatasetSelector, splitter: object) -> None:
+        self.selector = selector
+        self.splitter = splitter
+
+    def _prepare(self, dataset: Dataset) -> tuple[Dataset, BaseDatasetSplitter]:
+        selected = self.selector(dataset)
+        _validate_subset(dataset, selected)
+        return selected, _normalize_splitter(self.splitter)
+
+    def get_n_splits(self, dataset: Dataset) -> int | None:
+        """Return the child splitter's fold count for the selected subset."""
+        selected, splitter = self._prepare(dataset)
+        return splitter.get_n_splits(selected)
+
+    def split(
+        self, dataset: Dataset, n_splits: int | None = None
+    ) -> Iterator[tuple[list[GroupLabelT], list[GroupLabelT]]]:
+        """Select the subset and yield its train/test group labels."""
+        selected, splitter = self._prepare(dataset)
+        if n_splits is None:
+            yield from splitter.split(selected)
+        else:
+            yield from splitter.split(selected, n_splits=n_splits)
+
+
 class CombinedSplitter(BaseDatasetSplitter):
-    """Combine corresponding folds of splitters applied to selected dataset parts.
+    """Combine corresponding folds of named dataset splitters.
 
-    Pass a list of one or more ``(selector, splitter)`` pairs as ``parts``. Each selector receives the current
-    dataset and returns a subset. A child splitter can be a native tpcp splitter or any input
-    accepted by :class:`DatasetSplitter`, including raw sklearn splitters.
-    Positional fold assignments must be supplied as lists, including for raw child inputs.
+    Pass a list of one or more ``(name, splitter)`` pairs as ``parts``, where each child implements
+    :class:`BaseDatasetSplitter`. Use :class:`SubsetSplitter` to apply a child to a selected subset.
+    Names are unique strings without ``__``, following tpcp's composite parameter convention.
+    All children receive the current input dataset. Raw sklearn splitters and positional fold lists
+    can be used inside :class:`SubsetSplitter` or :class:`DatasetSplitter`.
 
     All specified fold counts must match, and at least one child must specify a count.
     Children that report ``None`` receive that count through their ``split`` method.
     All children must yield exactly that many folds. Train and test labels are
     deduplicated separately in first-occurrence order, and overlapping assignments
-    raise ``ValueError``. Selectors receive the current input dataset, including
-    within nested splits, and may return any dataset whose group labels belong to
-    that input.
+    raise ``ValueError``. Nested compositions operate on the dataset supplied by their parent.
 
     For example, cross-validate real recordings and always train on artificial recordings::
 
-        from tpcp.validate import CombinedSplitter, DatasetSplitter, NoSplit
+        from tpcp.validate import (
+            CombinedSplitter,
+            DatasetSplitter,
+            NoSplit,
+            SubsetSplitter,
+        )
 
         cv = CombinedSplitter(
             parts=[
                 (
-                    lambda ds: ds.get_subset(recording_type="real"),
-                    DatasetSplitter(5, groupby="participant"),
+                    "real",
+                    SubsetSplitter(
+                        lambda ds: ds.get_subset(recording_type="real"),
+                        DatasetSplitter(5, groupby="participant"),
+                    ),
                 ),
                 (
-                    lambda ds: ds.get_subset(recording_type="artificial"),
-                    NoSplit(None, train=lambda ds: ds),
+                    "artificial",
+                    NoSplit(
+                        None,
+                        train=lambda ds: ds.get_subset(recording_type="artificial"),
+                    ),
                 ),
             ],
         )
 
+        cv.set_params(parts__real__splitter__base_splitter=3)
+
+    Replace a whole child with ``set_params(parts__real=new_splitter)``, or update its nested parameters
+    with paths such as ``parts__real__selector`` or ``parts__artificial__train``. Adding or removing parts
+    requires replacing the entire ``parts`` list.
+
     Parameters
     ----------
     parts
-        A list of selector and splitter pairs, in the order their fold contributions are combined.
+        A composite parameter list of named :class:`BaseDatasetSplitter` objects, in the order their fold
+        contributions are combined. Migrate old ``(selector, splitter)`` entries to
+        ``(name, SubsetSplitter(selector, splitter))``.
     """
 
-    def __init__(self, parts: list[tuple[DatasetSelector, object]]) -> None:
+    _composite_params = ("parts",)
+
+    def __init__(self, parts: list[tuple[str, BaseDatasetSplitter]]) -> None:
         self.parts = parts
 
-    def _prepare(self, dataset: Dataset) -> list[tuple[Dataset, BaseDatasetSplitter]]:
+    def _fold_count(self, dataset: Dataset) -> tuple[int, list[int | None]]:
         if not self.parts:
-            raise ValueError("CombinedSplitter requires at least one selector and splitter pair.")
-        prepared = []
-        for selector, splitter in self.parts:
-            selected = selector(dataset)
-            _validate_subset(dataset, selected)
-            prepared.append((selected, _normalize_splitter(splitter)))
-        return prepared
-
-    @staticmethod
-    def _fold_count(prepared: list[tuple[Dataset, BaseDatasetSplitter]]) -> tuple[int, list[int | None]]:
-        reported = [splitter.get_n_splits(dataset) for dataset, splitter in prepared]
+            raise ValueError("CombinedSplitter requires at least one named dataset splitter.")
+        reported = [splitter.get_n_splits(dataset) for _, splitter in self.parts]
         counts = [count for count in reported if count is not None]
         if not counts:
             raise ValueError("CombinedSplitter requires at least one child to report an integer number of folds.")
@@ -134,19 +188,18 @@ class CombinedSplitter(BaseDatasetSplitter):
         return counts[0], reported
 
     def get_n_splits(self, dataset: Dataset) -> int:
-        """Return the shared number of folds after selecting each part."""
-        return self._fold_count(self._prepare(dataset))[0]
+        """Return the shared number of folds reported by the children."""
+        return self._fold_count(dataset)[0]
 
     def split(
         self, dataset: Dataset, n_splits: int | None = None
     ) -> Iterator[tuple[list[GroupLabelT], list[GroupLabelT]]]:
         """Yield deduplicated, disjoint train and test labels for corresponding child folds."""
-        prepared = self._prepare(dataset)
-        available, reported = self._fold_count(prepared)
+        available, reported = self._fold_count(dataset)
         count = _requested_fold_count(n_splits, available)
         iterators = [
-            iter(splitter.split(selected, n_splits=count)) if child_count is None else iter(splitter.split(selected))
-            for (selected, splitter), child_count in zip(prepared, reported, strict=True)
+            iter(splitter.split(dataset, n_splits=count)) if child_count is None else iter(splitter.split(dataset))
+            for (_, splitter), child_count in zip(self.parts, reported, strict=True)
         ]
         for _ in range(count):
             folds = []