Chronological model evaluation
Forecasting or other temporal prediction tasks
Scikit-Learn · Class
TimeSeriesSplit
TimeSeriesSplit is a cross-validator for time-ordered data. It builds progressively later test folds while training on earlier observations, with optional limits on training size, test size, and a gap.
- Since
- 0.18
How it works
TimeSeriesSplit creates successive chronological train/test partitions for ordered observations. Each later training partition includes earlier data, while gap can remove samples immediately before testing; equally spaced samples are needed when fold metrics must represent equal time durations.
Syntax
class sklearn.model_selection.TimeSeriesSplit(n_splits=5, *, max_train_size=None, test_size=None, gap=0)Parameters
| Name | Type | Description |
|---|---|---|
n_splits | int, default=5 | Number of splits; must be at least 2. |
max_train_size | int, default=None | Maximum size for a single training set. |
test_size | int, default=None | Limits the size of the test set; defaults to n_samples // (n_splits + 1). |
gap | int, default=0 | Number of samples excluded from the end of each training set before testing. |
Returns
A cross-validator that yields train/test index arrays for successive time-ordered splits.
Key points
- Use it to obtain indices for chronological cross-validation instead of randomly partitioning ordered observations.
- Its fold structure resembles KFold, but the partitions preserve temporal order and accumulate earlier training data.
- Each later split advances the test region while retaining preceding folds for training.
- With default sizing, training sets grow according to the documented fold-size formula, with the remainder assigned to the training portion.
- Set gap to create a buffer between the final training observation and the first test observation.
Common mistakes
- Use equally spaced observations when comparing metrics across folds; otherwise, identical sample counts do not represent identical time durations.
- Do not use ordinary shuffled-style cross-validation for ordered data when it could train on future observations and evaluate on earlier ones.
- The default test size depends on the sample count and number of splits; specifying a gap can constrain the usable layout.
Example: Chronological cross-validation
import numpy as np
from sklearn.model_selection import TimeSeriesSplit
X = np.arange(12).reshape(6, 2)
cv = TimeSeriesSplit(n_splits=3, gap=1, test_size=1)
for train, test in cv.split(X):
print(train, test)Creates chronological folds while leaving one sample between each training and test segment.
When to use it
Leakage-resistant validation with a gap
Pipelines with a delay between observed training data and evaluated outcomes
Rolling-window training
Non-stationary systems where old data should be discarded
Interview questions
QWhy use TimeSeriesSplit instead of KFold for temporal data?
TimeSeriesSplit is designed for ordered observations. It produces training indices from earlier folds and a test fold that occurs later, avoiding evaluation on the past after training on the future.
Follow-up: How would you prevent leakage from a forecast horizon? Set gap to exclude the required number of samples between the training end and test start.
QHow does TimeSeriesSplit construct its folds?
The default n_splits is 5, and it must be at least 2. In split k, the first k folds form training data and the next fold forms test data.
Follow-up: What happens as n_splits increases? Each default test partition becomes smaller because its size is based on n_samples divided by n_splits plus one.
QWhat do test_size and max_train_size control?
max_train_size limits the size of an individual training set. test_size limits the test-set size; when omitted, it defaults to n_samples // (n_splits + 1).
Follow-up: When would max_train_size be useful? Use it when only a recent rolling window should train the model rather than the entire accumulated history.
Related
KFoldcross-validationTimeSeriesSplit.split