API

TimeSeriesSplitByDate

timeseriessplitbydate.TimeSeriesSplitByDate

Bases: BaseEstimator, BaseCrossValidator

Time-series cross-validator with optional date-column-aware splitting.

Parameters

n_splits : int, default=5 Number of folds used by split_by='days' and fallback TimeSeriesSplit behavior. date_col : str or None, default=None Name of the datetime column in X when X is a pandas DataFrame. If None, the splitter can still use dates provided through :meth:set_date_data. max_train_size : int or None, default=None Maximum number of samples to keep in each training fold. test_size : int or None, default=None Maximum number of samples to keep in each testing fold. gap : int, default=0 Gap between training and testing windows.

- For date-based splitting, interpreted as calendar days.
- For fallback ``TimeSeriesSplit``, interpreted in samples.

split_by : {"days", "weeks", "months"}, default="days" Date-based splitting strategy.

- ``"days"`` divides the observed date span into equal-width intervals.
- ``"weeks"`` creates adjacent week folds based on ``week_start``
  (train through week ``i``, test on week ``i+1``).
- ``"months"`` creates adjacent month folds (train through month ``i``,
  test on month ``i+1``).

week_start : {"monday", "sunday"}, default="monday" First day of the week used when split_by='weeks'. "monday" is the default because it is the most common convention in analytics tooling (ISO week standard).

Notes

This splitter follows scikit-learn conventions:

  • split(X, y=None, groups=None) and get_n_splits(X=None, ...) are supported.
  • If no date source is available, it falls back to :class:sklearn.model_selection.TimeSeriesSplit.
  • groups is accepted for compatibility and ignored.

Date source precedence is:

  1. Data provided with :meth:set_date_data
  2. date_col from a pandas DataFrame X

get_n_splits(X=None, y=None, groups=None)

Return the number of splitting iterations.

Parameters

X : array-like or DataFrame, default=None Input data. Used for month-based mode when date_col is set. y : array-like, default=None Ignored, present for API compatibility. groups : array-like, default=None Ignored, present for API compatibility.

Returns

int Number of splits.

For ``split_by='weeks'`` or ``split_by='months'`` with available
date data, this is the number of unique periods minus one.

set_date_data(date_data)

Store external date values to use in subsequent :meth:split calls.

Parameters

date_data : iterable Datetime-like values aligned with samples passed to :meth:split.

Returns

TimeSeriesSplitByDate The current instance.

split(X, y=None, groups=None)

Generate train/test indices for each split.

Parameters

X : array-like of shape (n_samples, n_features) Input samples. y : array-like of shape (n_samples,), default=None Ignored, present for API compatibility. groups : array-like of shape (n_samples,), default=None Group labels. Ignored, present for API compatibility.

Yields

train : ndarray of shape (n_train_samples,) Training set indices for the split. test : ndarray of shape (n_test_samples,) Testing set indices for the split.

Notes

If no date source is available (no set_date_data and no date_col), this method falls back to :class:sklearn.model_selection.TimeSeriesSplit.

make_synthetic_time_series_dataset

timeseriessplitbydate.make_synthetic_time_series_dataset(n_samples=48, *, seed=42, shuffle=True, date_col='event_timestamp')

Create a synthetic time-series dataset with uneven timestamps.

Parameters

n_samples : int, default=48 Number of rows to generate. Must be at least 6. seed : int, default=42 Random seed used for reproducible noise and row shuffling. shuffle : bool, default=True If True, shuffle rows after generation so row order is not chronological. date_col : str, default="event_timestamp" Name of the datetime column in the returned DataFrame.

Returns

pandas.DataFrame DataFrame containing date_col, feature, and target columns.