Skip to content

BaseSplitter

yohou.model_selection.split.BaseSplitter

Bases: BaseEstimator, ABC

Base class for yohou time series cross-validation splitters.

Extends sklearn's BaseCrossValidator with time series-specific functionality including polars DataFrame support and panel data awareness.

All concrete splitters should inherit from this class and implement the _iter_test_indices() method.

Attributes

Name Type Description
interval_ str

Detected time interval of the data, set during split().

Notes

This is an abstract base class. Concrete splitters should inherit from this class and implement _iter_test_indices() and get_n_splits().

See Also

Source Code

View on GitHub

Show/Hide source 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
class BaseSplitter(BaseEstimator, ABC):
    """Base class for yohou time series cross-validation splitters.

    Extends sklearn's BaseCrossValidator with time series-specific
    functionality including polars DataFrame support and panel data awareness.

    All concrete splitters should inherit from this class and implement
    the ``_iter_test_indices()`` method.

    Attributes
    ----------
    interval_ : str
        Detected time interval of the data, set during ``split()``.

    Notes
    -----
    This is an abstract base class. Concrete splitters should inherit from
    this class and implement ``_iter_test_indices()`` and ``get_n_splits()``.

    See Also
    --------
    - [`ExpandingWindowSplitter`][yohou.model_selection.split.ExpandingWindowSplitter] : Expanding-window cross-validation.
    - [`SlidingWindowSplitter`][yohou.model_selection.split.SlidingWindowSplitter] : Sliding-window cross-validation.

    """

    _parameter_constraints: dict = {}
    _tags: ClassVar[dict[str, Any]] = {}

    # Fitted attributes (set during split())
    interval_: str

    def __init_subclass__(cls, **kwargs: Any) -> None:
        """Merge parameter constraints from all classes in the MRO."""
        super().__init_subclass__(**kwargs)
        # Auto-merge _parameter_constraints from all classes in the MRO.
        merged: dict = {}
        for klass in reversed(cls.__mro__):
            own = klass.__dict__.get("_parameter_constraints")
            if own and isinstance(own, dict):
                merged.update(own)
        cls._parameter_constraints = merged

    @abstractmethod
    def split(
        self,
        y: pl.DataFrame,
        X_actual: pl.DataFrame | None = None,
    ) -> Iterator[tuple[np.ndarray[Any, np.dtype[np.intp]], np.ndarray[Any, np.dtype[np.intp]]]]:
        """Generate indices to split time series data.

        Parameters
        ----------
        y : pl.DataFrame
            Target time series used to generate train/test split indices.
            Must have a ``"time"`` column.
        X_actual : pl.DataFrame or None, default=None
            Actual features.  Not used for splitting but accepted for
            API consistency.

        Yields
        ------
        train : ndarray
            Training set row indices for that split.
        test : ndarray
            Test set row indices for that split.

        """

    @abstractmethod
    def _iter_test_indices(
        self,
        y: pl.DataFrame,
        X_actual: pl.DataFrame | None = None,
    ) -> Iterator[np.ndarray[Any, np.dtype[np.intp]]]:
        """Generate test indices for each split.

        Must be implemented by concrete splitter classes.

        Parameters
        ----------
        y : pl.DataFrame
            Target time series.
        X_actual : pl.DataFrame or None, default=None
            Actual features. Not used for splitting but accepted for
            API consistency.

        Yields
        ------
        test : ndarray
            Test set indices for this split.

        """

    @abstractmethod
    def get_n_splits(
        self,
        y: pl.DataFrame | None = None,
        X_actual: pl.DataFrame | None = None,
    ) -> int:
        """Return the number of cross-validation folds.

        Parameters
        ----------
        y : pl.DataFrame or None, default=None
            Not used.  Accepted for API consistency.
        X_actual : pl.DataFrame or None, default=None
            Not used.  Accepted for API consistency.

        Returns
        -------
        int
            The number of cross-validation folds.

        """

    def __sklearn_tags__(self):
        """Get metadata tags for this splitter.

        Returns
        -------
        tags : Tags
            Metadata tags describing splitter capabilities.

        """
        tags = Tags(estimator_type="splitter")
        if tags.splitter_tags is not None:
            tags.splitter_tags.supports_panel_data = True

        # Merge class-level _tags dict (flat keys) into tag dataclasses.
        # Walk MRO in reverse so most-derived class wins.
        merged_tags: dict[str, Any] = {}
        for klass in reversed(type(self).__mro__):
            class_tags = klass.__dict__.get("_tags")
            if class_tags and isinstance(class_tags, dict):
                merged_tags.update(class_tags)

        if merged_tags:
            for key, value in merged_tags.items():
                if tags.splitter_tags is not None and hasattr(tags.splitter_tags, key):
                    setattr(tags.splitter_tags, key, value)
                elif tags.input_tags is not None and hasattr(tags.input_tags, key):
                    setattr(tags.input_tags, key, value)
                elif hasattr(tags, key):
                    setattr(tags, key, value)

        return tags

Methods

__init_subclass__(**kwargs)

Merge parameter constraints from all classes in the MRO.

Source Code

View on GitHub

Show/Hide source 
58
59
60
61
62
63
64
65
66
67
def __init_subclass__(cls, **kwargs: Any) -> None:
    """Merge parameter constraints from all classes in the MRO."""
    super().__init_subclass__(**kwargs)
    # Auto-merge _parameter_constraints from all classes in the MRO.
    merged: dict = {}
    for klass in reversed(cls.__mro__):
        own = klass.__dict__.get("_parameter_constraints")
        if own and isinstance(own, dict):
            merged.update(own)
    cls._parameter_constraints = merged

split(y, X_actual=None) abstractmethod

Generate indices to split time series data.

Parameters
Name Type Description Default
y DataFrame

Target time series used to generate train/test split indices. Must have a "time" column.

 required
X_actual DataFrame or None

Actual features. Not used for splitting but accepted for API consistency.

 None

Yields:

Name Type Description
train ndarray

Training set row indices for that split.
test ndarray

Test set row indices for that split.
Source Code

View on GitHub

Show/Hide source 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@abstractmethod
def split(
    self,
    y: pl.DataFrame,
    X_actual: pl.DataFrame | None = None,
) -> Iterator[tuple[np.ndarray[Any, np.dtype[np.intp]], np.ndarray[Any, np.dtype[np.intp]]]]:
    """Generate indices to split time series data.

    Parameters
    ----------
    y : pl.DataFrame
        Target time series used to generate train/test split indices.
        Must have a ``"time"`` column.
    X_actual : pl.DataFrame or None, default=None
        Actual features.  Not used for splitting but accepted for
        API consistency.

    Yields
    ------
    train : ndarray
        Training set row indices for that split.
    test : ndarray
        Test set row indices for that split.

    """

get_n_splits(y=None, X_actual=None) abstractmethod

Return the number of cross-validation folds.

Parameters
Name Type Description Default
y DataFrame or None

Not used. Accepted for API consistency.

 None
X_actual DataFrame or None

Not used. Accepted for API consistency.

 None
Returns
Type Description
int

The number of cross-validation folds.
Source Code

View on GitHub

Show/Hide source 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@abstractmethod
def get_n_splits(
    self,
    y: pl.DataFrame | None = None,
    X_actual: pl.DataFrame | None = None,
) -> int:
    """Return the number of cross-validation folds.

    Parameters
    ----------
    y : pl.DataFrame or None, default=None
        Not used.  Accepted for API consistency.
    X_actual : pl.DataFrame or None, default=None
        Not used.  Accepted for API consistency.

    Returns
    -------
    int
        The number of cross-validation folds.

    """

__sklearn_tags__()

Get metadata tags for this splitter.

Returns
Name Type Description
tags Tags

Metadata tags describing splitter capabilities.
Source Code

View on GitHub

Show/Hide source 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def __sklearn_tags__(self):
    """Get metadata tags for this splitter.

    Returns
    -------
    tags : Tags
        Metadata tags describing splitter capabilities.

    """
    tags = Tags(estimator_type="splitter")
    if tags.splitter_tags is not None:
        tags.splitter_tags.supports_panel_data = True

    # Merge class-level _tags dict (flat keys) into tag dataclasses.
    # Walk MRO in reverse so most-derived class wins.
    merged_tags: dict[str, Any] = {}
    for klass in reversed(type(self).__mro__):
        class_tags = klass.__dict__.get("_tags")
        if class_tags and isinstance(class_tags, dict):
            merged_tags.update(class_tags)

    if merged_tags:
        for key, value in merged_tags.items():
            if tags.splitter_tags is not None and hasattr(tags.splitter_tags, key):
                setattr(tags.splitter_tags, key, value)
            elif tags.input_tags is not None and hasattr(tags.input_tags, key):
                setattr(tags.input_tags, key, value)
            elif hasattr(tags, key):
                setattr(tags, key, value)

    return tags