skfolio 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

skfolio/population/__init__.py

@@ -1,3 +1,5 @@
+"""Population module."""
+
 from skfolio.population._population import Population
 
 __all__ = ["Population"]

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:
@@ -814,8 +813,7 @@ class Population(list):
                         )
                         + "<extra></extra>",
                         colorbar=dict(
-                            title=str(z),
-                            titleside="top",
+                            title=dict(text=str(z), side="top"),
                             tickformat=",.2%" if not z.is_ratio else None,
                         ),
                     )
@@ -942,6 +940,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/_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
@@ -613,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
@@ -654,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):
@@ -679,7 +680,7 @@ class BasePortfolio:
     # Classic property
     @property
     def n_observations(self) -> int:
-        """Number of observations"""
+        """Number of observations."""
         return len(self.observations)
 
     @property
@@ -709,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)
@@ -1007,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
         ----------
@@ -1031,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
@@ -649,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
@@ -706,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

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

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

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

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

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
 

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,6 +8,7 @@ from skfolio.prior._factor_model import (
     FactorModel,
     LoadingMatrixRegression,
 )
+from skfolio.prior._synthetic_data import SyntheticData
 
 __all__ = [
     "BaseLoadingMatrix",
@@ -15,4 +18,5 @@ __all__ = [
     "FactorModel",
     "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.
@@ -39,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%
@@ -53,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"]]
@@ -119,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,

skfolio/prior/_empirical.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
 
 import numpy as np
 import numpy.typing as npt
@@ -75,6 +75,8 @@ class EmpiricalPrior(BasePrior):
 
     mu_estimator_: BaseMu
     covariance_estimator_: BaseCovariance
+    n_features_in_: int
+    feature_names_in_: np.ndarray
 
     def __init__(
         self,

skfolio/prior/_factor_model.py

@@ -1,8 +1,8 @@
-"""Factor Model estimator"""
+"""Factor Model estimator."""
 
 # 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.
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
@@ -200,6 +200,8 @@ class FactorModel(BasePrior):
 
     factor_prior_estimator_: BasePrior
     loading_matrix_estimator_: BaseLoadingMatrix
+    n_features_in_: int
+    feature_names_in_: np.ndarray
 
     def __init__(
         self,
@@ -266,6 +268,7 @@ class FactorModel(BasePrior):
         )
         factor_mu = self.factor_prior_estimator_.prior_model_.mu
         factor_covariance = self.factor_prior_estimator_.prior_model_.covariance
+        factor_returns = self.factor_prior_estimator_.prior_model_.returns
 
         # Fitting loading matrix estimator
         self.loading_matrix_estimator_.fit(X, y)
@@ -293,11 +296,12 @@ class FactorModel(BasePrior):
 
         mu = loading_matrix @ factor_mu + intercepts
         covariance = loading_matrix @ factor_covariance @ loading_matrix.T
-        returns = y @ loading_matrix.T + intercepts
+        returns = factor_returns @ loading_matrix.T + intercepts
         cholesky = loading_matrix @ np.linalg.cholesky(factor_covariance)
 
         if self.residual_variance:
-            err = X - returns
+            y_pred = y @ loading_matrix.T + intercepts
+            err = X - y_pred
             err_cov = np.diag(np.var(err, ddof=1, axis=0))
             covariance += err_cov
             cholesky = np.hstack((cholesky, np.sqrt(err_cov)))