Time Series Cross-Validation

https://github.com/wenjiez/tscv
Admin
Time Series Cross-Validation (TSCV) is a scikit-learn extension that introduces gaps between...
Tokens:8,747
Snippets:36
Trust Score:7.8
License:BSD-3-Clause
Update:11 months ago
Show doc for...
Tokens:
Raw
### Initialize Environment and Load Data for Scikit-Learn Cross-Validation

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/scikit-learn.rst

Imports necessary libraries from scikit-learn and tscv, and loads the Iris dataset. This setup is crucial for performing cross-validation with scikit-learn.

```python
import numpy as np
from sklearn import datasets
from sklearn import svm
from sklearn.model_selection import cross_val_score
from tscv import GapKFold

iris = datasets.load_iris()
clf = svm.SVC(kernel='linear', C=1)
```

--------------------------------

### Install TSCV using Conda

Source: https://github.com/wenjiez/tscv/blob/master/README.md

This snippet demonstrates how to install the TSCV library using Conda, a package and environment management system. It specifies the conda-forge channel for installation.

```bash
conda install -c conda-forge tscv
```

--------------------------------

### Install TSCV using pip

Source: https://github.com/wenjiez/tscv/blob/master/README.md

This snippet shows how to install the TSCV library using pip, a common Python package installer. Ensure pip is up-to-date for the best experience.

```bash
pip install tscv
```

--------------------------------

### GapKFold Initialization and Splitting in Python

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/k_fold.rst

Demonstrates how to initialize the GapKFold cross-validator with specified splits and gap sizes, and then iterates through the generated training and testing indices. This method is useful for verifying the cross-validation setup.

```python
from tscv import GapKFold
cv = GapKFold(n_splits=5, gap_before=2, gap_after=1)
for train, test in cv.split(range(10)):
    print("train:", train, "test:", test)

```

--------------------------------

### GapRollForward Cross-Validation Setup in Python

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/roll_forward.rst

Demonstrates how to instantiate and use the GapRollForward class to generate training and testing indices for time series cross-validation. This setup is useful for verifying configurations before integrating with scikit-learn cross-validators.

```python
from tscv import GapRollForward
cv = GapRollForward(min_train_size=3, gap_size=1, max_test_size=2)
for train, test in cv.split(range(10)):
    print("train:", train, "test:", test)

```

--------------------------------

### Time Series GapLeavePOut Cross-Validation Setup

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/leave_p_out.rst

Demonstrates how to initialize and use the GapLeavePOut class from the tscv library to generate train and test set indices for time series cross-validation. It highlights the 'p' samples left out and the 'gap_before' and 'gap_after' parameters. The output shows the generated indices for each split.

```python
from tscv import GapLeavePOut
cv = GapLeavePOut(p=3, gap_before=1, gap_after=2)
for train, test in cv.split(range(7)):
    print("train:", train, "test:", test)

```

--------------------------------

### GapRollForward: Rolling Window Cross-Validation in Python

Source: https://context7.com/wenjiez/tscv/llms.txt

Showcases the GapRollForward cross-validator for flexible walk-forward analysis on time series data. This example configures a rolling window with options for minimum/maximum training and testing sizes, gap size, and roll size. Dependencies include numpy and tscv.

```python
import numpy as np
from tscv import GapRollForward
from sklearn.ensemble import RandomForestRegressor
from sklearn.metrics import r2_score

# Generate time series data (e.g., daily stock prices)
np.random.seed(42)
n_samples = 100
X = np.random.randn(n_samples, 5)  # 5 features
y = np.random.randn(n_samples)

# Configure rolling window validation
# - min_train_size=20: Start with at least 20 samples for training
# - max_train_size=50: Use maximum 50 most recent samples (sliding window)
# - max_test_size=10: Test on up to 10 samples at a time
# - gap_size=5: 5-sample gap between train and test (e.g., 5-day embargo)
# - roll_size=10: Move forward 10 samples between splits
cv = GapRollForward(
    min_train_size=20,
    max_train_size=50,
    min_test_size=5,
    max_test_size=10,
    gap_size=5,
    roll_size=10
)
```

--------------------------------

### Split Data with gap_train_test_split

Source: https://github.com/wenjiez/tscv/blob/master/README.md

This example shows how to use the gap_train_test_split function from the TSCV library to split datasets for time series analysis. It creates training and testing sets with a specified gap size between them, preventing data leakage.

```python
import numpy as np
from tscv import gap_train_test_split

X, y = np.arange(20).reshape((10, 2)), np.arange(10)
X_train, X_test, y_train, y_test = gap_train_test_split(X, y, test_size=2, gap_size=2)
```

--------------------------------

### Integrate TSCV with scikit-learn Pipeline and GridSearchCV

Source: https://context7.com/wenjiez/tscv/llms.txt

Demonstrates a complete workflow for integrating `tscv`'s `GapKFold` with scikit-learn's `Pipeline` and `GridSearchCV`. This setup allows for hyperparameter optimization of a Gradient Boosting Regressor within a pipeline, while ensuring that the cross-validation strategy respects temporal ordering and includes gaps before and after the test sets.

```python
import numpy as np
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import GradientBoostingRegressor
from sklearn.model_selection import GridSearchCV, cross_validate
from tscv import GapKFold

# Generate time series data
np.random.seed(123)
n_samples = 200
X = np.cumsum(np.random.randn(n_samples, 3), axis=0)
y = X[:, 0] * 2 + X[:, 1] - X[:, 2] + np.random.randn(n_samples) * 0.5

# Create pipeline
pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('model', GradientBoostingRegressor(random_state=42))
])

# Define parameter grid
param_grid = {
    'model__n_estimators': [50, 100, 200],
    'model__learning_rate': [0.01, 0.1, 0.2],
    'model__max_depth': [3, 5, 7]
}

# Setup cross-validator with gaps
cv = GapKFold(n_splits=5, gap_before=10, gap_after=10)
```

--------------------------------

### Time Series Cross-Validation with GapKFold

Source: https://github.com/wenjiez/tscv/blob/master/README.md

This example demonstrates using GapKFold from the TSCV library for time series cross-validation within scikit-learn. It shows how to integrate a custom cross-validator like GapKFold with scikit-learn's cross_val_score function, specifying gap sizes before and after the test set.

```python
import numpy as np
from sklearn import datasets
from sklearn import svm
from sklearn.model_selection import cross_val_score
from tscv import GapKFold

iris = datasets.load_iris()
clf = svm.SVC(kernel='linear', C=1)

# use GapKFold as the cross-validator
cv = GapKFold(n_splits=5, gap_before=5, gap_after=5)
scores = cross_val_score(clf, iris.data, iris.target, cv=cv)
```

--------------------------------

### Legacy GapWalkForward Cross-Validator

Source: https://context7.com/wenjiez/tscv/llms.txt

Introduces `GapWalkForward`, a legacy cross-validator for time series data, maintained for backward compatibility. It enables walk-forward validation with configurable splits, test sizes, and gap sizes. For new projects, `GapRollForward` is recommended due to its enhanced flexibility.

```python
import numpy as np
from tscv import GapWalkForward

# Time series data
X = np.array([[1, 2], [3, 4], [1, 2], [3, 4], [1, 2], [3, 4]])
y = np.array([1, 2, 3, 4, 5, 6])

# Basic walk forward with 5 splits
cv = GapWalkForward(n_splits=5)
for train_idx, test_idx in cv.split(X):
    print(f"TRAIN: {train_idx} TEST: {test_idx}")

# With fixed test size and gap
X = np.random.randn(12, 2)
y = np.random.randint(0, 2, 12)
cv = GapWalkForward(n_splits=3, test_size=2, gap_size=2)
for train_idx, test_idx in cv.split(X):
    print(f"TRAIN: {train_idx} TEST: {test_idx}")

# With maximum training window size
cv = GapWalkForward(n_splits=3, test_size=2, gap_size=2, max_train_size=4)
for train_idx, test_idx in cv.split(X):
    print(f"TRAIN: {train_idx} TEST: {test_idx}")
```

--------------------------------

### GapRollForward - Rolling Window Cross-Validation

Source: https://context7.com/wenjiez/tscv/llms.txt

Provides flexible rolling window cross-validation for walk-forward analysis, with options for training window size, test size, gaps, and rolling increments.

```APIDOC
## GapRollForward - Rolling Window Cross-Validation

### Description
Flexible rolling window cross-validator for walk-forward analysis with extensive configuration options. Supports growing or fixed-size training windows, variable test sizes, and custom roll sizes for overlapping or non-overlapping test sets.

### Method
N/A (Class definition and usage)

### Endpoint
N/A (Class definition and usage)

### Parameters
#### Class Parameters
- **min_train_size** (int) - The minimum number of samples required for the initial training set.
- **max_train_size** (int) - The maximum number of samples to use in the training set (determines the sliding window size if used).
- **min_test_size** (int) - The minimum number of samples for each test set.
- **max_test_size** (int) - The maximum number of samples for each test set.
- **gap_size** (int) - The number of samples to include as a gap between the training and test sets.
- **roll_size** (int) - The number of samples to advance the window for each subsequent split.

### Request Example
```python
from tscv import GapRollForward

cv = GapRollForward(
    min_train_size=20,
    max_train_size=50,
    min_test_size=5,
    max_test_size=10,
    gap_size=5,
    roll_size=10
)
```

### Response
#### Success Response (Usage Example)
```python
import numpy as np
from tscv import GapRollForward
from sklearn.ensemble import RandomForestRegressor
from sklearn.metrics import r2_score

# Generate time series data (e.g., daily stock prices)
np.random.seed(42)
n_samples = 100
X = np.random.randn(n_samples, 5)  # 5 features
y = np.random.randn(n_samples)

# Configure rolling window validation
cv = GapRollForward(
    min_train_size=20,
    max_train_size=50,
    min_test_size=5,
    max_test_size=10,
    gap_size=5,
    roll_size=10
)

# Example of iterating through splits and evaluating a model
model = RandomForestRegressor(n_estimators=10, random_state=42)
r2_scores = []

for train_idx, test_idx in cv.split(X):
    X_train, X_test = X[train_idx], X[test_idx]
    y_train, y_test = y[train_idx], y[test_idx]

    model.fit(X_train, y_train)
    y_pred = model.predict(X_test)
    r2 = r2_score(y_test, y_pred)
    r2_scores.append(r2)
    print(f"TRAIN indices: {train_idx[0]}..{train_idx[-1]} (size {len(train_idx)})")
    print(f"TEST indices: {test_idx[0]}..{test_idx[-1]} (size {len(test_idx)})")
    print(f"R2 Score: {r2:.4f}")

print(f"\nAverage R2 Score: {np.mean(r2_scores):.4f}")
print(f"Number of splits: {cv.get_n_splits(X)}")
```

#### Response Example (Evaluation Output Snippet)
```
TRAIN indices: 0..49 (size 50)
TEST indices: 55..64 (size 10)
R2 Score: -0.1176
TRAIN indices: 0..59 (size 60) - Note: max_train_size caps training data if `grow_train` is False
TEST indices: 65..74 (size 10)
R2 Score: -0.0744
...
```
```

--------------------------------

### Perform Cross-Validation with GapKFold Splitter in Scikit-Learn

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/scikit-learn.rst

Instantiates a GapKFold splitter and uses it with scikit-learn's cross_val_score function to evaluate an SVM classifier on the Iris dataset. This demonstrates the compatibility between tscv splitters and scikit-learn's cross-validation framework.

```python
cv = GapKFold(n_splits=5, gap_before=5, gap_after=5)
scores = cross_val_score(clf, iris.data, iris.target, cv=cv)

# Example output:
# >>> scores
# array([1.        , 1.        , 0.83333333, 0.96666667, 0.83333333])
```

--------------------------------

### GapLeavePOut: Leave-P-Out Cross-Validation with Temporal Gaps in Python

Source: https://context7.com/wenjiez/tscv/llms.txt

Illustrates the use of GapLeavePOut for time series cross-validation, where 'p' samples are left out for testing with configurable gaps before and after. It demonstrates evaluating a Ridge model's performance using mean squared error across multiple splits. Dependencies include numpy, tscv, and scikit-learn.

```python
import numpy as np
from tscv import GapLeavePOut
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_squared_error

# Create time series data
X = np.arange(20).reshape(-1, 1)
y = np.sin(X.ravel()) + np.random.randn(20) * 0.1

# Leave 2 samples out with 1 sample gap before and after
cv = GapLeavePOut(p=2, gap_before=1, gap_after=1)

# Evaluate model performance
model = Ridge()
mse_scores = []

for train_idx, test_idx in cv.split(X):
    X_train, X_test = X[train_idx], X[test_idx]
    y_train, y_test = y[train_idx], y[test_idx]

    model.fit(X_train, y_train)
    y_pred = model.predict(X_test)
    mse = mean_squared_error(y_test, y_pred)
    mse_scores.append(mse)
    print(f"TRAIN: {train_idx} TEST: {test_idx} MSE: {mse:.4f}")

print(f"Average MSE: {np.mean(mse_scores):.4f}")
print(f"Number of splits: {cv.get_n_splits(X)}")
```

--------------------------------

### Perform Walk-Forward Validation with RandomForestRegressor

Source: https://context7.com/wenjiez/tscv/llms.txt

Demonstrates a standard walk-forward validation process using scikit-learn's RandomForestRegressor. It iterates through cross-validation splits, trains the model on training data, predicts on test data, and calculates the R² score for each split, finally reporting the average R² score.

```python
model = RandomForestRegressor(n_estimators=100, random_state=42)
r2_scores = []

print(f"Number of splits: {cv.get_n_splits(X)}\n")

for i, (train_idx, test_idx) in enumerate(cv.split(X), 1):
    X_train, X_test = X[train_idx], X[test_idx]
    y_train, y_test = y[train_idx], y[test_idx]

    model.fit(X_train, y_train)
    y_pred = model.predict(X_test)
    r2 = r2_score(y_test, y_pred)
    r2_scores.append(r2)

    print(f"Split {i}:")
    print(f"  Train: samples {train_idx[0]} to {train_idx[-1]} (n={len(train_idx)})")
    print(f"  Test:  samples {test_idx[0]} to {test_idx[-1]} (n={len(test_idx)})")
    print(f"  R² score: {r2:.4f}")

print(f"\nAverage R² score: {np.mean(r2_scores):.4f}")
```

--------------------------------

### Hyperparameter Tuning with GridSearchCV and Time Series CV

Source: https://context7.com/wenjiez/tscv/llms.txt

Performs hyperparameter tuning for a given pipeline using GridSearchCV with a time series cross-validation strategy. It optimizes for negative mean squared error and utilizes all available CPU cores. Outputs the best found parameters and the corresponding best MSE.

```python
from sklearn.model_selection import GridSearchCV

# Assuming 'pipeline', 'param_grid', 'cv', 'X', and 'y' are defined elsewhere
grid_search = GridSearchCV(
    pipeline,
    param_grid,
    cv=cv,
    scoring='neg_mean_squared_error',
    n_jobs=-1,
    verbose=1
)

grid_search.fit(X, y)

print("Best parameters:", grid_search.best_params_)
print(f"Best MSE: {-grid_search.best_score_:.4f}")
```

--------------------------------

### GapKFold: K-Folds Cross-Validation with Temporal Gaps in Python

Source: https://context7.com/wenjiez/tscv/llms.txt

Demonstrates how to use GapKFold for K-Folds cross-validation on time series data with specified temporal gaps. It shows integration with scikit-learn's cross_val_score and manual iteration through splits, ensuring no information leakage between training and testing folds. Dependencies include numpy, scikit-learn, and tscv.

```python
import numpy as np
from sklearn import datasets
from sklearn import svm
from sklearn.model_selection import cross_val_score
from tscv import GapKFold

# Load dataset
iris = datasets.load_iris()
clf = svm.SVC(kernel='linear', C=1)

# Create cross-validator with 5 splits and gaps of 5 samples before/after test sets
cv = GapKFold(n_splits=5, gap_before=5, gap_after=5)

# Use with scikit-learn's cross-validation functions
scores = cross_val_score(clf, iris.data, iris.target, cv=cv)
print(f"Cross-validation scores: {scores}")
print(f"Mean accuracy: {scores.mean():.3f} (+/- {scores.std() * 2:.3f})")

# Manual iteration through splits
X = np.arange(10)
cv = GapKFold(n_splits=5, gap_before=3, gap_after=4)
for train_idx, test_idx in cv.split(X):
    print(f"TRAIN: {train_idx} TEST: {test_idx}")
# Output:
# TRAIN: [6 7 8 9] TEST: [0 1]
# TRAIN: [8 9] TEST: [2 3]
# TRAIN: [0] TEST: [4 5]
# TRAIN: [0 1 2] TEST: [6 7]
# TRAIN: [0 1 2 3 4] TEST: [8 9]
```

--------------------------------

### Split Arrays with Gap Removal using Python

Source: https://github.com/wenjiez/tscv/blob/master/doc/tutorial/train_test_split.rst

This Python code demonstrates how to use the gap_train_test_split function from the tscv library to divide numpy arrays into training and testing sets. It specifies the test set size and the gap size to be removed between the sets. The function is useful for time series cross-validation where temporal gaps need to be handled.

```python
import numpy as np
from tscv import gap_train_test_split
X, y = np.arange(20).reshape((10, 2)), np.arange(10)
X_train, X_test, y_train, y_test = gap_train_test_split(
    X, y, test_size=2, gap_size=2)

print(X_train)
print(X_test)
print(y_train)
print(y_test)
```

--------------------------------

### Detailed Cross-Validation with Multiple Metrics using cross_validate

Source: https://context7.com/wenjiez/tscv/llms.txt

Evaluates the best model obtained from grid search using cross_validate with multiple scoring metrics (MSE, MAE, R²). It returns training and testing scores, allowing for a comprehensive performance analysis including mean and standard deviation for each metric on the test set.

```python
from sklearn.model_selection import cross_validate

# Assuming 'cv', 'X', 'y', and 'grid_search' are defined elsewhere
scoring = {
    'mse': 'neg_mean_squared_error',
    'mae': 'neg_mean_absolute_error',
    'r2': 'r2'
}

cv_results = cross_validate(
    grid_search.best_estimator_,
    X, y,
    cv=cv,
    scoring=scoring,
    return_train_score=True
)

print(f"\nTest MSE: {-cv_results['test_mse'].mean():.4f} (+/- {cv_results['test_mse'].std():.4f})")
print(f"Test MAE: {-cv_results['test_mae'].mean():.4f} (+/- {cv_results['test_mae'].std():.4f})")
print(f"Test R²: {cv_results['test_r2'].mean():.4f} (+/- {cv_results['test_r2'].std():.4f})")
```

--------------------------------

### GapLeavePOut - Leave-P-Out with Temporal Gaps

Source: https://context7.com/wenjiez/tscv/llms.txt

Implements a Leave-P-Out cross-validation strategy for time series data, leaving out contiguous blocks of 'p' samples for testing and including gaps.

```APIDOC
## GapLeavePOut - Leave-P-Out with Temporal Gaps

### Description
Leave-P-Out cross-validator that tests on contiguous samples of size p while using remaining samples (with gaps removed) for training. Particularly useful for testing model robustness across all possible temporal windows of a given size.

### Method
N/A (Class definition and usage)

### Endpoint
N/A (Class definition and usage)

### Parameters
#### Class Parameters
- **p** (int) - The size of the contiguous test set (leave-out block).
- **gap_before** (int) - The number of samples to include as a gap before each test set.
- **gap_after** (int) - The number of samples to include as a gap after each test set.

### Request Example
```python
from tscv import GapLeavePOut

cv = GapLeavePOut(p=2, gap_before=1, gap_after=1)
```

### Response
#### Success Response (Usage Example)
```python
import numpy as np
from tscv import GapLeavePOut
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_squared_error

# Create time series data
X = np.arange(20).reshape(-1, 1)
y = np.sin(X.ravel()) + np.random.randn(20) * 0.1

# Leave 2 samples out with 1 sample gap before and after
cv = GapLeavePOut(p=2, gap_before=1, gap_after=1)

# Evaluate model performance
model = Ridge() mse_scores = []

for train_idx, test_idx in cv.split(X):
    X_train, X_test = X[train_idx], X[test_idx]
    y_train, y_test = y[train_idx], y[test_idx]

    model.fit(X_train, y_train)
    y_pred = model.predict(X_test)
    mse = mean_squared_error(y_test, y_pred)
    mse_scores.append(mse)
    print(f"TRAIN: {train_idx} TEST: {test_idx} MSE: {mse:.4f}")

print(f"Average MSE: {np.mean(mse_scores):.4f}")
print(f"Number of splits: {cv.get_n_splits(X)}")
```

#### Response Example (Evaluation Output)
```
TRAIN: [ 2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17] TEST: [0 1] MSE: 0.0314
TRAIN: [4 5 6 7 8 9 10 11 12 13 14 15 16 17] TEST: [2 3] MSE: 0.0389
TRAIN: [ 0  1  6  7  8  9 10 11 12 13 14 15 16 17] TEST: [4 5] MSE: 0.0248
TRAIN: [0 1 2 3 8 9 10 11 12 13 14 15 16 17] TEST: [6 7] MSE: 0.0098
TRAIN: [0 1 2 3 4 5 10 11 12 13 14 15 16 17] TEST: [8 9] MSE: 0.0028
TRAIN: [0 1 2 3 4 5 6 7 12 13 14 15 16 17] TEST: [10 11] MSE: 0.0051
TRAIN: [0 1 2 3 4 5 6 7 8 9 14 15 16 17] TEST: [12 13] MSE: 0.0169
TRAIN: [0 1 2 3 4 5 6 7 8 9 10 11 16 17] TEST: [14 15] MSE: 0.0421
TRAIN: [0 1 2 3 4 5 6 7 8 9 10 11 12 13] TEST: [16 17] MSE: 0.0725
Average MSE: 0.0291
Number of splits: 9
```
```

--------------------------------

### GapKFold - K-Folds Cross-Validation with Temporal Gaps

Source: https://context7.com/wenjiez/tscv/llms.txt

Performs K-Folds cross-validation on time series data, incorporating specified gaps before and after each test set to maintain temporal independence.

```APIDOC
## GapKFold - K-Folds Cross-Validation with Temporal Gaps

### Description
K-Folds cross-validator that splits time series data into k consecutive folds with configurable gaps before and after each test set. Each fold serves as validation while the remaining folds (with gaps removed) form the training set, ensuring temporal independence between train and test data.

### Method
N/A (Class definition and usage)

### Endpoint
N/A (Class definition and usage)

### Parameters
#### Class Parameters
- **n_splits** (int) - The number of folds (splits) for cross-validation.
- **gap_before** (int) - The number of samples to include as a gap before each test set.
- **gap_after** (int) - The number of samples to include as a gap after each test set.

### Request Example
```python
from tscv import GapKFold

cv = GapKFold(n_splits=5, gap_before=5, gap_after=5)
```

### Response
#### Success Response (Usage Example)
```python
import numpy as np
from sklearn.model_selection import cross_val_score
from sklearn import datasets
from sklearn import svm

# Load dataset
iris = datasets.load_iris()
clf = svm.SVC(kernel='linear', C=1)

# Create cross-validator
cv = GapKFold(n_splits=5, gap_before=5, gap_after=5)

# Use with scikit-learn's cross-validation functions
scores = cross_val_score(clf, iris.data, iris.target, cv=cv)
print(f"Cross-validation scores: {scores}")
print(f"Mean accuracy: {scores.mean():.3f} (+/- {scores.std() * 2:.3f})")

# Manual iteration through splits
X = np.arange(10)
cv_manual = GapKFold(n_splits=5, gap_before=3, gap_after=4)
for train_idx, test_idx in cv_manual.split(X):
    print(f"TRAIN: {train_idx} TEST: {test_idx}")
```

#### Response Example (Manual Split Output)
```
TRAIN: [6 7 8 9] TEST: [0 1]
TRAIN: [8 9] TEST: [2 3]
TRAIN: [0] TEST: [4 5]
TRAIN: [0 1 2] TEST: [6 7]
TRAIN: [0 1 2 3 4] TEST: [8 9]
```
```

--------------------------------

### Gap-Based Train/Test Split for Time Series Data

Source: https://context7.com/wenjiez/tscv/llms.txt

Utilizes the `gap_train_test_split` function from the `tscv` library to divide time series data into training and testing sets with a specified gap. This function ensures temporal separation, preventing data leakage from the test set into the training set. It supports both proportional and absolute gap sizes and can split single arrays or multiple arrays simultaneously.

```python
import numpy as np
from tscv import gap_train_test_split
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_absolute_error

# Create time series dataset
X = np.arange(100).reshape((50, 2))
y = np.arange(50) * 2 + 5

# Split with gap_size as proportion (10% gap)
X_train, X_test, y_train, y_test = gap_train_test_split(
    X, y, test_size=0.2, gap_size=0.1
)
print(f"Train size: {len(X_train)}, Test size: {len(X_test)}")
print(f"Gap: samples {len(X_train)} to {len(X_train) + int(0.1 * len(X))}")

# Split with absolute gap size (5 samples gap)
X_train, X_test, y_train, y_test = gap_train_test_split(
    X, y, test_size=10, gap_size=5
)
print(f"\nTrain indices: 0 to {len(X_train)-1}")
print(f"Gap indices: {len(X_train)} to {len(X_train)+4}")
print(f"Test indices: {len(X_train)+5} to {len(X)-1}")

# Train and evaluate model
model = LinearRegression()
model.fit(X_train, y_train)
y_pred = model.predict(X_test)
mae = mean_absolute_error(y_test, y_pred)
print(f"\nMAE: {mae:.4f}")

# Single array split (useful for index-based operations)
train_indices, test_indices = gap_train_test_split(
    list(range(100)), gap_size=10, test_size=0.2
)
print(f"\nTrain indices: {train_indices[:5]}...{train_indices[-5:]}")
print(f"Test indices: {test_indices[:5]}...{test_indices[-5:]}")
```

--------------------------------

### gap_train_test_split - Utility Function

Source: https://context7.com/wenjiez/tscv/llms.txt

A utility function to split time series data into training and testing sets with an optional gap in between, preventing data leakage.

```APIDOC
## gap_train_test_split - Utility Function

### Description
A utility function that splits time series data into training and testing sets, incorporating an optional gap to prevent temporal data leakage. This is useful for simple train-test splits where temporal order is crucial.

### Method
N/A (Function definition and usage)

### Endpoint
N/A (Function definition and usage)

### Parameters
#### Function Parameters
- **train_size** (int or float) - The proportion or absolute number of samples to include in the training split.
- **test_size** (int or float) - The proportion or absolute number of samples to include in the test split.
- **gap** (int) - The number of samples to place between the training and testing sets.
- **shuffle** (bool) - Whether to shuffle the data before splitting. Defaults to False for time series integrity.

### Request Example
```python
from tscv import gap_train_test_split
import numpy as np

X = np.arange(50)
y = np.arange(50)

X_train, X_test, y_train, y_test = gap_train_test_split(X, y, test_size=10, gap=5, shuffle=False)

print(f"X_train shape: {X_train.shape}")
print(f"X_test shape: {X_test.shape}")
print(f"First few X_train: {X_train[:5]}")
print(f"First few X_test: {X_test[:5]}")
```

### Response
#### Success Response (Output Example)
```
X_train shape: (35,)
X_test shape: (10,)
First few X_train: [0 1 2 3 4]
First few X_test: [15 16 17 18 19]
```

#### Response Example (Variable Explanation)
- **X_train** (numpy.ndarray) - The training features.
- **X_test** (numpy.ndarray) - The testing features.
- **y_train** (numpy.ndarray) - The training target variable.
- **y_test** (numpy.ndarray) - The testing target variable.
```
Tokens:
Raw