skfolio 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

skfolio/uncertainty_set/_bootstrap.py

@@ -11,6 +11,7 @@
 import numpy as np
 import numpy.typing as npt
 import scipy.stats as st
+import sklearn.utils.metadata_routing as skm
 
 from skfolio.prior import BasePrior, EmpiricalPrior
 from skfolio.uncertainty_set._base import (
@@ -86,8 +87,6 @@ class BootstrapMuUncertaintySet(BaseMuUncertaintySet):
         Patton, Politis & White (2009).
     """
 
-    prior_estimator_: BasePrior
-
     def __init__(
         self,
         prior_estimator: BasePrior | None = None,
@@ -97,7 +96,7 @@ class BootstrapMuUncertaintySet(BaseMuUncertaintySet):
         block_size: float | None = None,
         seed: int | None = None,
     ):
-        self.prior_estimator = prior_estimator
+        super().__init__(prior_estimator=prior_estimator)
         self.confidence_level = confidence_level
         self.diagonal = diagonal
         self.n_bootstrap_samples = n_bootstrap_samples
@@ -105,7 +104,7 @@ class BootstrapMuUncertaintySet(BaseMuUncertaintySet):
         self.seed = seed
 
     def fit(
-        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None
+        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None, **fit_params
     ) -> "BootstrapMuUncertaintySet":
         """Fit the Bootstrap Mu Uncertainty set estimator.
 
@@ -118,18 +117,27 @@ class BootstrapMuUncertaintySet(BaseMuUncertaintySet):
             Price returns of factors.
             The default is `None`.
 
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
         Returns
         -------
         self : BootstrapMuUncertaintySet
             Fitted estimator.
         """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
+
         self.prior_estimator_ = check_estimator(
             self.prior_estimator,
             default=EmpiricalPrior(),
             check_type=BasePrior,
         )
         # fitting estimators
-        self.prior_estimator_.fit(X, y)
+        self.prior_estimator_.fit(X, y, **routed_params.prior_estimator.fit)
         mu = self.prior_estimator_.prior_model_.mu
         returns = self.prior_estimator_.prior_model_.returns
         n_assets = returns.shape[1]
@@ -217,8 +225,6 @@ class BootstrapCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
         Patton, Politis & White (2009).
     """
 
-    prior_estimator_: BasePrior
-
     def __init__(
         self,
         prior_estimator: BasePrior | None = None,
@@ -228,14 +234,16 @@ class BootstrapCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
         block_size: float | None = None,
         seed: int | None = None,
     ):
-        self.prior_estimator = prior_estimator
+        super().__init__(prior_estimator=prior_estimator)
         self.confidence_level = confidence_level
         self.diagonal = diagonal
         self.n_bootstrap_samples = n_bootstrap_samples
         self.block_size = block_size
         self.seed = seed
 
-    def fit(self, X: npt.ArrayLike, y=None) -> "BootstrapCovarianceUncertaintySet":
+    def fit(
+        self, X: npt.ArrayLike, y=None, **fit_params
+    ) -> "BootstrapCovarianceUncertaintySet":
         """Fit the Bootstrap Covariance Uncertainty set estimator.
 
         Parameters
@@ -247,11 +255,19 @@ class BootstrapCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
             Price returns of factors.
             The default is `None`.
 
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
         Returns
         -------
         self : EmpiricalCovarianceUncertaintySet
             Fitted estimator.
         """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
 
         self.prior_estimator_ = check_estimator(
             self.prior_estimator,
@@ -259,7 +275,7 @@ class BootstrapCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
             check_type=BasePrior,
         )
         # fitting estimators
-        self.prior_estimator_.fit(X, y)
+        self.prior_estimator_.fit(X, y, **routed_params.prior_estimator.fit)
         covariance = self.prior_estimator_.prior_model_.covariance
         returns = self.prior_estimator_.prior_model_.returns
         n_assets = returns.shape[1]

skfolio/uncertainty_set/_empirical.py

@@ -11,6 +11,7 @@
 import numpy as np
 import numpy.typing as npt
 import scipy.stats as st
+import sklearn.utils.metadata_routing as skm
 
 from skfolio.prior import BasePrior, EmpiricalPrior
 from skfolio.uncertainty_set._base import (
@@ -77,20 +78,18 @@ class EmpiricalMuUncertaintySet(BaseMuUncertaintySet):
         Schöttle & Werner (2009).
     """
 
-    prior_estimator_: BasePrior
-
     def __init__(
         self,
         prior_estimator: BasePrior | None = None,
         confidence_level: float = 0.95,
         diagonal: bool = True,
     ):
-        self.prior_estimator = prior_estimator
+        super().__init__(prior_estimator=prior_estimator)
         self.confidence_level = confidence_level
         self.diagonal = diagonal
 
     def fit(
-        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None
+        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None, **fit_params
     ) -> "EmpiricalMuUncertaintySet":
         """Fit the Empirical Mu Uncertainty set estimator.
 
@@ -103,18 +102,27 @@ class EmpiricalMuUncertaintySet(BaseMuUncertaintySet):
             Price returns of factors.
             The default is `None`.
 
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
         Returns
         -------
         self : EmpiricalMuUncertaintySet
             Fitted estimator.
         """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
+
         self.prior_estimator_ = check_estimator(
             self.prior_estimator,
             default=EmpiricalPrior(),
             check_type=BasePrior,
         )
         # fitting estimators
-        self.prior_estimator_.fit(X, y)
+        self.prior_estimator_.fit(X, y, **routed_params.prior_estimator.fit)
 
         prior_model = self.prior_estimator_.prior_model_
         n_observations, n_assets = prior_model.returns.shape
@@ -185,20 +193,18 @@ class EmpiricalCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
         Schöttle & Werner (2009).
     """
 
-    prior_estimator_: BasePrior
-
     def __init__(
         self,
         prior_estimator: BasePrior | None = None,
         confidence_level: float = 0.95,
         diagonal: bool = True,
     ):
-        self.prior_estimator = prior_estimator
+        super().__init__(prior_estimator=prior_estimator)
         self.confidence_level = confidence_level
         self.diagonal = diagonal
 
     def fit(
-        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None
+        self, X: npt.ArrayLike, y: npt.ArrayLike | None = None, **fit_params
     ) -> "EmpiricalCovarianceUncertaintySet":
         """Fit the Empirical Covariance Uncertainty set estimator.
 
@@ -211,18 +217,27 @@ class EmpiricalCovarianceUncertaintySet(BaseCovarianceUncertaintySet):
             Price returns of factors.
             The default is `None`.
 
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
         Returns
         -------
         self : EmpiricalCovarianceUncertaintySet
             Fitted estimator.
         """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
+
         self.prior_estimator_ = check_estimator(
             self.prior_estimator,
             default=EmpiricalPrior(),
             check_type=BasePrior,
         )
         # fitting estimators
-        self.prior_estimator_.fit(X, y)
+        self.prior_estimator_.fit(X, y, **routed_params.prior_estimator.fit)
 
         prior_model = self.prior_estimator_.prior_model_
         n_observations, n_assets = prior_model.returns.shape

skfolio/utils/stats.py

@@ -1,12 +1,13 @@
 """Tools module"""
 
+import warnings
+
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
 # License: BSD 3 clause
 # Implementation derived from:
 # Riskfolio-Lib, Copyright (c) 2020-2023, Dany Cajas, Licensed under BSD 3 clause.
 # Statsmodels, Copyright (C) 2006, Jonathan E. Taylor, Licensed under BSD 3 clause.
-
 from enum import auto
 
 import numpy as np
@@ -102,7 +103,7 @@ def n_bins_knuth(x: np.ndarray) -> int:
     x = np.sort(x)
     n = len(x)
 
-    def func(y: float):
+    def func(y: np.ndarray) -> float:
         y = y[0]
         if y <= 0:
             return np.inf
@@ -301,9 +302,18 @@ def corr_to_cov(corr: np.ndarray, std: np.ndarray):
 _CLIPPING_VALUE = 1e-13
 
 
-def cov_nearest(cov: np.ndarray, higham: bool = False, higham_max_iteration: int = 100):
+def cov_nearest(
+    cov: np.ndarray,
+    higham: bool = False,
+    higham_max_iteration: int = 100,
+    warn: bool = False,
+):
     """Compute the nearest covariance matrix that is positive definite and with a
     cholesky decomposition than can be computed. The variance is left unchanged.
+    A covariance matrix that is not positive definite often occurs in high
+    dimensional problems. It can be due to multicollinearity, floating-point
+    inaccuracies, or when the number of observations is smaller than the number of
+    assets.
 
     First, it converts the covariance matrix to a correlation matrix.
     Then, it finds the nearest correlation matrix and converts it back to a covariance
@@ -330,6 +340,10 @@ def cov_nearest(cov: np.ndarray, higham: bool = False, higham_max_iteration: int
         Maximum number of iteration of the Higham & Nick (2002) algorithm.
         The default value is `100`.
 
+    warn : bool, default=False
+        If this is set to True, a user warning is emitted when the covariance matrix
+        is not positive definite and replaced by the nearest. The default is False.
+
     Returns
     -------
     cov : ndarray
@@ -348,6 +362,13 @@ def cov_nearest(cov: np.ndarray, higham: bool = False, higham_max_iteration: int
     if is_cholesky_dec(cov) and is_positive_definite(cov):
         return cov
 
+    if warn:
+        warnings.warn(
+            "The covariance matrix is not positive definite. "
+            f"The {'Higham' if higham else 'Clipping'} algorithm will be used to find "
+            "the nearest positive definite covariance.",
+            stacklevel=2,
+        )
     corr, std = cov_to_corr(cov)
 
     if higham:

skfolio/utils/tools.py

@@ -15,6 +15,7 @@ from typing import Any
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
+import scipy.sparse as sp
 import sklearn as sk
 import sklearn.base as skb
 
@@ -29,9 +30,11 @@ __all__ = [
     "safe_split",
     "fit_single_estimator",
     "fit_and_predict",
+    "safe_indexing",
     "deduplicate_names",
     "default_asset_names",
     "check_estimator",
+    "get_feature_names",
 ]
 
 GenericAlias = type(list[int])
@@ -115,6 +118,144 @@ def _make_key(args, kwds) -> int:
     return hash(key)
 
 
+def _make_indexable(iterable):
+    """Ensure iterable supports indexing or convert to an indexable variant.
+
+    Convert sparse matrices to csr and other non-indexable iterable to arrays.
+    Let `None` and indexable objects (e.g. pandas dataframes) pass unchanged.
+
+    Parameters
+    ----------
+    iterable : {list, dataframe, ndarray, sparse matrix} or None
+        Object to be converted to an indexable iterable.
+    """
+    if sp.issparse(iterable):
+        return iterable.tocsr()
+    elif hasattr(iterable, "__getitem__") or hasattr(iterable, "iloc"):
+        return iterable
+    elif iterable is None:
+        return iterable
+    return np.array(iterable)
+
+
+def _check_method_params(
+    X: npt.ArrayLike, params: dict, indices: np.ndarray = None, axis: int = 0
+):
+    """Check and validate the parameters passed to a specific
+    method like `fit`.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_samples, n_features)
+        Data array.
+
+    params : dict
+        Dictionary containing the parameters passed to the method.
+
+    indices : ndarray of shape (n_samples,), default=None
+        Indices to be selected if the parameter has the same size as `X`.
+
+    axis : int, default=0
+        The axis along which `X` will be sub-sampled. `axis=0` will select
+        rows while `axis=1` will select columns.
+
+    Returns
+    -------
+    method_params_validated : dict
+        Validated parameters. We ensure that the values support indexing.
+    """
+    # noinspection PyUnresolvedReferences
+    n_observations = X.shape[0]
+    method_params_validated = {}
+    for param_key, param_value in params.items():
+        if param_value.shape[0] != n_observations:
+            raise ValueError(
+                f"param_key has wrong number of observations, "
+                f"received={param_value.shape[0]}, "
+                f"expected={n_observations}"
+            )
+        method_params_validated[param_key] = _make_indexable(param_value)
+        method_params_validated[param_key] = safe_indexing(
+            X=method_params_validated[param_key], indices=indices, axis=axis
+        )
+    return method_params_validated
+
+
+def safe_indexing(
+    X: npt.ArrayLike | pd.DataFrame, indices: npt.ArrayLike | None, axis: int = 0
+):
+    """Return rows, items or columns of X using indices.
+
+    Parameters
+    ----------
+    X : array-like
+        Data from which to sample rows.
+
+    indices : array-like, optional
+        Indices of rows or columns.
+        The default (`None`) is to select the entire data.
+
+    axis : int, default=0
+        The axis along which `X` will be sub-sampled. `axis=0` will select
+        rows while `axis=1` will select columns.
+
+    Returns
+    -------
+    subset :
+        Subset of X on axis 0.
+    """
+    if indices is None:
+        return X
+    if hasattr(X, "iloc"):
+        return X.take(indices, axis=axis)
+    if axis == 0:
+        return X[indices]
+    return X[:, indices]
+
+
+def safe_split(
+    X: npt.ArrayLike,
+    y: npt.ArrayLike | None = None,
+    indices: np.ndarray | None = None,
+    axis: int = 0,
+):
+    """Create subset of dataset.
+
+    Slice X, y according to indices for cross-validation.
+
+    Parameters
+    ----------
+    X : array-like
+        Data to be indexed.
+
+    y : array-like
+        Data to be indexed.
+
+    indices : ndarray of int, optional
+        Rows or columns to select from X and y.
+        The default (`None`) is to select the entire data.
+
+    axis : int, default=0
+        The axis along which `X` will be sub-sampled. `axis=0` will select
+        rows while `axis=1` will select columns.
+
+    Returns
+    -------
+    X_subset : array-like
+        Indexed data.
+
+    y_subset : array-like
+        Indexed targets.
+    """
+
+    X_subset = safe_indexing(X, indices=indices, axis=axis)
+    if y is not None:
+        y_subset = safe_indexing(y, indices=indices, axis=axis)
+    else:
+        y_subset = None
+    return X_subset, y_subset
+
+
 def cache_method(cache_name: str) -> Callable:
     """Decorator that caches class methods results into a class dictionary.
 
@@ -348,86 +489,11 @@ def bisection(x: list[np.ndarray]) -> Iterator[list[np.ndarray, np.ndarray]]:
             yield [e[0:mid], e[mid:n]]
 
 
-def safe_indexing(
-    X: npt.ArrayLike | pd.DataFrame, indices: npt.ArrayLike | None, axis: int = 0
-):
-    """
-    Return rows, items or columns of X using indices.
-
-    Parameters
-    ----------
-    X : array-like
-        Data from which to sample rows.
-
-    indices : array-like, optional
-        Indices of rows or columns.
-        The default (`None`) is to select the entire data.
-
-    axis : int, default=0
-        The axis along which `X` will be sub-sampled. `axis=0` will select
-        rows while `axis=1` will select columns.
-
-    Returns
-    -------
-    subset :
-        Subset of X on axis 0.
-    """
-    if indices is None:
-        return X
-    if hasattr(X, "iloc"):
-        return X.take(indices, axis=axis)
-    if axis == 0:
-        return X[indices]
-    return X[:, indices]
-
-
-def safe_split(
-    X: npt.ArrayLike,
-    y: npt.ArrayLike | None = None,
-    indices: np.ndarray | None = None,
-    axis: int = 0,
-):
-    """Create subset of dataset.
-
-    Slice X, y according to indices for cross-validation.
-
-    Parameters
-    ----------
-    X : array-like
-        Data to be indexed.
-
-    y : array-like
-        Data to be indexed.
-
-    indices : ndarray of int, optional
-        Rows or columns to select from X and y.
-        The default (`None`) is to select the entire data.
-
-    axis : int, default=0
-        The axis along which `X` will be sub-sampled. `axis=0` will select
-        rows while `axis=1` will select columns.
-
-    Returns
-    -------
-    X_subset : array-like
-        Indexed data.
-
-    y_subset : array-like
-        Indexed targets.
-    """
-
-    X_subset = safe_indexing(X, indices=indices, axis=axis)
-    if y is not None:
-        y_subset = safe_indexing(y, indices=indices, axis=axis)
-    else:
-        y_subset = None
-    return X_subset, y_subset
-
-
 def fit_single_estimator(
     estimator: Any,
     X: npt.ArrayLike,
-    y: npt.ArrayLike | None = None,
+    y: npt.ArrayLike | None,
+    fit_params: dict,
     indices: np.ndarray | None = None,
     axis: int = 0,
 ):
@@ -444,6 +510,9 @@ def fit_single_estimator(
     y : array-like of shape (n_observations, n_targets), optional
         The target array if provided.
 
+    fit_params : dict
+        Parameters that will be passed to `estimator.fit`.
+
     indices : ndarray of int, optional
         Rows or columns to select from X and y.
         The default (`None`) is to select the entire data.
@@ -457,9 +526,11 @@ def fit_single_estimator(
     fitted_estimator : estimator
         The fitted estimator.
     """
+    fit_params = fit_params if fit_params is not None else {}
+    fit_params = _check_method_params(X, params=fit_params, indices=indices, axis=axis)
 
     X, y = safe_split(X, y, indices=indices, axis=axis)
-    estimator.fit(X, y)
+    estimator.fit(X, y, **fit_params)
     return estimator
 
 
@@ -493,7 +564,7 @@ def fit_and_predict(
         Indices of test samples or list of indices.
 
     fit_params : dict
-        Parameters that will be passed to ``estimator.fit``.
+        Parameters that will be passed to `estimator.fit`.
 
     method : str
         Invokes the passed method name of the passed estimator.
@@ -511,6 +582,8 @@ def fit_and_predict(
         results of calling 'estimator.method' on each test set in `test`.
     """
     fit_params = fit_params if fit_params is not None else {}
+    fit_params = _check_method_params(X, params=fit_params, indices=train)
+
     X, y = safe_split(X, y, indices=column_indices, axis=1)
     X_train, y_train = safe_split(X, y, indices=train, axis=0)
     if y_train is None:
@@ -570,3 +643,64 @@ def deduplicate_names(names: npt.ArrayLike) -> list[str]:
             names[i] = f"{col}_{cur_count}"
         counts[col] = cur_count + 1
     return names
+
+
+def get_feature_names(X):
+    """Get feature names from X.
+
+    Support for other array containers should place its implementation here.
+
+    Parameters
+    ----------
+    X : {ndarray, dataframe} of shape (n_samples, n_features)
+        Array container to extract feature names.
+
+        - pandas dataframe : The columns will be considered to be feature
+          names. If the dataframe contains non-string feature names, `None` is
+          returned.
+        - All other array containers will return `None`.
+
+    Returns
+    -------
+    names: ndarray or None
+        Feature names of `X`. Unrecognized array containers will return `None`.
+    """
+    feature_names = None
+
+    # extract feature names for support array containers
+    if isinstance(X, pd.DataFrame):
+        # Make sure we can inspect columns names from pandas, even with
+        # versions too old to expose a working implementation of
+        # __dataframe__.column_names() and avoid introducing any
+        # additional copy.
+        # TODO: remove the pandas-specific branch once the minimum supported
+        # version of pandas has a working implementation of
+        # __dataframe__.column_names() that is guaranteed to not introduce any
+        # additional copy of the data without having to impose allow_copy=False
+        # that could fail with other libraries. Note: in the longer term, we
+        # could decide to instead rely on the __dataframe_namespace__ API once
+        # adopted by our minimally supported pandas version.
+        feature_names = np.asarray(X.columns, dtype=object)
+    elif hasattr(X, "__dataframe__"):
+        df_protocol = X.__dataframe__()
+        feature_names = np.asarray(list(df_protocol.column_names()), dtype=object)
+
+    if feature_names is None or len(feature_names) == 0:
+        return
+
+    types = sorted(t.__qualname__ for t in set(type(v) for v in feature_names))
+
+    # mixed type of string and non-string is not supported
+    if len(types) > 1 and "str" in types:
+        raise TypeError(
+            "Feature names are only supported if all input features have string names, "
+            f"but your input has {types} as feature name / column name types. "
+            "If you want feature names to be stored and validated, you must convert "
+            "them all to strings, by using X.columns = X.columns.astype(str) for "
+            "example. Otherwise you can remove feature / column names from your input "
+            "data, or convert them all to a non-string data type."
+        )
+
+    # Only feature names of all strings are supported
+    if len(types) == 1 and types[0] == "str":
+        return feature_names

{skfolio-0.2.3.dist-info → skfolio-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: skfolio
-Version: 0.2.3
+Version: 0.3.0
 Summary: Portfolio optimization built on top of scikit-learn
 Author-email: Hugo Delatte <delatte.hugo@gmail.com>
 Maintainer-email: Hugo Delatte <delatte.hugo@gmail.com>
@@ -60,7 +60,7 @@ Requires-Dist: numpy <2.0.0,>=1.23.4
 Requires-Dist: scipy >=1.8.0
 Requires-Dist: pandas >=1.4.1
 Requires-Dist: cvxpy >=1.4.1
-Requires-Dist: scikit-learn >=1.3.2
+Requires-Dist: scikit-learn >=1.5.0
 Requires-Dist: joblib >=1.3.2
 Requires-Dist: plotly >=5.22.0
 Provides-Extra: docs
@@ -237,6 +237,7 @@ Available models
     * Oracle Approximating Shrinkage
     * Shrunk Covariance
     * Graphical Lasso CV
+    * Implied Covariance
 
 * Distance Estimator:
     * Pearson Distance