skfolio 0.9.1__py3-none-any.whl → 0.10.0__py3-none-any.whl

skfolio/portfolio/_base.py

@@ -39,6 +39,7 @@
 
 import warnings
 from abc import abstractmethod
+from collections.abc import Callable
 from typing import ClassVar
 
 import numpy as np
@@ -113,6 +114,10 @@ class BasePortfolio:
         If this is set to True, cumulative returns are compounded.
         The default is `False`.
 
+    sample_weight : ndarray of shape (n_observations,), optional
+        Sample weights for each observation. The weights must sum to one.
+         If None, equal weights are assumed.
+
     min_acceptable_return : float, optional
         The minimum acceptable return used to distinguish "downside" and "upside"
         returns for the computation of lower partial moments:
@@ -376,6 +381,7 @@ class BasePortfolio:
         "min_acceptable_return",
         "compounded",
         "risk_free_rate",
+        "sample_weight",
     }
 
     # Arguments locally used in measures computation
@@ -403,6 +409,7 @@ class BasePortfolio:
         # custom getter and setter
         "_fitness_measures",
         "_annualized_factor",
+        "_sample_weight",
         # custom getter (read-only and cached)
         "_fitness",
         "_cumulative_returns",
@@ -485,6 +492,7 @@ class BasePortfolio:
         fitness_measures: list[skt.Measure] | None = None,
         risk_free_rate: float = 0.0,
         compounded: bool = False,
+        sample_weight: np.ndarray | None = None,
         min_acceptable_return: float | None = None,
         value_at_risk_beta: float = 0.95,
         entropic_risk_measure_theta: float = 1.0,
@@ -497,6 +505,7 @@ class BasePortfolio:
     ):
         self._loaded = False
         self._annualized_factor = annualized_factor
+        self._sample_weight = sample_weight
         self.returns = np.asarray(returns)
         self.observations = np.asarray(observations)
         self.risk_free_rate = risk_free_rate
@@ -652,6 +661,25 @@ class BasePortfolio:
         self._annualized_factor = value
         self.clear()
 
+    @property
+    def sample_weight(self) -> float:
+        """Observations sample weights."""
+        return self._sample_weight
+
+    @sample_weight.setter
+    def sample_weight(self, value: np.ndarray | None) -> None:
+        if value is not None:
+            value = np.asarray(value)
+            if value.ndim != 1:
+                raise ValueError("sample_weight must be a 1D array.")
+            if len(value) != self.n_observations:
+                raise ValueError(
+                    "sample_weight must have the same length as the number of observations."
+                )
+            if not np.isclose(value.sum(), 1):
+                raise ValueError("sample_weight must sum to one.")
+        self._sample_weight = value
+
     # Custom attribute getter (read-only and cached)
     @cached_property_slots
     def fitness(self) -> np.ndarray:
@@ -738,19 +766,9 @@ class BasePortfolio:
             # Local measures function arguments need to be defined in the class
             # attributes with the argument name preceded by the measure name and
             # separated by "_".
-            if measure.is_annualized:
-                func = getattr(mt, str(measure.non_annualized_measure.value))
-            else:
-                func = getattr(mt, str(measure.value))
 
-            args = {
-                arg: (
-                    getattr(self, arg)
-                    if arg in self._measure_global_args
-                    else getattr(self, f"{measure.value}_{arg}")
-                )
-                for arg in args_names(func)
-            }
+            func, args = self._get_measure_func(measure=measure)
+
             try:
                 value = func(**args)
                 if measure in [
@@ -844,15 +862,7 @@ class BasePortfolio:
             risk_measure = non_annualized_measure
 
         if risk_measure is not None:
-            risk_func = getattr(mt, str(risk_measure.value))
-            risk_func_args = {
-                arg: (
-                    getattr(self, arg)
-                    if arg in self._measure_global_args
-                    else getattr(self, f"{risk_measure.value}_{arg}")
-                )
-                for arg in args_names(risk_func)
-            }
+            risk_func, risk_func_args = self._get_measure_func(measure=risk_measure)
 
             if "drawdowns" in risk_func_args:
                 del risk_func_args["drawdowns"]
@@ -1032,18 +1042,33 @@ class BasePortfolio:
         )
         return fig
 
-    def plot_returns_distribution(self) -> go.Figure:
+    def plot_returns_distribution(
+        self, percentile_cutoff: float | None = None
+    ) -> go.Figure:
         """Plot the Portfolio returns distribution using Gaussian KDE.
 
+        Parameters
+        ----------
+        percentile_cutoff : float, default=None
+            Percentile cutoff for tail truncation (percentile), in percent.
+            If a float p is provided, the distribution support is truncated at the p-th
+            and (100 - p)-th percentiles.
+            If None, no truncation is applied (uses full min/max of returns).
+
         Returns
         -------
         plot : Figure
             Returns the plot Figure object
         """
-        lower = np.percentile(self.returns, 1e-1)
-        upper = np.percentile(self.returns, 100 - 1e-1)
+        returns = self.returns
+        if percentile_cutoff is None:
+            lower, upper = returns.min(), returns.max()
+        else:
+            lower = np.percentile(returns, percentile_cutoff)
+            upper = np.percentile(returns, 100.0 - percentile_cutoff)
+
         x = np.linspace(lower, upper, 500)
-        y = st.gaussian_kde(self.returns)(x)
+        y = st.gaussian_kde(self.returns, weights=self.sample_weight)(x)
 
         fig = go.Figure(
             go.Scatter(
@@ -1090,7 +1115,7 @@ class BasePortfolio:
         fig = rolling.plot(backend="plotly")
         fig.add_hline(
             y=getattr(self, measure.value),
-            line_width=1,
+            line_width=1.5,
             line_dash="dash",
             line_color="blue",
         )
@@ -1163,3 +1188,20 @@ class BasePortfolio:
             legend_title_text="Assets",
         )
         return fig
+
+    def _get_measure_func(self, measure: skt.Measure) -> tuple[Callable, dict]:
+        """Return the function and arguments of a given measure."""
+        if measure.is_annualized:
+            func = getattr(mt, str(measure.non_annualized_measure.value))
+        else:
+            func = getattr(mt, str(measure.value))
+
+        args = {}
+        for arg in args_names(func):
+            if arg in self._measure_global_args:
+                args[arg] = getattr(self, arg)
+            elif arg == "biased":
+                args[arg] = False
+            else:
+                args[arg] = getattr(self, f"{measure.value}_{arg}")
+        return func, args

skfolio/portfolio/_multi_period_portfolio.py

@@ -63,6 +63,9 @@ class MultiPeriodPortfolio(BasePortfolio):
         If this is set to True, cumulative returns are compounded.
         The default is `False`.
 
+    sample_weight : ndarray of shape (n_observations,), optional
+        Sample weights for each observation. If None, equal weights are assumed.
+
     min_acceptable_return : float, optional
         The minimum acceptable return used to distinguish "downside" and "upside"
         returns for the computation of lower partial moments:
@@ -334,6 +337,7 @@ class MultiPeriodPortfolio(BasePortfolio):
         annualized_factor: float = 252.0,
         fitness_measures: list[skt.Measure] | None = None,
         compounded: bool = False,
+        sample_weight: np.ndarray | None = None,
         min_acceptable_return: float | None = None,
         value_at_risk_beta: float = 0.95,
         entropic_risk_measure_theta: float = 1,
@@ -354,6 +358,7 @@ class MultiPeriodPortfolio(BasePortfolio):
             annualized_factor=annualized_factor,
             fitness_measures=fitness_measures,
             compounded=compounded,
+            sample_weight=sample_weight,
             min_acceptable_return=min_acceptable_return,
             value_at_risk_beta=value_at_risk_beta,
             cvar_beta=cvar_beta,

skfolio/portfolio/_portfolio.py

@@ -147,6 +147,9 @@ class Portfolio(BasePortfolio):
         If this is set to True, cumulative returns are compounded.
         The default is `False`.
 
+    sample_weight : ndarray of shape (n_observations,), optional
+        Sample weights for each observation. If None, equal weights are assumed.
+
     min_acceptable_return : float, optional
         The minimum acceptable return used to distinguish "downside" and "upside"
         returns for the computation of lower partial moments:
@@ -442,6 +445,7 @@ class Portfolio(BasePortfolio):
         annualized_factor: float = 252,
         fitness_measures: list[skt.Measure] | None = None,
         compounded: bool = False,
+        sample_weight: np.ndarray | None = None,
         min_acceptable_return: float | None = None,
         value_at_risk_beta: float = 0.95,
         entropic_risk_measure_theta: float = 1,
@@ -541,6 +545,7 @@ class Portfolio(BasePortfolio):
             tag=tag,
             fitness_measures=fitness_measures,
             compounded=compounded,
+            sample_weight=sample_weight,
             risk_free_rate=risk_free_rate,
             annualized_factor=annualized_factor,
             min_acceptable_return=min_acceptable_return,

skfolio/prior/__init__.py

@@ -1,13 +1,15 @@
 """Prior module."""
 
-from skfolio.prior._base import BasePrior, PriorModel
+from skfolio.prior._base import BasePrior, ReturnDistribution
 from skfolio.prior._black_litterman import BlackLitterman
 from skfolio.prior._empirical import EmpiricalPrior
+from skfolio.prior._entropy_pooling import EntropyPooling
 from skfolio.prior._factor_model import (
     BaseLoadingMatrix,
     FactorModel,
     LoadingMatrixRegression,
 )
+from skfolio.prior._opinion_pooling import OpinionPooling
 from skfolio.prior._synthetic_data import SyntheticData
 
 __all__ = [
@@ -15,8 +17,10 @@ __all__ = [
     "BasePrior",
     "BlackLitterman",
     "EmpiricalPrior",
+    "EntropyPooling",
     "FactorModel",
     "LoadingMatrixRegression",
-    "PriorModel",
+    "OpinionPooling",
+    "ReturnDistribution",
     "SyntheticData",
 ]

skfolio/prior/_base.py

@@ -15,8 +15,8 @@ import sklearn.base as skb
 # frozen=True with eq=False will lead to an id-based hashing which is needed for
 # caching CVX models in Optimization without impacting performance
 @dataclass(frozen=True, eq=False)
-class PriorModel:
-    """Prior model dataclass.
+class ReturnDistribution:
+    """Return Distribution dataclass used by the optimization estimators.
 
     Attributes
     ----------
@@ -36,12 +36,16 @@ class PriorModel:
         (for example in Factor Models). When provided, this cholesky factor is use in
         some optimizations (for example in mean-variance) to improve performance and
         convergence. The default is `None`.
+
+    sample_weight : ndarray of shape (n_observations,), optional
+        Sample weights for each observation. If None, equal weights are assumed.
     """
 
     mu: np.ndarray
     covariance: np.ndarray
     returns: np.ndarray
     cholesky: np.ndarray | None = None
+    sample_weight: np.ndarray | None = None
 
 
 class BasePrior(skb.BaseEstimator, ABC):
@@ -54,7 +58,7 @@ class BasePrior(skb.BaseEstimator, ABC):
     arguments (no ``*args`` or ``**kwargs``).
     """
 
-    prior_model_: PriorModel
+    return_distribution_: ReturnDistribution
 
     @abstractmethod
     def __init__(self):

skfolio/prior/_black_litterman.py

@@ -1,4 +1,4 @@
-"""Black & Litterman Prior Model estimator."""
+"""Black & Litterman estimator."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
@@ -13,14 +13,14 @@ 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
+from skfolio.prior._base import BasePrior, ReturnDistribution
 from skfolio.prior._empirical import EmpiricalPrior
 from skfolio.utils.equations import equations_to_matrix
 from skfolio.utils.tools import check_estimator, input_to_array
 
 
 class BlackLitterman(BasePrior):
-    """Black & Litterman Prior Model estimator.
+    """Black & Litterman estimator.
 
     The Black & Litterman model [1]_ takes a Bayesian approach by using a prior estimate
     of the assets expected returns and covariance matrix, which are updated using the
@@ -59,9 +59,9 @@ class BlackLitterman(BasePrior):
             * groups = [["Equity", "Equity", "Bond"], ["Europe", "US", "US"]]
 
     prior_estimator : BasePrior, optional
-        The assets' :ref:`prior model estimator <prior>`. It is used to estimate
-        the :class:`~skfolio.prior.PriorModel` containing the estimation of the assets
-        expected returns, covariance matrix, returns and Cholesky decomposition.
+        The assets' :ref:`prior estimator <prior>`. It is used to estimate
+        the :class:`~skfolio.prior.ReturnDistribution` containing the estimation of the
+        assets expected returns, covariance matrix, returns and Cholesky decomposition.
         The default (`None`) is to use `EmpiricalPrior(mu_estimator=EquilibriumMu())`.
 
     tau : float, default=0.05
@@ -81,8 +81,10 @@ class BlackLitterman(BasePrior):
 
     Attributes
     ----------
-    prior_model_ : PriorModel
-        The :class:`~skfolio.prior.PriorModel`.
+    return_distribution_ : ReturnDistribution
+        Fitted :class:`~skfolio.prior.ReturnDistribution` to be used by the optimization
+        estimators, containing the asset returns distribution and posterior Black &
+        Litterman moments estimation.
 
     groups_ : ndarray of shape(n_groups, n_assets)
         Assets names and groups converted to an 2D array.
@@ -179,9 +181,9 @@ class BlackLitterman(BasePrior):
         # fitting prior estimator
         self.prior_estimator_.fit(X, y, **routed_params.prior_estimator.fit)
 
-        prior_mu = self.prior_estimator_.prior_model_.mu
-        prior_covariance = self.prior_estimator_.prior_model_.covariance
-        prior_returns = self.prior_estimator_.prior_model_.returns
+        prior_mu = self.prior_estimator_.return_distribution_.mu
+        prior_covariance = self.prior_estimator_.return_distribution_.covariance
+        prior_returns = self.prior_estimator_.return_distribution_.returns
 
         # we validate after all models have been fitted to keep features names
         # information.
@@ -260,7 +262,7 @@ class BlackLitterman(BasePrior):
             + self.tau * prior_covariance
             - _v @ np.linalg.solve(_a, _v.T)
         )
-        self.prior_model_ = PriorModel(
+        self.return_distribution_ = ReturnDistribution(
             mu=posterior_mu, covariance=posterior_covariance, returns=prior_returns
         )
         return self

skfolio/prior/_empirical.py

@@ -1,4 +1,4 @@
-"""Empirical Prior Model estimator."""
+"""Empirical Prior estimator."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
@@ -10,15 +10,15 @@ 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
+from skfolio.prior._base import BasePrior, ReturnDistribution
 from skfolio.utils.tools import check_estimator
 
 
 class EmpiricalPrior(BasePrior):
     """Empirical Prior estimator.
 
-    The Empirical Prior estimates the :class:`~skfolio.prior.PriorModel` by fitting a
-    `mu_estimator` and a `covariance_estimator` separately.
+    The Empirical Prior estimates the :class:`~skfolio.prior.ReturnDistribution` by
+    fitting a `mu_estimator` and a `covariance_estimator` separately.
 
     Parameters
     ----------
@@ -50,8 +50,9 @@ class EmpiricalPrior(BasePrior):
 
     Attributes
     ----------
-    prior_model_ : PriorModel
-        The assets :class:`~skfolio.prior.PriorModel`.
+    return_distribution_ : ReturnDistribution
+        Fitted :class:`~skfolio.prior.ReturnDistribution` to be used by the optimization
+        estimators, containing the asset returns distribution and moments estimation.
 
     mu_estimator_ : BaseMu
         Fitted `mu_estimator`.
@@ -194,7 +195,7 @@ class EmpiricalPrior(BasePrior):
         # we validate and convert to numpy after all models have been fitted to keep
         # features names information.
         X = skv.validate_data(self, X)
-        self.prior_model_ = PriorModel(
+        self.return_distribution_ = ReturnDistribution(
             mu=mu,
             covariance=covariance,
             returns=X,