skfolio 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

skfolio/population/_population.py

@@ -4,7 +4,7 @@ A population is a collection of portfolios.
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import inspect
 from typing import Any
@@ -14,6 +14,7 @@ import pandas as pd
 import plotly.express as px
 import plotly.graph_objects as go
 import scipy.interpolate as sci
+import scipy.stats as st
 
 import skfolio.typing as skt
 from skfolio.measures import RatioMeasure
@@ -285,7 +286,7 @@ class Population(list):
         measure: skt.Measure,
         q: float,
     ) -> BasePortfolio:
-        """Returns the portfolio corresponding to the `q` quantile for a given portfolio
+        """Return the portfolio corresponding to the `q` quantile for a given portfolio
         measure.
 
         Parameters
@@ -311,7 +312,7 @@ class Population(list):
         self,
         measure: skt.Measure,
     ) -> BasePortfolio:
-        """Returns the portfolio with the minimum measure.
+        """Return the portfolio with the minimum measure.
 
         Parameters
         ----------
@@ -329,7 +330,7 @@ class Population(list):
         self,
         measure: skt.Measure,
     ) -> BasePortfolio:
-        """Returns the portfolio with the maximum measure.
+        """Return the portfolio with the maximum measure.
 
         Parameters
         ----------
@@ -347,7 +348,7 @@ class Population(list):
         self,
         formatted: bool = True,
     ) -> pd.DataFrame:
-        """Summary of the portfolios in the population
+        """Summary of the portfolios in the population.
 
         Parameters
         ----------
@@ -361,7 +362,6 @@ class Population(list):
         summary : pandas DataFrame
             The population's portfolios summary
         """
-
         df = pd.concat(
             [p.summary(formatted=formatted) for p in self],
             keys=[p.name for p in self],
@@ -473,7 +473,6 @@ class Population(list):
         dataframe : pandas DataFrame
             The rolling measures.
         """
-
         rolling_measures = []
         names = []
         for ptf in self:
@@ -942,6 +941,34 @@ class Population(list):
         )
         return fig
 
+    def plot_returns_distribution(self) -> go.Figure:
+        """Plot the Portfolios returns distribution using Gaussian KDE.
+
+        Returns
+        -------
+        plot : Figure
+            Returns the plot Figure object
+        """
+        traces = []
+        for ptf in self:
+            lower = np.percentile(ptf.returns, 1e-1)
+            upper = np.percentile(ptf.returns, 100 - 1e-1)
+            x = np.linspace(lower, upper, 500)
+            y = st.gaussian_kde(ptf.returns)(x)
+            traces.append(
+                go.Scatter(x=x, y=y, mode="lines", fill="tozeroy", name=ptf.name)
+            )
+        fig = go.Figure(traces)
+        fig.update_layout(
+            title="Returns Distribution",
+            xaxis_title="Returns",
+            yaxis_title="Probability Density",
+        )
+        fig.update_xaxes(
+            tickformat=".0%",
+        )
+        return fig
+
 
 def _ptf_name_with_tag(portfolio: BasePortfolio) -> str:
     if portfolio.tag is None:

skfolio/portfolio/__init__.py

@@ -10,4 +10,4 @@ from skfolio.portfolio._base import BasePortfolio
 from skfolio.portfolio._multi_period_portfolio import MultiPeriodPortfolio
 from skfolio.portfolio._portfolio import Portfolio
 
-__all__ = ["BasePortfolio", "Portfolio", "MultiPeriodPortfolio"]
+__all__ = ["BasePortfolio", "MultiPeriodPortfolio", "Portfolio"]

skfolio/portfolio/_base.py

@@ -1,8 +1,8 @@
-"""Base Portfolio module"""
+"""Base Portfolio module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 # The Portfolio class contains more than 40 measures than can be computationally
 # expensive. The use of __slots__ instead of __dict__ is based on the following
@@ -45,6 +45,7 @@ import numpy as np
 import pandas as pd
 import plotly.express as px
 import plotly.graph_objects as go
+import scipy.stats as st
 
 import skfolio.typing as skt
 from skfolio import measures as mt
@@ -389,6 +390,7 @@ class BasePortfolio:
         "edar_beta",
     }
 
+    # ruff: noqa: RUF023
     __slots__ = {
         # public
         "tag",
@@ -612,14 +614,14 @@ class BasePortfolio:
     @property
     @abstractmethod
     def composition(self) -> pd.DataFrame:
-        """DataFrame of the Portfolio composition"""
+        """DataFrame of the Portfolio composition."""
         pass
 
     @abstractmethod
     def contribution(
         self, measure: skt.Measure, spacing: float | None = None, to_df: bool = True
     ) -> np.ndarray | pd.DataFrame:
-        """Compute the contribution of each asset to a given measure"""
+        """Compute the contribution of each asset to a given measure."""
         pass
 
     # Custom attribute setter and getter
@@ -653,7 +655,7 @@ class BasePortfolio:
     # Custom attribute getter (read-only and cached)
     @cached_property_slots
     def fitness(self) -> np.ndarray:
-        """The Portfolio fitness."""
+        """Portfolio fitness."""
         res = []
         for measure in self.fitness_measures:
             if isinstance(measure, PerfMeasure | RatioMeasure):
@@ -678,7 +680,7 @@ class BasePortfolio:
     # Classic property
     @property
     def n_observations(self) -> int:
-        """Number of observations"""
+        """Number of observations."""
         return len(self.observations)
 
     @property
@@ -708,7 +710,7 @@ class BasePortfolio:
         return self.__copy__()
 
     def clear(self) -> None:
-        """Clear all measures, fitness, cumulative returns and drawdowns in slots"""
+        """Clear all measures, fitness, cumulative returns and drawdowns in slots."""
         attrs = ["_fitness", "_cumulative_returns", "_drawdowns"]
         for attr in attrs + list(_MEASURES_VALUES):
             delattr(self, attr)
@@ -1006,7 +1008,7 @@ class BasePortfolio:
         return fig
 
     def plot_returns(self, idx: slice | np.ndarray | None = None) -> go.Figure:
-        """Plot the Portfolio returns
+        """Plot the Portfolio returns.
 
         Parameters
         ----------
@@ -1030,6 +1032,39 @@ class BasePortfolio:
         )
         return fig
 
+    def plot_returns_distribution(self) -> go.Figure:
+        """Plot the Portfolio returns distribution using Gaussian KDE.
+
+        Returns
+        -------
+        plot : Figure
+            Returns the plot Figure object
+        """
+        lower = np.percentile(self.returns, 1e-1)
+        upper = np.percentile(self.returns, 100 - 1e-1)
+        x = np.linspace(lower, upper, 500)
+        y = st.gaussian_kde(self.returns)(x)
+
+        fig = go.Figure(
+            go.Scatter(
+                x=x,
+                y=y,
+                mode="lines",
+                fill="tozeroy",
+            )
+        )
+
+        fig.update_layout(
+            title="Returns Distribution",
+            xaxis_title="Returns",
+            yaxis_title="Probability Density",
+            showlegend=False,
+        )
+        fig.update_xaxes(
+            tickformat=".0%",
+        )
+        return fig
+
     def plot_rolling_measure(
         self,
         measure: skt.Measure = RatioMeasure.SHARPE_RATIO,

skfolio/portfolio/_multi_period_portfolio.py

@@ -5,7 +5,7 @@
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numbers
 from collections.abc import Iterator
@@ -538,7 +538,8 @@ class MultiPeriodPortfolio(BasePortfolio):
     @portfolios.setter
     def portfolios(self, value: list[Portfolio] | None = None):
         """Set the list of Portfolios and clear the attributes cache linked to the
-        list of portfolios."""
+        list of portfolios.
+        """
         self._set_portfolios(portfolios=value)
         self.clear()
 

skfolio/portfolio/_portfolio.py

@@ -6,7 +6,7 @@ is the dot product of the assets weights with the assets returns.
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numbers
 from typing import ClassVar
@@ -412,6 +412,7 @@ class Portfolio(BasePortfolio):
         }
     )
 
+    # ruff: noqa: RUF023
     __slots__ = {
         # read-only
         "X",
@@ -648,12 +649,12 @@ class Portfolio(BasePortfolio):
     # Custom attribute getter (read-only and cached)
     @cached_property_slots
     def nonzero_assets(self) -> np.ndarray:
-        """Invested asset :math:`abs(weights) > 0.001%`"""
+        """Invested asset :math:`abs(weights) > 0.001%`."""
         return self.assets[self.nonzero_assets_index]
 
     @cached_property_slots
     def nonzero_assets_index(self) -> np.ndarray:
-        """Indices of invested asset :math:`abs(weights) > 0.001%`"""
+        """Indices of invested asset :math:`abs(weights) > 0.001%`."""
         return np.flatnonzero(abs(self.weights) > _ZERO_THRESHOLD)
 
     @property
@@ -705,7 +706,7 @@ class Portfolio(BasePortfolio):
     @property
     def effective_number_assets(self) -> float:
         r"""Computes the effective number of assets, defined as the inverse of the
-        Herfindahl index [1]_:
+        Herfindahl index.
 
         .. math:: N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}
 

skfolio/pre_selection/__init__.py

@@ -1,3 +1,5 @@
+"""Pre Selection module."""
+
 from skfolio.pre_selection._drop_correlated import DropCorrelated
 from skfolio.pre_selection._select_complete import SelectComplete
 from skfolio.pre_selection._select_k_extremes import SelectKExtremes
@@ -6,8 +8,8 @@ from skfolio.pre_selection._select_non_expiring import SelectNonExpiring
 
 __all__ = [
     "DropCorrelated",
+    "SelectComplete",
     "SelectKExtremes",
     "SelectNonDominated",
-    "SelectComplete",
     "SelectNonExpiring",
 ]

skfolio/pre_selection/_drop_correlated.py

@@ -1,8 +1,8 @@
-"""Pre-selection DropCorrelated module"""
+"""Pre-selection DropCorrelated module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
@@ -74,7 +74,7 @@ class DropCorrelated(skf.SelectorMixin, skb.BaseEstimator):
         self : DropCorrelated
             Fitted estimator.
         """
-        X = self._validate_data(X)
+        X = skv.validate_data(self, X)
         if not -1 <= self.threshold <= 1:
             raise ValueError("`threshold` must be between -1 and 1")
 

skfolio/pre_selection/_select_complete.py

@@ -1,8 +1,8 @@
-"""pre-selection SelectComplete module"""
+"""pre-selection SelectComplete module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
@@ -49,30 +49,29 @@ class SelectComplete(skf.SelectorMixin, skb.BaseEstimator):
 
     Examples
     --------
-
-        >>> import numpy as np
-        >>> import pandas as pd
-        >>> from skfolio.pre_selection import SelectComplete
-        >>> X = pd.DataFrame({
-        ...     'asset1': [np.nan, np.nan, 2, 3, 4],    # Starts late (inception)
-        ...     'asset2': [1, 2, 3, 4, 5],         # Complete data
-        ...     'asset3': [1, 2, 3, np.nan, 5], # Missing values within data
-        ...     'asset4': [1, 2, 3, 4, np.nan]      # Ends early (expiration)
-        ... })
-        >>> selector = SelectComplete()
-        >>> selector.fit_transform(X)
-         array([[ 1.,  1.],
-                [ 2.,  2.],
-                [ 3.,  3.],
-                [ 4., nan],
-                [ 5.,  5.]])
-        >>> selector = SelectComplete(drop_assets_with_internal_nan=True)
-        >>> selector.fit_transform(X)
-         array([[1.],
-               [2.],
-               [3.],
-               [4.],
-               [5.]])
+    >>> import numpy as np
+    >>> import pandas as pd
+    >>> from skfolio.pre_selection import SelectComplete
+    >>> X = pd.DataFrame({
+    ...     'asset1': [np.nan, np.nan, 2, 3, 4],    # Starts late (inception)
+    ...     'asset2': [1, 2, 3, 4, 5],         # Complete data
+    ...     'asset3': [1, 2, 3, np.nan, 5], # Missing values within data
+    ...     'asset4': [1, 2, 3, 4, np.nan]      # Ends early (expiration)
+    ... })
+    >>> selector = SelectComplete()
+    >>> selector.fit_transform(X)
+     array([[ 1.,  1.],
+            [ 2.,  2.],
+            [ 3.,  3.],
+            [ 4., nan],
+            [ 5.,  5.]])
+    >>> selector = SelectComplete(drop_assets_with_internal_nan=True)
+    >>> selector.fit_transform(X)
+     array([[1.],
+           [2.],
+           [3.],
+           [4.],
+           [5.]])
     """
 
     to_keep_: np.ndarray
@@ -97,7 +96,7 @@ class SelectComplete(skf.SelectorMixin, skb.BaseEstimator):
             Fitted estimator.
         """
         # Validate by allowing NaNs
-        X = self._validate_data(X, force_all_finite="allow-nan")
+        X = skv.validate_data(self, X, ensure_all_finite="allow-nan")
 
         if self.drop_assets_with_internal_nan:
             # Identify columns with any NaNs
@@ -108,9 +107,11 @@ class SelectComplete(skf.SelectorMixin, skb.BaseEstimator):
 
         return self
 
-    def _get_support_mask(self):
+    def _get_support_mask(self) -> np.ndarray:
         skv.check_is_fitted(self)
         return self.to_keep_
 
-    def _more_tags(self):
-        return {"allow_nan": True}
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True
+        return tags

skfolio/pre_selection/_select_k_extremes.py

@@ -1,8 +1,8 @@
-"""Pre-selection SelectKExtremes module"""
+"""Pre-selection SelectKExtremes module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
@@ -76,7 +76,7 @@ class SelectKExtremes(skf.SelectorMixin, skb.BaseEstimator):
         self : SelectKExtremes
             Fitted estimator.
         """
-        X = self._validate_data(X)
+        X = skv.validate_data(self, X)
         k = int(self.k)
         if k <= 0:
             raise ValueError("`k` must be strictly positive")

skfolio/pre_selection/_select_non_dominated.py

@@ -1,8 +1,8 @@
-"""Pre-selection SelectNonDominated module"""
+"""Pre-selection SelectNonDominated module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
@@ -95,7 +95,7 @@ class SelectNonDominated(skf.SelectorMixin, skb.BaseEstimator):
         self : SelectNonDominated
             Fitted estimator.
         """
-        X = self._validate_data(X)
+        X = skv.validate_data(self, X)
         if not -1 <= self.threshold <= 1:
             raise ValueError("`threshold` must be between -1 and 1")
         n_assets = X.shape[1]

skfolio/pre_selection/_select_non_expiring.py

@@ -1,10 +1,10 @@
-"""pre-selection estimators module"""
+"""pre-selection estimators module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
 # Implementation derived from:
 # Conway-Yu https://github.com/skfolio/skfolio/discussions/60
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import datetime as dt
 
@@ -114,7 +114,7 @@ class SelectNonExpiring(skf.SelectorMixin, skb.BaseEstimator):
         self : SelectNonExpiring
             Fitted estimator.
         """
-        _ = self._validate_data(X, force_all_finite="allow-nan")
+        _ = skv.validate_data(self, X, ensure_all_finite="allow-nan")
 
         # Validate by allowing NaNs
         if not hasattr(X, "index") or not isinstance(X.index, pd.DatetimeIndex):
@@ -140,9 +140,11 @@ class SelectNonExpiring(skf.SelectorMixin, skb.BaseEstimator):
 
         return self
 
-    def _get_support_mask(self):
+    def _get_support_mask(self) -> np.ndarray:
         skv.check_is_fitted(self)
         return self.to_keep_
 
-    def _more_tags(self):
-        return {"allow_nan": True}
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True
+        return tags

skfolio/preprocessing/__init__.py

@@ -1,3 +1,5 @@
+"""Preprocessing module."""
+
 from skfolio.preprocessing._returns import prices_to_returns
 
 __all__ = ["prices_to_returns"]

skfolio/preprocessing/_returns.py

@@ -2,7 +2,7 @@
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from typing import Literal
 
@@ -19,7 +19,7 @@ def prices_to_returns(
     drop_inceptions_nan: bool = True,
     fill_nan: bool = True,
 ) -> pd.DataFrame | tuple[pd.DataFrame, pd.DataFrame]:
-    r"""Transforms a DataFrame of prices to linear or logarithmic returns.
+    r"""Transform a DataFrame of prices to linear or logarithmic returns.
 
     Linear returns (also called simple returns) are defined as:
         .. math:: \frac{S_{t}}{S_{t-1}} - 1

skfolio/prior/__init__.py

@@ -1,3 +1,5 @@
+"""Prior module."""
+
 from skfolio.prior._base import BasePrior, PriorModel
 from skfolio.prior._black_litterman import BlackLitterman
 from skfolio.prior._empirical import EmpiricalPrior
@@ -6,13 +8,15 @@ from skfolio.prior._factor_model import (
     FactorModel,
     LoadingMatrixRegression,
 )
+from skfolio.prior._synthetic_data import SyntheticData
 
 __all__ = [
-    "PriorModel",
+    "BaseLoadingMatrix",
     "BasePrior",
-    "EmpiricalPrior",
     "BlackLitterman",
+    "EmpiricalPrior",
     "FactorModel",
-    "BaseLoadingMatrix",
     "LoadingMatrixRegression",
+    "PriorModel",
+    "SyntheticData",
 ]

skfolio/prior/_base.py

@@ -1,8 +1,8 @@
-"""Base Prior estimator"""
+"""Base Prior estimator."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass

skfolio/prior/_black_litterman.py

@@ -2,7 +2,7 @@
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 # Implementation derived from:
 # Riskfolio-Lib, Copyright (c) 2020-2023, Dany Cajas, Licensed under BSD 3 clause.
 # PyPortfolioOpt, Copyright (c) 2018 Robert Andrew Martin, Licensed under MIT Licence.
@@ -10,6 +10,7 @@
 import numpy as np
 import numpy.typing as npt
 import sklearn.utils.metadata_routing as skm
+import sklearn.utils.validation as skv
 
 from skfolio.moments import EquilibriumMu
 from skfolio.prior._base import BasePrior, PriorModel
@@ -38,7 +39,7 @@ class BlackLitterman(BasePrior):
         about the assets expected returns expressed in the same frequency as the
         returns `X`.
 
-        Examples:
+        For example:
 
             * "SPX = 0.00015" --> the SPX will have a daily expected return of 0.015%
             * "SX5E - TLT = 0.00039" --> the SX5E will outperform the TLT by a daily expected return of 0.039%
@@ -52,7 +53,7 @@ class BlackLitterman(BasePrior):
         (asset name/asset groups) and the input `X` of the `fit` method must be a
         DataFrame with the assets names in columns.
 
-        Examples:
+        For example:
 
             * groups = {"SX5E": ["Equity", "Europe"], "SPX": ["Equity", "US"], "TLT": ["Bond", "US"]}
             * groups = [["Equity", "Equity", "Bond"], ["Europe", "US", "US"]]
@@ -118,6 +119,8 @@ class BlackLitterman(BasePrior):
     views_: np.ndarray
     picking_matrix_: np.ndarray
     prior_estimator_: BasePrior
+    n_features_in_: int
+    feature_names_in_: np.ndarray
 
     def __init__(
         self,
@@ -182,7 +185,7 @@ class BlackLitterman(BasePrior):
 
         # we validate after all models have been fitted to keep features names
         # information.
-        self._validate_data(X)
+        skv.validate_data(self, X)
 
         n_assets = prior_returns.shape[1]
         views = np.asarray(self.views)

skfolio/prior/_empirical.py

@@ -2,11 +2,12 @@
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
 import sklearn.utils.metadata_routing as skm
+import sklearn.utils.validation as skv
 
 from skfolio.moments import BaseCovariance, BaseMu, EmpiricalCovariance, EmpiricalMu
 from skfolio.prior._base import BasePrior, PriorModel
@@ -74,6 +75,8 @@ class EmpiricalPrior(BasePrior):
 
     mu_estimator_: BaseMu
     covariance_estimator_: BaseCovariance
+    n_features_in_: int
+    feature_names_in_: np.ndarray
 
     def __init__(
         self,
@@ -190,7 +193,7 @@ class EmpiricalPrior(BasePrior):
 
         # we validate and convert to numpy after all models have been fitted to keep
         # features names information.
-        X = self._validate_data(X)
+        X = skv.validate_data(self, X)
         self.prior_model_ = PriorModel(
             mu=mu,
             covariance=covariance,