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

skfolio/portfolio/_base.py

@@ -59,6 +59,7 @@ from skfolio.utils.tools import (
     args_names,
     cached_property_slots,
     format_measure,
+    optimal_rounding_decimals,
 )
 
 _ZERO_THRESHOLD = 1e-5
@@ -614,6 +615,13 @@ class BasePortfolio:
         """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"""
+        pass
+
     # Custom attribute setter and getter
     @property
     def fitness_measures(self) -> list[skt.Measure]:
@@ -811,7 +819,7 @@ class BasePortfolio:
             The measure. The default measure is the Sharpe Ratio.
 
         window : int, default=30
-            The window size. The default value is `30`.
+            The window size. The default value is `30` observations.
 
         Returns
         -------
@@ -925,11 +933,9 @@ class BasePortfolio:
                 key = f"{e!s} at {beta:.0%}"
             except AttributeError:
                 key = str(e)
-            if isinstance(e, RatioMeasure) or e in [
+            if e.is_ratio or e in [
                 ExtraRiskMeasure.ENTROPIC_RISK_MEASURE,
                 RiskMeasure.ULCER_INDEX,
-                ExtraRiskMeasure.SKEW,
-                ExtraRiskMeasure.KURTOSIS,
             ]:
                 percent = False
             else:
@@ -1053,19 +1059,18 @@ class BasePortfolio:
             line_dash="dash",
             line_color="blue",
         )
-        max_val = rolling.max()
-        min_val = rolling.min()
-        if max_val > 0:
+        max_val = np.max(rolling)
+        min_val = np.min(rolling)
+        if max_val > 0 > min_val:
             fig.add_hrect(
                 y0=0, y1=max_val * 1.3, line_width=0, fillcolor="green", opacity=0.1
             )
-        if min_val < 0:
             fig.add_hrect(
                 y0=min_val * 1.3, y1=0, line_width=0, fillcolor="red", opacity=0.1
             )
 
         fig.update_layout(
-            title=f"rolling {measure} - {window} observations window",
+            title=f"Rolling {measure} - {window} observations window",
             xaxis_title="Observations",
             yaxis_title=str(measure),
             showlegend=False,
@@ -1089,3 +1094,37 @@ class BasePortfolio:
             legend_title_text="Assets",
         )
         return fig
+
+    def plot_contribution(self, measure: skt.Measure, spacing: float | None = None):
+        r"""Plot the contribution of each asset to a given measure.
+
+        Parameters
+        ----------
+        measure : Measure
+            The measure used for the contribution computation.
+
+        spacing : float, optional
+            Spacing "h" of the finite difference:
+            :math:`contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}`
+
+        Returns
+        -------
+        plot : Figure
+            The plotly Figure of assets contribution to the measure.
+        """
+        df = self.contribution(measure=measure, spacing=spacing, to_df=True).T
+        fig = px.bar(df, x=df.index, y=df.columns)
+        yaxis = {
+            "title": "Contribution",
+        }
+        if not measure.is_ratio:
+            n = optimal_rounding_decimals(df.sum(axis=1).max())
+            yaxis["tickformat"] = f",.{n}%"
+
+        fig.update_layout(
+            title=f"{measure} Contribution",
+            xaxis_title="Portfolio",
+            yaxis=yaxis,
+            legend_title_text="Assets",
+        )
+        return fig

skfolio/portfolio/_multi_period_portfolio.py

@@ -556,6 +556,51 @@ class MultiPeriodPortfolio(BasePortfolio):
         df.columns = deduplicate_names(df.columns)
         return df
 
+    @property
+    def weights_per_observation(self) -> pd.DataFrame:
+        """DataFrame of the Portfolio weights per observation."""
+        return (
+            pd.concat([p.weights_per_observation for p in self], axis=0)
+            .fillna(0)
+            .sort_index()
+        )
+
+    def contribution(
+        self, measure: skt.Measure, spacing: float | None = None, to_df: bool = True
+    ) -> np.ndarray | pd.DataFrame:
+        r"""Compute the contribution of each asset to a given measure for each
+        portfolio.
+
+        Parameters
+        ----------
+        measure : Measure
+            The measure used for the contribution computation.
+
+        spacing : float, optional
+            Spacing "h" of the finite difference:
+            :math:`contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}`
+
+        to_df : bool, default=False
+            If this is set to True, a DataFrame with asset names in index and portfolio
+            names in columns is returned, otherwise a list of numpy array is returned.
+            When a DataFrame is returned, the assets with zero weights are removed.
+
+        Returns
+        -------
+        values : list of numpy array of shape (n_assets,) for each portfolio or a DataFrame
+            The measure contribution of each asset for each portfolio.
+        """
+        contributions = [
+            ptf.contribution(measure=measure, spacing=spacing, to_df=to_df)
+            for ptf in self
+        ]
+        if not to_df:
+            return contributions
+        df = pd.concat(contributions, axis=1)
+        df.fillna(0, inplace=True)
+        df.columns = deduplicate_names(df.columns)
+        return df
+
     def summary(self, formatted: bool = True) -> pd.Series:
         """Portfolio summary of all its measures.
 

skfolio/portfolio/_portfolio.py

@@ -14,7 +14,6 @@ from typing import ClassVar
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
-import plotly.express as px
 
 import skfolio.typing as skt
 from skfolio.measures import RiskMeasure, effective_number_assets
@@ -668,7 +667,20 @@ class Portfolio(BasePortfolio):
         return df
 
     @property
-    def diversification(self):
+    def weights_per_observation(self) -> pd.DataFrame:
+        """DataFrame of the Portfolio weights per observation."""
+        idx = self.nonzero_assets_index
+        weights = self.weights[idx]
+        assets = self.assets[idx]
+        df = pd.DataFrame(
+            np.ones((len(self.observations), len(assets))) * weights,
+            index=self.observations,
+            columns=assets,
+        )
+        return df
+
+    @property
+    def diversification(self) -> float:
         """Weighted average of volatility divided by the portfolio volatility."""
         return (
             self.weights @ np.std(np.asarray(self.X), axis=0) / self.standard_deviation
@@ -750,8 +762,8 @@ class Portfolio(BasePortfolio):
         return float(self.weights @ assets_covariance @ self.weights.T)
 
     def contribution(
-        self, measure: skt.Measure, spacing: float | None = None
-    ) -> np.ndarray:
+        self, measure: skt.Measure, spacing: float | None = None, to_df: bool = False
+    ) -> np.ndarray | pd.DataFrame:
         r"""Compute the contribution of each asset to a given measure.
 
         Parameters
@@ -763,9 +775,15 @@ class Portfolio(BasePortfolio):
             Spacing "h" of the finite difference:
             :math:`contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}`
 
+        to_df : bool, default=False
+            If set to True, a DataFrame with asset names in index is returned,
+            otherwise a numpy array is returned. When a DataFrame is returned, the
+            values are sorted in descending order and assets with zero weights are
+            removed.
+
         Returns
         -------
-        values : ndrray of shape (n_assets,)
+        values : numpy array of shape (n_assets,) or DataFrame
             The measure contribution of each asset.
         """
         if spacing is None:
@@ -778,49 +796,26 @@ class Portfolio(BasePortfolio):
                 spacing = 1e-1
             else:
                 spacing = 1e-5
-        args = {arg: getattr(self, arg) for arg in args_names(self.__init__)}
-
-        def get_risk(i: int, h: float) -> float:
-            a = args.copy()
-            w = a["weights"].copy()
-            w[i] += h
-            a["weights"] = w
-            return getattr(Portfolio(**a), measure.value)
-
-        cont = [
-            (get_risk(i, h=spacing) - get_risk(i, h=-spacing))
-            / (2 * spacing)
-            * self.weights[i]
-            for i in range(len(self.weights))
-        ]
-        return np.array(cont)
-
-    def plot_contribution(self, measure: skt.Measure, spacing: float | None = None):
-        r"""Plot the contribution of each asset to a given measure.
-
-        Parameters
-        ----------
-        measure : Measure
-            The measure used for the contribution computation.
-
-        spacing : float, optional
-            Spacing "h" of the finite difference:
-            :math:`contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}`
+        args = {
+            arg: getattr(self, arg)
+            for arg in args_names(self.__init__)
+            if arg != "weights"
+        }
 
-        Returns
-        -------
-        plot : Figure
-            The plotly Figure of assets contribution to the measure.
-        """
-        cont = self.contribution(measure=measure, spacing=spacing)
-        df = pd.DataFrame(cont, index=self.assets, columns=["contribution"])
-        fig = px.bar(df, x=df.index, y=df.columns)
-        fig.update_layout(
-            title=f"{measure} contribution",
-            xaxis_title="Asset",
-            yaxis_title=f"{measure} contribution",
+        contribution, assets = _compute_contribution(
+            args=args,
+            weights=self.weights,
+            assets=self.assets,
+            measure=measure,
+            h=spacing,
+            drop_zero_weights=to_df,
         )
-        return fig
+
+        if not to_df:
+            return np.array(contribution)
+        df = pd.DataFrame(contribution, index=assets, columns=[self.name])
+        df.sort_values(by=self.name, ascending=False, inplace=True)
+        return df
 
     def summary(self, formatted: bool = True) -> pd.Series:
         """Portfolio summary of all its measures.
@@ -863,3 +858,44 @@ class Portfolio(BasePortfolio):
             return self.weights[np.where(self.assets == asset)[0][0]]
         except IndexError:
             raise IndexError("{asset} is not a valid asset name.") from None
+
+
+def _get_risk(
+    args: dict, weights: np.ndarray, measure: skt.Measure, i: int, h: float
+) -> float:
+    """Get the Portfolio risk measure when the weight of asset `i` is increased by `h`."""
+    assert "weights" not in args
+    weights = weights.copy()
+    weights[i] += h
+    return getattr(Portfolio(weights=weights, **args), measure.value)
+
+
+def _compute_contribution(
+    args: dict,
+    weights: np.ndarray,
+    assets: np.ndarray,
+    measure: skt.Measure,
+    h: float,
+    drop_zero_weights: bool,
+) -> tuple[list[float], list[str]]:
+    """Compute the contribution of each asset to a given measure using finite
+    difference.
+    """
+    contributions = []
+    _assets = []
+    for i, (weight, asset) in enumerate(zip(weights, assets, strict=True)):
+        if weight == 0:
+            if not drop_zero_weights:
+                _assets.append(asset)
+                contributions.append(0)
+        else:
+            _assets.append(asset)
+            contributions.append(
+                (
+                    _get_risk(args, weights, measure, i, h)
+                    - _get_risk(args, weights, measure, i, -h)
+                )
+                / (2 * h)
+                * weight
+            )
+    return contributions, _assets

skfolio/utils/tools.py

@@ -26,6 +26,7 @@ __all__ = [
     "input_to_array",
     "args_names",
     "format_measure",
+    "optimal_rounding_decimals",
     "bisection",
     "safe_split",
     "fit_single_estimator",
@@ -465,10 +466,26 @@ def format_measure(x: float, percent: bool = False) -> str:
     if xn == 0:
         n = 0
     else:
-        n = min(6, max(int(-np.log10(abs(xn))) + 2, 2))
+        n = optimal_rounding_decimals(xn)
     return "{value:{fmt}}".format(value=x, fmt=f".{n}{f}")
 
 
+def optimal_rounding_decimals(x: float) -> int:
+    """Return the optimal rounding decimal number for a user-friendly formatting.
+
+    Parameters
+    ----------
+    x : float
+        Number to round.
+
+    Returns
+    -------
+    n : int
+        Rounding decimal number.
+    """
+    return min(6, max(int(-np.log10(abs(x))) + 2, 2))
+
+
 def bisection(x: list[np.ndarray]) -> Iterator[list[np.ndarray, np.ndarray]]:
     """Generator to bisect a list of array.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: skfolio
-Version: 0.3.0
+Version: 0.4.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>

{skfolio-0.3.0.dist-info → skfolio-0.4.0.dist-info}/RECORD

@@ -4,7 +4,7 @@ skfolio/typing.py,sha256=yEZiCZ6UIyfYUqtfj9Kf2KA9mrjUbmxyzpH9uqVboJs,1378
 skfolio/cluster/__init__.py,sha256=4g-PFB_ld9BhiQ1ZPvvAorpFbRwd_p_DkeRlulDv2Hk,251
 skfolio/cluster/_hierarchical.py,sha256=16INBe5HB7ALODO3RNI8ZjOYALtMZa3U_7EP1aEIxp8,12819
 skfolio/datasets/__init__.py,sha256=TKzb3wucwuaBI7V8GSiEIun-oaV0W0Mhl_XJgMjlajU,481
-skfolio/datasets/_base.py,sha256=-SPN7BA58PiGu4OMIs-bmOMk8qp9aLiRVsBDyI0zsi4,15903
+skfolio/datasets/_base.py,sha256=Al8YzVsiuas3NMMKSjMhE0C0XFkYE-qjONumgoXwFbo,15902
 skfolio/datasets/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 skfolio/datasets/data/factors_dataset.csv.gz,sha256=brCJlT25DJo40yg1gnUXAakNtvWZZYR_1ksFeN5JcWE,36146
 skfolio/datasets/data/sp500_dataset.csv.gz,sha256=7iHKwovvsdCnOanOsiGE-ZU5RyaqDP3pohlB0awErA0,426065
@@ -14,13 +14,13 @@ skfolio/distance/_base.py,sha256=jBgRk6lZrP1woSI9541fTfxBBkp4WCTLlRPmWcmA3j4,132
 skfolio/distance/_distance.py,sha256=yRyyxMXqKYOiuXdq35aQ2MfS8fp6Xh9BR_ABbUVkaGg,19034
 skfolio/measures/__init__.py,sha256=9ThQikIAQcfKRLSCoMr-Z5vE2-ThtYe9B-L40b6Ewg0,1631
 skfolio/measures/_enums.py,sha256=NJcngwg9b2JMMiekwkWU9POfnDvgfUgtYtyV2VSFDVM,8934
-skfolio/measures/_measures.py,sha256=VU9tahJKJvt8PaJZNxWkmFkFU4PsN0FfYO32Je6D53E,16829
+skfolio/measures/_measures.py,sha256=Z7XHSyM9xfecDgOqm-lJQJhvZxasF018-oFS4QjC4g0,16829
 skfolio/metrics/__init__.py,sha256=MomHJ5_bgjq4qUwGS2bfhNmG_ld0oQ4wK6y0Yy_Eonc,75
 skfolio/metrics/_scorer.py,sha256=h1VuZk-zzn4rIChHl9FvM7RxqVT3b-jR1CEB-cr9F2s,4306
 skfolio/model_selection/__init__.py,sha256=8j9Z5tpbgBScjFbn8ZsCm_6rZO7RkPQ1QIF8BqYMVA8,507
 skfolio/model_selection/_combinatorial.py,sha256=cS_W_4uA2aUC0eRbqbRnfezRRxUpm2_HGs1S5ea0q6E,19045
 skfolio/model_selection/_validation.py,sha256=3eFYzPejjDZljc33vRehDuBQTEKCkrj-mZihMVuGA4s,10034
-skfolio/model_selection/_walk_forward.py,sha256=Y3xB7X0zVELBHtn4S_NCDBt5pXLE2xmcdtSJP6bmESk,7529
+skfolio/model_selection/_walk_forward.py,sha256=T57HhdFGjG31mAufujHQuRK1uKfAdkiBx9eucQZ-WG0,15043
 skfolio/moments/__init__.py,sha256=zwxaRO4TLoPj8qrcYSofNyd3tYhbLLcZWQaErzfDdNg,794
 skfolio/moments/covariance/__init__.py,sha256=maWkl5Uh0RMgfaxQ0yO-c5zhJg51vm1zrtxZrk_p0pg,1068
 skfolio/moments/covariance/_base.py,sha256=98o4YDFcOZ4X4hRFlrJAwWifULGzisEyRZaxFYW1qeA,3970
@@ -30,7 +30,7 @@ skfolio/moments/covariance/_empirical_covariance.py,sha256=_7T1x4p-vdATQvQzQjQBM
 skfolio/moments/covariance/_ew_covariance.py,sha256=jzLE4zSEfLCToNBTIG5CMy1n9EYWo1IHJPifcyLVe1g,3673
 skfolio/moments/covariance/_gerber_covariance.py,sha256=3wSwZtji2cEr2rzZ6pi2knmuOSzTFpyb_4XJl_S3Yj0,5856
 skfolio/moments/covariance/_graphical_lasso_cv.py,sha256=_6WQ1sjYJRG8XDq8zb5YIPtDhpb8CmLhLBlfewBvqjM,6539
-skfolio/moments/covariance/_implied_covariance.py,sha256=x0midsEr4RnJ63DMhv0zytoPCFqfGaV0WpxtnOeF75Y,17368
+skfolio/moments/covariance/_implied_covariance.py,sha256=6DiPWo7WVRA8EFvjYxBLBIrYaeRJWpr8yH5I64Sbbd0,17732
 skfolio/moments/covariance/_ledoit_wolf.py,sha256=iV92TpAopOAgQwa4zk7NF1rYdXkgm3uXn5ZZpbcMss0,4875
 skfolio/moments/covariance/_oas.py,sha256=ru8BNz7vQU75ARCuUbtJstmR2fy2fiD9OXLDlztUm5g,3684
 skfolio/moments/covariance/_shrunk_covariance.py,sha256=OOUahkiSdU3vFOb8i0iHtn8WU0AHl7o9pf8pFkG6Lv4,3095
@@ -60,11 +60,11 @@ skfolio/optimization/ensemble/_stacking.py,sha256=ZoICUnc_MwoXDQAR2kewCg-KIezSOI
 skfolio/optimization/naive/__init__.py,sha256=Dkr55R48urC-jfYN007NTbei16N91Na_EDYLVqzhGgQ,147
 skfolio/optimization/naive/_naive.py,sha256=AhEyYKEUAm-Fjn4p8SHwhp7yE9iF0tRyDZIjKYV4EeU,6390
 skfolio/population/__init__.py,sha256=rsPPMUv95aTK7vmpPeQwF8NzFuBwk6RDo5g4HNaPzNM,80
-skfolio/population/_population.py,sha256=MNIqIkBQs-ourGYFbV-PgC0vn9qJNqYCINN3ZogWqMM,29222
+skfolio/population/_population.py,sha256=9NKnz_rQYLnauP1Me6tnDwD7lq3MeGnSyCq-sb0fTV0,30424
 skfolio/portfolio/__init__.py,sha256=YYtcAPmA2zeCxFGTXegg2FXcA7py6CxOX7IMTdYuXl0,586
-skfolio/portfolio/_base.py,sha256=XbvCdlhwP-mgnbVppoZxv8gr_IgCv8csx71LigqZ0-M,38282
-skfolio/portfolio/_multi_period_portfolio.py,sha256=Zt2khkaeVwZjUKvL0NAk5kLJtfO19hup3YxCGdgk5Mk,22719
-skfolio/portfolio/_portfolio.py,sha256=sSDX2HzK2KgatCgQakEhENOLE-3jSfwI_xgbiVrCGUY,31609
+skfolio/portfolio/_base.py,sha256=EFLsvHoxZmDvGPOKePr6hQGXU7y7TWsALvzYP9qt0fQ,39588
+skfolio/portfolio/_multi_period_portfolio.py,sha256=K2JfEwlPD9iGO58lOdk7WUbWuXZDWw2prPT5T7pOdto,24387
+skfolio/portfolio/_portfolio.py,sha256=gqvCKM6ZVfwZrgixiYdahgbQ1DRNW2LkGHkXOpjleb4,32753
 skfolio/pre_selection/__init__.py,sha256=VtUtDn-U-Mn_xR2k7yfld0Yb0rPhLakEAiBwUyi-4Z8,189
 skfolio/pre_selection/_pre_selection.py,sha256=w84T14nKmzkgzbw5CW_AIlci741lXYxKUwB5pBjhTTI,12163
 skfolio/preprocessing/__init__.py,sha256=15A1bzfPsbfxxXgGP1gstf4R0E_347Wn18z5W5jH-hk,94
@@ -83,9 +83,9 @@ skfolio/utils/bootstrap.py,sha256=3zY2kO_GQURKEcQMCasJOSByde9Mt2IAi3KJH0_a4mk,35
 skfolio/utils/equations.py,sha256=w0HsYjA7cS0mHYsI9MpixHLkof3HN26nc14ZfqFrHlE,11047
 skfolio/utils/sorting.py,sha256=lSjMvH2L-sSj-06B3MlwBrH1rtjCeGEe4hG894W7TE0,3504
 skfolio/utils/stats.py,sha256=wuOmSt5panMMTw_pFYizLbmrclsE_4PHQfamkzJ5J2s,13937
-skfolio/utils/tools.py,sha256=ADMk7sXiiM97JqGuhzDqv0V33DIDk2dwX7X9337dYmo,20572
-skfolio-0.3.0.dist-info/LICENSE,sha256=F6Gi-ZJX5BlVzYK8R9NcvAkAsKa7KO29xB1OScbrH6Q,1526
-skfolio-0.3.0.dist-info/METADATA,sha256=ABlRGykFqSR2RLECAvF_uhCCrC98w7Clg2pg8dSeRgk,19617
-skfolio-0.3.0.dist-info/WHEEL,sha256=mguMlWGMX-VHnMpKOjjQidIo1ssRlCFu4a4mBpz1s2M,91
-skfolio-0.3.0.dist-info/top_level.txt,sha256=NXEaoS9Ms7t32gxkb867nV0OKlU0KmssL7IJBVo0fJs,8
-skfolio-0.3.0.dist-info/RECORD,,
+skfolio/utils/tools.py,sha256=4KrmBR9jOLiI6j0hb27gsPC--OHXo4Sp1xl-6i-k9Tg,20925
+skfolio-0.4.0.dist-info/LICENSE,sha256=F6Gi-ZJX5BlVzYK8R9NcvAkAsKa7KO29xB1OScbrH6Q,1526
+skfolio-0.4.0.dist-info/METADATA,sha256=Vh_PqWOdbuuaxurc6k3BL0dZeG7BpKLlis___v8YMv4,19617
+skfolio-0.4.0.dist-info/WHEEL,sha256=5Mi1sN9lKoFv_gxcPtisEVrJZihrm_beibeg5R6xb4I,91
+skfolio-0.4.0.dist-info/top_level.txt,sha256=NXEaoS9Ms7t32gxkb867nV0OKlU0KmssL7IJBVo0fJs,8
+skfolio-0.4.0.dist-info/RECORD,,

{skfolio-0.3.0.dist-info → skfolio-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (70.1.1)
+Generator: setuptools (75.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any