macrosynergy.learning.panel_time_series_split#

Tools to produce, visualise and use walk-forward validation splits across panels.

class BasePanelSplit[source]#

Bases: BaseCrossValidator

Base class for the production of paired training and test splits for panel data. All children classes possess the following methods: get_n_splits and visualise_splits. The method ‘get_n_splits’ is required so that our panel splitters can inherit from sklearn’s BaseCrossValidator class, allowing for seamless integration with sklearn’s API. The method ‘visualise_splits’ is a convenience method for visualising the splits produced by each child splitter, giving the user confidence in the splits produced for their use case.

get_n_splits(X=None, y=None, groups=None)[source]#

Returns the number of splits in the cross-validator.

Parameters:

  • X – Always ignored, exists for compatibility with scikit-learn.

  • y – Always ignored, exists for compatibility with scikit-learn.

  • groups – Always ignored, exists for compatibility with scikit-learn.

Return <int> n_splits:

Returns the number of splits.

Return type:

int

visualise_splits(X, y, figsize=(20, 5))[source]#

Method to visualise the splits created according to the parameters specified in the constructor.

Parameters:

  • X (DataFrame) – Pandas dataframe of features/quantamental indicators, multi-indexed by (cross-section, date). The dates must be in datetime format. Otherwise the dataframe must be in wide format: each feature is a column.

  • y (DataFrame) – Pandas dataframe of target variable, multi-indexed by (cross-section, date). The dates must be in datetime format.

  • figsize (Tuple[int, int]) – tuple of integers specifying the splitter visualisation figure size.

:return None

Return type:

None

class ExpandingKFoldPanelSplit(n_splits=5)[source]#

Bases: BasePanelSplit

Class for the production of paired training and test splits, created over a panel of countries. ExpandingKFoldPanelSplit operates similarly to sklearn’s TimeSeriesSplit class, but is designed to handle panels of data, as opposed to single time series’. To create the splits, the sorted, unique dates in the panel are divided into ‘n_splits + 1’ sequential and non-overlapping intervals. This results in ‘n_splits’ pairs of training and test sets, where the ‘i’th training set is the union of the first ‘i’ intervals, and the ‘i’th test set is the ‘i+1’th interval.

Parameters:

n_splits (int) – number of splits. Must be at least 2.

split(X, y, groups=None)[source]#

Method that produces pairs of training and test indices as intended by the ExpandingKFoldPanelSplit class. Wide format Pandas (panel) dataframes are expected, multi-indexed by cross-section and date. It is recommended for the features to lag behind the associated targets by a single native frequency unit.

Parameters:

  • X (DataFrame) – Pandas dataframe of features, multi-indexed by (cross-section, date). The dates must be in datetime format. Otherwise the dataframe must be in wide format: each feature is a column.

  • y (DataFrame) – Pandas dataframe of the target variable, multi-indexed by (cross-section, date). The dates must be in datetime format.

  • groups – Always ignored, exists for compatibility with scikit-learn.

Return <Iterable[Tuple[np.ndarray[int],np.ndarray[int]]]> splits:

Iterable of (train,test) indices.

Return type:

Iterable[Tuple[ndarray, ndarray]]

class RollingKFoldPanelSplit(n_splits=5)[source]#

Bases: BasePanelSplit

Class for the production of paired training and test splits, created over a panel of countries. RollingKFoldPanelSplit operates similarly to sklearn’s KFold class (without shuffle enabled), but is designed to handle panels of data, as opposed to single time series’. To create the splits, the sorted, unique dates in the panel are divided into ‘n_splits’ sequential and non-overlapping intervals. This results in ‘n_splits’ pairs of training and test sets, where the ‘i’th training set is the ‘i’th interval, and the ‘i’th test set are all other intervals. This gives the effect of the test set “rolling” forward in time.

Parameters:

n_splits (int) – number of splits. Must be at least 2.

split(X, y, groups=None)[source]#

Method that produces pairs of training and test indices as intended by the RollingKFoldPanelSplit class. Wide format Pandas (panel) dataframes are expected, multi-indexed by cross-section and date. It is recommended for the features to lag behind the associated targets by a single native frequency unit.

Parameters:

  • X (DataFrame) – Pandas dataframe of features, multi-indexed by (cross-section, date). The dates must be in datetime format. Otherwise the dataframe must be in wide format: each feature is a column.

  • y (DataFrame) – Pandas dataframe of the target variable, multi-indexed by (cross-section, date). The dates must be in datetime format.

  • groups – Always ignored, exists for compatibility with scikit-learn.

Return <Iterable[Tuple[np.ndarray[int],np.ndarray[int]]]> splits:

Iterable of (train,test) indices.

Return type:

Iterable[Tuple[ndarray, ndarray]]

class ExpandingIncrementPanelSplit(train_intervals=21, min_cids=4, min_periods=500, test_size=21, max_periods=None)[source]#

Bases: BasePanelSplit

Class for the production of paired training and test splits, created over a panel of countries. ExpandingIncrementPanelSplit differs from ExpandingKFoldPanelSplit by specifying the structure of an initial training and test set, as well as the number of time periods to expand both the initial and subsequent training and test sets by. This is a flexible alternative to defining the number of splits to make.

The first training set is determined by the parameters ‘min_cids’ and ‘min_periods’, defined below. This set comprises at least ‘min_periods’ time periods for at least ‘min_cids’ cross-sections. Its associated test set immediately follows the training set, and is of length ‘test_size’. Subsequent training sets are created by expanding the previous training set by ‘train_intervals’ time periods, in the native frequency of the concerned datasets. As before, each test set immediately follows its associated training set, and is of length ‘test_size’. We also provide a parameter ‘max_periods’, which allows the user to roll the training set forward as opposed to expanding it. If the number of time periods in the training set exceeds ‘max_periods’, the earliest time periods are truncated.

This splitter can be employed, in addition to standard use, to reflect a pipeline through time in a real-world setting. This is especially the case when ‘test_size’ is set to 1.

Parameters:

  • train_intervals (Optional[int]) – training interval length in time periods for sequential training. This is the number of periods by which the training set is expanded at each subsequent split. Default is 21.

  • min_cids (Optional[int]) – minimum number of cross-sections required for the initial training set. Default is 4.

  • min_periods (Optional[int]) – minimum number of time periods required for the initial training set. Default is 500.

  • test_size (int) – test set length for interval training. This is the number of periods to use for the test set subsequent to the training set. Default is 21.

  • max_periods (Optional[int]) – maximum length of each training set in interval training. If the maximum is exceeded, the earliest periods are cut off. Default is None.

split(X, y, groups=None)[source]#

Method that produces pairs of training and test indices as intended by the ExpandingIncrementPanelSplit class. Wide format Pandas (panel) dataframes are expected, multi-indexed by cross-section and date. It is recommended for the features to lag behind the associated targets by a single native frequency unit.

Parameters:

  • X (DataFrame) – Pandas dataframe of features, multi-indexed by (cross-section, date). The dates must be in datetime format. Otherwise the dataframe must be in wide format: each feature is a column.

  • y (DataFrame) – Pandas dataframe of the target variable, multi-indexed by (cross-section, date). The dates must be in datetime format.

  • groups – Always ignored, exists for compatibility with scikit-learn.

Return <Iterable[Tuple[np.ndarray[int],np.ndarray[int]]]> splits:

Iterable of (train,test) indices.

Return type:

Iterable[Tuple[ndarray, ndarray]]

get_n_splits(X=None, y=None, groups=None)[source]#

Calculates and returns the number of splits.

Parameters:

  • X – Pandas dataframe of features, multi-indexed by (cross-section, date). The dates must be in datetime format. Otherwise the dataframe must be in wide format: each feature is a column.

  • y – Pandas dataframe of the target variable, multi-indexed by (cross-section, date). The dates must be in datetime format.

  • groups – Always ignored, exists for compatibility.

Return <int> n_splits:

Returns the number of splits.

Return type:

int