skfolio 0.0.1__py3-none-any.whl

skfolio/metrics/_scorer.py

@@ -0,0 +1,121 @@
+"""Scorer module"""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+from collections.abc import Callable
+
+import numpy.typing as npt
+
+import skfolio.typing as skt
+from skfolio.optimization import BaseOptimization
+from skfolio.portfolio import Portfolio
+
+
+class _PortfolioScorer:
+    """Portfolio Scorer wrapper"""
+
+    def __init__(self, score_func: Callable, sign: int, kwargs: dict):
+        self._score_func = score_func
+        self._kwargs = kwargs
+        self._sign = sign
+
+    def __repr__(self) -> str:
+        """String representation of the `PortfolioScorer`."""
+        kwargs_string = "".join([f", {k}={v}" for k, v in self._kwargs.items()])
+        return (
+            f"make_scorer({self._score_func.__name__}"
+            f"{'' if self._sign > 0 else ', greater_is_better=False'}"
+            f"{kwargs_string})"
+        )
+
+    def __call__(self, estimator: BaseOptimization, X: npt.ArrayLike) -> float:
+        """Compute the score of the estimator prediction on X.
+
+        Parameters
+        ----------
+        estimator : BaseOptimization
+            Trained estimator to use for scoring.
+
+        X : array-like of shape (n_observations, n_assets)
+            Test data that will be fed to estimator.predict.
+
+        Returns
+        -------
+        score : float
+            Score of the estimator prediction on X.
+        """
+        pred = estimator.predict(X)
+        return self._sign * self._score_func(pred, **self._kwargs)
+
+
+def make_scorer(
+    score_func: skt.Measure | Callable,
+    greater_is_better: bool | None = None,
+    **kwargs,
+) -> Callable:
+    """Make a scorer from a :ref:`measure <measures_ref>` or from a custom score
+    function.
+
+    This is a modified version from `scikit-learn` `make_scorer` for enhanced
+    functionalities with `Portfolio` objects.
+
+    This factory function wraps scoring functions for use in
+    `sklearn.model_selection.GridSearchCV` and
+    `sklearn.model_selection.cross_val_score`.
+
+    Parameters
+    ----------
+    score_func : Measure | callable
+        If `score_func` is a :ref:`measure <measures_ref>`, we return the measure of
+        the predicted :class:`~skfolio.portfolio.Portfolio` times `1` or `-1`
+        depending on the `greater_is_better` parameter.
+
+        Otherwise, `score_func` must be a score function (or loss function) with
+        signature `score_func(pred, **kwargs)`. The argument `pred` is the predicted
+        :class:`~skfolio.portfolio.Portfolio`.
+
+        Note that you can convert this portfolio object into a numpy array of price
+        returns with `np.asarray(pred)`.
+
+    greater_is_better : bool, optional
+        If this is set to True, `score_func` is a score function (default) meaning high
+        is good, otherwise it is a loss function, meaning low is good.
+        In the latter case, the scorer object will sign-flip the outcome of the `score_func`.
+        The default (`None`) is to use:
+
+        * If `score_func` is a :ref:`measure <measures_ref>`:
+
+            * True for `PerfMeasure` and `RationMeasure`
+            * False for `RiskMeasure` and `ExtraRiskMeasure`.
+
+        * Otherwise, True.
+
+    **kwargs : additional arguments
+        Additional parameters to be passed to score_func.
+
+    Returns
+    -------
+    scorer : callable
+        Callable object that returns a scalar score.
+    """
+    if callable(score_func):
+        if greater_is_better is None:
+            greater_is_better = True
+
+    else:
+        measure = score_func
+        if not isinstance(measure, skt.Measure):
+            raise TypeError("`score_func` must be a callable or a measure")
+        if greater_is_better is None:
+            if measure.is_perf or measure.is_ratio:
+                greater_is_better = True
+            else:
+                greater_is_better = False
+
+        def score_func(pred: Portfolio) -> float:
+            """Score function"""
+            return getattr(pred, measure.value)
+
+    sign = 1 if greater_is_better else -1
+    return _PortfolioScorer(score_func, sign, kwargs)

skfolio/model_selection/__init__.py

@@ -0,0 +1,18 @@
+"""Model selection module"""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+from skfolio.model_selection._combinatorial import (
+    BaseCombinatorialCV,
+    CombinatorialPurgedCV,
+)
+from skfolio.model_selection._validation import cross_val_predict
+from skfolio.model_selection._walk_forward import WalkForward
+
+__all__ = [
+    "cross_val_predict",
+    "WalkForward",
+    "BaseCombinatorialCV",
+    "CombinatorialPurgedCV",
+]

skfolio/model_selection/_combinatorial.py

@@ -0,0 +1,407 @@
+"""Combinatorial module"""
+
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# License: BSD 3 clause
+
+import itertools
+import math
+import numbers
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+import plotly.graph_objects as go
+import sklearn.model_selection as skm
+import sklearn.utils as sku
+
+import skfolio.typing as skt
+
+
+class BaseCombinatorialCV(ABC):
+    """Base class for all combinatorial cross-validators.
+
+    Implementations must define `split` or `get_path_ids`.
+    """
+
+    @abstractmethod
+    def split(self, X: npt.ArrayLike, y=None) -> tuple[np.ndarray, list[np.ndarray]]:
+        pass
+
+    @abstractmethod
+    def get_path_ids(self) -> np.ndarray:
+        """Return the path id of each test sets in each split"""
+        pass
+
+    __repr__ = skm.BaseCrossValidator.__repr__
+
+
+# TODO: review params and function naming
+class CombinatorialPurgedCV(BaseCombinatorialCV):
+    """Combinatorial Purged Cross-Validation.
+
+    Provides train/test indices to split time series data samples based on
+    Combinatorial Purged Cross-Validation [1]_.
+
+    Compared to `KFold` which split the data into `k` folds with `1` fold for the test
+    set and `k - 1` folds for the training set, `CombinatorialPurgedCV` uses `k - p`
+    folds for the training set with `p > 1` being the number of test folds.
+
+    `KFold` can recombine one single testing path while `CombinatorialPurgedCV` can
+    recombine multiple testing paths from the combinations of the train/test sets.
+
+    To avoid data leakage, purging and embargoing can be performed.
+
+    Purging consist of removing from the training set all observations whose labels
+    overlapped in time with those labels included in the testing set.
+
+    Embargoing consist of removing from the training set all observations that
+    immediately follow an observation in the testing set since financial features
+    often incorporate series that exhibit serial correlation (like ARMA processes).
+
+    Parameters
+    ----------
+    n_folds : int, default=10
+        Number of folds. Must be at least 3.
+
+    n_test_folds : int, default=8
+        Number of test folds. Must be at least 2.
+        For only one test fold, use `sklearn.model_validation.KFold`.
+
+    purged_size : int, default=0
+        Number of observations to exclude from the start of each train set that are
+        after a test set **and** the number of observations to exclude from the end of
+        each training set that are before a test set.
+
+    embargo_size : int, default=0
+        Number of observations to exclude from the start of each training set that are
+        after a test set.
+
+    Attributes
+    ----------
+    index_train_test_ : ndarray of shape (n_observations, n_splits)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from skfolio.model_selection import CombinatorialPurgedCV
+    >>> X = np.random.randn(12, 2)
+    >>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2)
+    >>> for i, (train_index, tests) in enumerate(cv.split(X)):
+    ...     print(f"Split {i}:")
+    ...     print(f"  Train: index={train_index}")
+    ...     for j, test_index in enumerate(tests):
+    ...         print(f"  Test {j}:  index={test_index}")
+    Split 0:
+      Train: index=[ 8  9 10 11]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[4 5 6 7]
+    Split 1:
+      Train: index=[4 5 6 7]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[ 8  9 10 11]
+    Split 2:
+      Train: index=[0 1 2 3]
+      Test 0:  index=[4 5 6 7]
+      Test 1:  index=[ 8  9 10 11]
+    >>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2, purged_size=1)
+    >>> for i, (train_index, tests) in enumerate(cv.split(X)):
+    ...     print(f"Split {i}:")
+    ...     print(f"  Train: index={train_index}")
+    ...     for j, test_index in enumerate(tests):
+    ...         print(f"  Test {j}:  index={test_index}")
+    Split 0:
+      Train: index=[ 9 10 11]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[4 5 6 7]
+    Split 1:
+      Train: index=[5 6]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[ 8  9 10 11]
+    Split 2:
+      Train: index=[0 1 2]
+      Test 0:  index=[4 5 6 7]
+      Test 1:  index=[ 8  9 10 11]
+    >>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2, embargo_size=1)
+    >>> for i, (train_index, tests) in enumerate(cv.split(X)):
+    ...     print(f"Split {i}:")
+    ...     print(f"  Train: index={train_index}")
+    ...     for j, test_index in enumerate(tests):
+    ...         print(f"  Test {j}:  index={test_index}")
+    Split 0:
+      Train: index=[ 9 10 11]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[4 5 6 7]
+    Split 1:
+      Train: index=[5 6 7]
+      Test 0:  index=[0 1 2 3]
+      Test 1:  index=[ 8  9 10 11]
+    Split 2:
+      Train: index=[0 1 2 3]
+      Test 0:  index=[4 5 6 7]
+      Test 1:  index=[ 8  9 10 11]
+
+    References
+    ----------
+    .. [1]  "Advances in Financial Machine Learning",
+        Marcos López de Prado (2018)
+    """
+
+    index_train_test_: np.ndarray
+
+    def __init__(
+        self,
+        n_folds: int = 10,
+        n_test_folds: int = 8,
+        purged_size: int = 0,
+        embargo_size: int = 0,
+    ):
+        if not isinstance(n_folds, numbers.Integral):
+            raise ValueError(
+                "The number of folds must be of Integral type. "
+                f"{n_folds} of type {type(n_folds)} was passed."
+            )
+        n_folds = int(n_folds)
+
+        if n_folds <= 2:
+            raise ValueError(f"`n_folds` must be at least 3`, got `n_folds={n_folds}`.")
+
+        if n_test_folds <= 1:
+            raise ValueError(
+                f"`n_test_folds` must at least 2, got `n_test_folds={n_test_folds}`."
+            )
+
+        if n_test_folds >= n_folds:
+            raise ValueError(
+                "Combinatorial purged cross-validation requires `n_folds` "
+                "to be greater than `n_test_folds`."
+            )
+
+        if purged_size < 0:
+            raise ValueError("`purged_size` cannot be negative")
+
+        if embargo_size < 0:
+            raise ValueError("`embargo_size` cannot be negative")
+
+        self.n_folds = n_folds
+        self.n_test_folds = n_test_folds
+        self.purged_size = purged_size
+        self.embargo_size = embargo_size
+
+    @property
+    def n_splits(self) -> int:
+        """Number of splits"""
+        return int(
+            math.factorial(self.n_folds)
+            / (
+                math.factorial(self.n_test_folds)
+                * math.factorial(self.n_folds - self.n_test_folds)
+            )
+        )
+
+    @property
+    def n_test_paths(self) -> int:
+        """Number of test paths that can be reconstructed from the train/test
+        combinations"""
+        return self.n_splits * self.n_test_folds // self.n_folds
+
+    @property
+    def test_set_index(self) -> np.ndarray:
+        """Location of each test set"""
+        return np.array(
+            list(itertools.combinations(np.arange(self.n_folds), self.n_test_folds))
+        ).reshape(-1, self.n_test_folds)
+
+    @property
+    def binary_train_test_sets(self) -> np.ndarray:
+        """Identify training and test folds for each combinations by assigning `0` to
+        training folds and `1` to test folds"""
+        folds_train_test = np.zeros((self.n_folds, self.n_splits))
+        folds_train_test[
+            self.test_set_index, np.arange(self.n_splits)[:, np.newaxis]
+        ] = 1
+        return folds_train_test
+
+    @property
+    def recombined_paths(self) -> np.ndarray:
+        """Recombine each test path by returning the test set location in each split."""
+        return np.argwhere(self.binary_train_test_sets == 1)[:, 1].reshape(
+            self.n_folds, -1
+        )
+
+    def get_path_ids(self) -> np.ndarray:
+        """Return the path id of each test sets in each split"""
+        recombine_paths = self.recombined_paths
+        path_ids = np.zeros((self.n_splits, self.n_test_folds), dtype=int)
+        for i in range(self.n_splits):
+            for j in range(self.n_test_folds):
+                path_ids[i, j] = np.argwhere(recombine_paths == i)[j][1]
+        return path_ids
+
+    def split(
+        self, X: npt.ArrayLike, y=None, groups=None
+    ) -> Iterator[tuple[np.ndarray, list[np.ndarray]]]:
+        """Generate indices to split data into training and test set.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Training data, where `n_samples` is the number of samples
+            and `n_features` is the number of features.
+
+        y : array-like of shape (n_samples,), optional
+            The (multi-)target variable
+
+        groups : array-like of shape (n_samples,), optional
+            Group labels for the samples used while splitting the dataset into
+            train/test set.
+
+        Yields
+        ------
+        train : ndarray
+            The training set indices for that split.
+
+        test : ndarray
+            The testing set indices for that split.
+        """
+        test_set_index = self.test_set_index
+        recombine_paths = self.recombined_paths
+
+        X, y = sku.indexable(X, y)
+        n_samples = X.shape[0]
+        min_fold_size = n_samples // self.n_folds
+        if self.purged_size + self.embargo_size >= min_fold_size - 1:
+            raise ValueError(
+                "The sum of `purged_size` and `embargo_size` must be smaller than the"
+                f" size of a train fold which is {min_fold_size}"
+            )
+
+        fold_index_num = np.arange(n_samples) // (n_samples // self.n_folds)
+        fold_index_num[fold_index_num == self.n_folds] = self.n_folds - 1
+
+        index_train_test = np.zeros((n_samples, self.n_splits))
+        for i in range(self.n_splits):
+            index_train_test[
+                np.argwhere([fold_index_num == j for j in test_set_index[i]])[:, 1], i
+            ] = 1
+
+        diff = np.diff(index_train_test, axis=0)
+
+        # Purge before
+        before_index = np.argwhere(diff == 1)
+        for k in range(self.purged_size):
+            index_train_test[
+                np.maximum(0, before_index[:, 0] - k), before_index[:, 1]
+            ] = -1
+
+        # Purge after and Embargo
+        after_index = np.argwhere(diff == -1)
+        for k in range(self.purged_size + self.embargo_size):
+            index_train_test[
+                np.minimum(n_samples - 1, after_index[:, 0] + k + 1), after_index[:, 1]
+            ] = -1
+        self.index_train_test_ = index_train_test
+
+        fold_index = {
+            fold_id: np.argwhere(fold_index_num == fold_id).reshape(-1)
+            for fold_id in range(self.n_folds)
+        }
+        for i in range(self.n_splits):
+            train_index = np.argwhere(index_train_test[:, i] == 0).reshape(-1)
+            test_index_list = [
+                fold_index[fold_id] for fold_id, _ in np.argwhere(recombine_paths == i)
+            ]
+            yield train_index, test_index_list
+
+    def summary(self, X) -> pd.Series:
+        n_samples = X.shape[0]
+        return pd.Series(
+            {
+                "Number of Observations": n_samples,
+                "Total Number of Folds": self.n_folds,
+                "Number of Test Folds": self.n_test_folds,
+                "Purge Size": self.purged_size,
+                "Embargo Size": self.embargo_size,
+                "Average Training Size": int(
+                    n_samples / self.n_folds * (self.n_folds - self.n_test_folds)
+                ),
+                "Number of Test Paths": self.n_test_paths,
+                "Number of Training Combinations": self.n_splits,
+            }
+        )
+
+    def plot_train_test_folds(self) -> skt.Figure:
+        """Plot the train/test fold locations"""
+        values = self.binary_train_test_sets
+        fill_color = np.where(values == 0, "blue", "red")
+        fill_color = fill_color.astype(object)
+        fill_color = np.insert(
+            fill_color, 0, np.array(["darkblue" for _ in range(self.n_splits)]), axis=0
+        )
+        values = np.insert(values, 0, np.arange(self.n_splits), axis=0)
+        fig = go.Figure(
+            data=[
+                go.Table(
+                    header=dict(
+                        values=["Train Combinations"]
+                        + [f"Fold {i}" for i in range(self.n_folds)],
+                        fill_color="darkblue",
+                        font=dict(color="white"),
+                        align="left",
+                    ),
+                    cells=dict(
+                        values=values,
+                        font=dict(color="white"),
+                        fill_color=fill_color,
+                        line_color="grey",
+                        align="left",
+                    ),
+                )
+            ]
+        )
+        fig.update_layout(title="Split Train (0) /Test (1) Folds per Combination")
+        return fig
+
+    def plot_train_test_index(self, X) -> skt.Figure:
+        """Plot the training and test indices for each combinations by assigning `0` to
+        training, `1` to test and `-1` to both purge and embargo indices."""
+        next(self.split(X))
+        n_samples = X.shape[0]
+        cond = [
+            self.index_train_test_ == -1,
+            self.index_train_test_ == 0,
+            self.index_train_test_ == 1,
+        ]
+        values = self.index_train_test_.T
+        values = np.insert(values, 0, np.arange(n_samples), axis=0)
+        fill_color = np.select(cond, ["green", "blue", "red"]).T
+        fill_color = fill_color.astype(object)
+        fill_color = np.insert(
+            fill_color, 0, np.array(["darkblue" for _ in range(n_samples)]), axis=0
+        )
+        fig = go.Figure(
+            data=[
+                go.Table(
+                    header=dict(
+                        values=["observations"]
+                        + [f"Split {i}" for i in range(self.n_splits)],
+                        fill_color="darkblue",
+                        font=dict(color="white"),
+                        align="left",
+                    ),
+                    cells=dict(
+                        values=values,
+                        font=dict(color="white"),
+                        fill_color=fill_color,
+                        line_color="grey",
+                        align="left",
+                    ),
+                )
+            ]
+        )
+        fig.update_layout(
+            title="Train (0), Test (1) and Purge/Embargo (-1) observations per splits"
+        )
+
+        return fig