skfolio 0.9.0__tar.gz → 0.10.0__tar.gz

{skfolio-0.9.0/src/skfolio.egg-info → skfolio-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skfolio
-Version: 0.9.0
+Version: 0.10.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>, Matteo Manzi <matteomanzi09@gmail.com>
@@ -92,7 +92,7 @@ Dynamic: license-file
 
 .. -*- mode: rst -*-
 
-|Licence| |Codecov| |Black| |PythonVersion| |PyPi| |CI/CD| |Downloads| |Ruff| |Contribution| |Website| |JupyterLite|
+|Licence| |Codecov| |Black| |PythonVersion| |PyPi| |CI/CD| |Downloads| |Ruff| |Contribution| |Website| |JupyterLite| |Discord|
 
 .. |Licence| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
    :target: https://github.com/skfolio/skfolio/blob/main/LICENSE
@@ -127,6 +127,9 @@ Dynamic: license-file
 .. |JupyterLite| image:: https://jupyterlite.rtfd.io/en/latest/_static/badge.svg
    :target: https://skfolio.org/lite
 
+.. |Discord| image:: https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white
+   :target: https://discord.gg/Bu7EtNYugS
+
 .. |PythonMinVersion| replace:: 3.10
 .. |NumpyMinVersion| replace:: 1.23.4
 .. |ScipyMinVersion| replace:: 1.8.0
@@ -281,6 +284,8 @@ Available models
     * Black & Litterman
     * Factor Model
     * Synthetic Data (Stress Test, Factor Stress Test)
+    * Entropy Pooling
+    * Opinion Pooling
 
 * Uncertainty Set Estimator:
     * On Expected Returns:
@@ -296,6 +301,7 @@ Available models
     * Drop Highly Correlated Assets
     * Select Non-Expiring Assets
     * Select Complete Assets (handle late inception, delisting, etc.)
+    * Drop Zero Variance
 
 * Cross-Validation and Model Selection:
     * Compatible with all `sklearn` methods (KFold, etc.)
@@ -385,7 +391,14 @@ Imports
     )
     from skfolio.pre_selection import SelectKExtremes
     from skfolio.preprocessing import prices_to_returns
-    from skfolio.prior import BlackLitterman, EmpiricalPrior, FactorModel, SyntheticData
+    from skfolio.prior import (
+        BlackLitterman,
+        EmpiricalPrior,
+        EntropyPooling,
+        FactorModel,
+        OpinionPooling,
+        SyntheticData,
+     )
     from skfolio.uncertainty_set import BootstrapMuUncertaintySet
 
 Load Dataset
@@ -701,8 +714,84 @@ Factor Stress Test
         conditioning={"QUAL": -0.5}
     ))
     factor_model.fit(X,y)
-    stressed_X = factor_model.prior_model_.returns
-    stressed_ptf = model.predict(stressed_X)
+    stressed_dist = factor_model.return_distribution_
+    stressed_ptf = model.predict(stressed_dist)
+
+Entropy Pooling
+---------------
+.. code-block:: python
+
+    entropy_pooling = EntropyPooling(
+        mean_views=[
+            "JPM == -0.002",
+            "PG >= LLY",
+            "BAC >= prior(BAC) * 1.2",
+        ],
+        cvar_views=[
+            "GE == 0.08",
+        ],
+    )
+    entropy_pooling.fit(X)
+    print(entropy_pooling.relative_entropy_)
+    print(entropy_pooling.effective_number_of_scenarios_)
+    print(entropy_pooling.return_distribution_.sample_weight)
+
+CVaR Hierarchical Risk Parity optimization on Entropy Pooling
+-------------------------------------------------------------
+.. code-block:: python
+
+    entropy_pooling = EntropyPooling(cvar_views=["GE == 0.08"])
+    model = HierarchicalRiskParity(
+        risk_measure=RiskMeasure.CVAR,
+        prior_estimator=entropy_pooling
+    )
+    model.fit(X)
+    print(model.weights_)
+
+Stress Test with Entropy Pooling on Factor Synthetic Data
+---------------------------------------------------------
+.. code-block:: python
+
+    # Regular Vine Copula and sampling of 100,000 synthetic factor returns
+    factor_synth = SyntheticData(
+        n_samples=100_000,
+        distribution_estimator=VineCopula(log_transform=True, n_jobs=-1, random_state=0)
+    )
+
+    # Entropy Pooling by imposing a CVaR-95% of 10% on the Quality factor
+    factor_entropy_pooling = EntropyPooling(
+        prior_estimator=factor_synth,
+        cvar_views=["QUAL == 0.10"],
+    )
+
+    factor_entropy_pooling.fit(X, factors)
+
+    # We retrieve the stressed distribution:
+    stressed_dist = factor_model.return_distribution_
+
+    # We stress-test our portfolio:
+    stressed_ptf = model.predict(stressed_dist)
+
+Opinion Pooling
+---------------
+.. code-block:: python
+
+    # We consider two expert opinions, each generated via Entropy Pooling with
+    # user-defined views.
+    # We assign probabilities of 40% to Expert 1, 50% to Expert 2, and by default
+    # the remaining 10% is allocated to the prior distribution:
+    opinion_1 = EntropyPooling(cvar_views=["AMD == 0.10"])
+    opinion_2 = EntropyPooling(
+        mean_views=["AMD >= BAC", "JPM <= prior(JPM) * 0.8"],
+        cvar_views=["GE == 0.12"],
+    )
+
+    opinion_pooling = OpinionPooling(
+        estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
+        opinion_probabilities=[0.4, 0.5],
+    )
+
+    opinion_pooling.fit(X)
 
 
 Recognition

{skfolio-0.9.0 → skfolio-0.10.0}/README.rst

@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-|Licence| |Codecov| |Black| |PythonVersion| |PyPi| |CI/CD| |Downloads| |Ruff| |Contribution| |Website| |JupyterLite|
+|Licence| |Codecov| |Black| |PythonVersion| |PyPi| |CI/CD| |Downloads| |Ruff| |Contribution| |Website| |JupyterLite| |Discord|
 
 .. |Licence| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
    :target: https://github.com/skfolio/skfolio/blob/main/LICENSE
@@ -35,6 +35,9 @@
 .. |JupyterLite| image:: https://jupyterlite.rtfd.io/en/latest/_static/badge.svg
    :target: https://skfolio.org/lite
 
+.. |Discord| image:: https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white
+   :target: https://discord.gg/Bu7EtNYugS
+
 .. |PythonMinVersion| replace:: 3.10
 .. |NumpyMinVersion| replace:: 1.23.4
 .. |ScipyMinVersion| replace:: 1.8.0
@@ -189,6 +192,8 @@ Available models
     * Black & Litterman
     * Factor Model
     * Synthetic Data (Stress Test, Factor Stress Test)
+    * Entropy Pooling
+    * Opinion Pooling
 
 * Uncertainty Set Estimator:
     * On Expected Returns:
@@ -204,6 +209,7 @@ Available models
     * Drop Highly Correlated Assets
     * Select Non-Expiring Assets
     * Select Complete Assets (handle late inception, delisting, etc.)
+    * Drop Zero Variance
 
 * Cross-Validation and Model Selection:
     * Compatible with all `sklearn` methods (KFold, etc.)
@@ -293,7 +299,14 @@ Imports
     )
     from skfolio.pre_selection import SelectKExtremes
     from skfolio.preprocessing import prices_to_returns
-    from skfolio.prior import BlackLitterman, EmpiricalPrior, FactorModel, SyntheticData
+    from skfolio.prior import (
+        BlackLitterman,
+        EmpiricalPrior,
+        EntropyPooling,
+        FactorModel,
+        OpinionPooling,
+        SyntheticData,
+     )
     from skfolio.uncertainty_set import BootstrapMuUncertaintySet
 
 Load Dataset
@@ -609,8 +622,84 @@ Factor Stress Test
         conditioning={"QUAL": -0.5}
     ))
     factor_model.fit(X,y)
-    stressed_X = factor_model.prior_model_.returns
-    stressed_ptf = model.predict(stressed_X)
+    stressed_dist = factor_model.return_distribution_
+    stressed_ptf = model.predict(stressed_dist)
+
+Entropy Pooling
+---------------
+.. code-block:: python
+
+    entropy_pooling = EntropyPooling(
+        mean_views=[
+            "JPM == -0.002",
+            "PG >= LLY",
+            "BAC >= prior(BAC) * 1.2",
+        ],
+        cvar_views=[
+            "GE == 0.08",
+        ],
+    )
+    entropy_pooling.fit(X)
+    print(entropy_pooling.relative_entropy_)
+    print(entropy_pooling.effective_number_of_scenarios_)
+    print(entropy_pooling.return_distribution_.sample_weight)
+
+CVaR Hierarchical Risk Parity optimization on Entropy Pooling
+-------------------------------------------------------------
+.. code-block:: python
+
+    entropy_pooling = EntropyPooling(cvar_views=["GE == 0.08"])
+    model = HierarchicalRiskParity(
+        risk_measure=RiskMeasure.CVAR,
+        prior_estimator=entropy_pooling
+    )
+    model.fit(X)
+    print(model.weights_)
+
+Stress Test with Entropy Pooling on Factor Synthetic Data
+---------------------------------------------------------
+.. code-block:: python
+
+    # Regular Vine Copula and sampling of 100,000 synthetic factor returns
+    factor_synth = SyntheticData(
+        n_samples=100_000,
+        distribution_estimator=VineCopula(log_transform=True, n_jobs=-1, random_state=0)
+    )
+
+    # Entropy Pooling by imposing a CVaR-95% of 10% on the Quality factor
+    factor_entropy_pooling = EntropyPooling(
+        prior_estimator=factor_synth,
+        cvar_views=["QUAL == 0.10"],
+    )
+
+    factor_entropy_pooling.fit(X, factors)
+
+    # We retrieve the stressed distribution:
+    stressed_dist = factor_model.return_distribution_
+
+    # We stress-test our portfolio:
+    stressed_ptf = model.predict(stressed_dist)
+
+Opinion Pooling
+---------------
+.. code-block:: python
+
+    # We consider two expert opinions, each generated via Entropy Pooling with
+    # user-defined views.
+    # We assign probabilities of 40% to Expert 1, 50% to Expert 2, and by default
+    # the remaining 10% is allocated to the prior distribution:
+    opinion_1 = EntropyPooling(cvar_views=["AMD == 0.10"])
+    opinion_2 = EntropyPooling(
+        mean_views=["AMD >= BAC", "JPM <= prior(JPM) * 0.8"],
+        cvar_views=["GE == 0.12"],
+    )
+
+    opinion_pooling = OpinionPooling(
+        estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
+        opinion_probabilities=[0.4, 0.5],
+    )
+
+    opinion_pooling.fit(X)
 
 
 Recognition

{skfolio-0.9.0 → skfolio-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skfolio"
-version = "0.9.0"
+version = "0.10.0"
 maintainers = [
     { name = "Hugo Delatte", email = "delatte.hugo@gmail.com" },
     { name = "Matteo Manzi", email = "matteomanzi09@gmail.com" }

{skfolio-0.9.0 → skfolio-0.10.0}/src/skfolio/distribution/multivariate/_vine_copula.py

@@ -34,7 +34,6 @@ import numpy as np
 import numpy.typing as npt
 import plotly.express as px
 import plotly.graph_objects as go
-import scipy.stats as st
 import sklearn.utils as sku
 import sklearn.utils.parallel as skp
 import sklearn.utils.validation as skv
@@ -65,6 +64,7 @@ from skfolio.distribution.univariate import (
     StudentT,
     select_univariate_dist,
 )
+from skfolio.utils.figure import kde_trace
 from skfolio.utils.tools import input_to_array, validate_input_list
 
 _UNIFORM_SAMPLE_EPSILON = 1e-14
@@ -996,6 +996,7 @@ class VineCopula(BaseMultivariateDist):
         | None = None,
         subset: list[int | str] | None = None,
         n_samples: int = 500,
+        percentile_cutoff: float | None = None,
         title: str = "Vine Copula Marginal Distributions",
     ) -> go.Figure:
         """
@@ -1025,7 +1026,7 @@ class VineCopula(BaseMultivariateDist):
                If an array-like of length `n_samples` is provided, each sample is
                conditioned on the corresponding value in the array for that asset.
 
-            **Important:** When using conditional sampling, it is recommended that the
+            When using conditional sampling, it is recommended that the
             assets you condition on are set as central during the vine copula
             construction. This can be specified via the `central_assets` parameter in
             the vine copula instantiation.
@@ -1041,6 +1042,12 @@ class VineCopula(BaseMultivariateDist):
             rows than `n_samples`, the value is adjusted to match the number of rows in
             `X` to ensure balanced visualization.
 
+        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).
+
         title : str, default="Vine Copula Marginal Distributions"
             The title for the plot.
 
@@ -1051,7 +1058,6 @@ class VineCopula(BaseMultivariateDist):
         """
         n_assets = self.n_features_in_
         subset = subset or list(range(n_assets))
-        colors = px.colors.qualitative.Plotly
         if X is not None:
             X = np.asarray(X)
             if X.ndim != 2:
@@ -1070,30 +1076,43 @@ class VineCopula(BaseMultivariateDist):
                 n_samples = X.shape[0]
 
         samples = self.sample(n_samples=n_samples, conditioning=conditioning)
+        colors = px.colors.qualitative.Plotly
 
-        traces = []
+        traces: list[go.Scatter] = []
         for i, s in enumerate(subset):
+            visible = True if i == 0 else "legendonly"
+            color = colors[i % len(colors)]
+            asset = self.feature_names_in_[s]
+
             traces.append(
-                _kde_trace(
+                kde_trace(
                     x=samples[:, s],
-                    opacity=1.0,
-                    color=colors[i % len(colors)],
-                    name=f"{self.feature_names_in_[s]} Generated",
-                    visible=True if i == 0 else "legendonly",
+                    sample_weight=None,
+                    percentile_cutoff=percentile_cutoff,
+                    name=f"{asset} Generated",
+                    line_color=color,
+                    fill_opacity=0.17,
+                    line_dash="solid",
+                    line_width=1,
+                    visible=visible,
                 )
             )
 
-        if X is not None:
-            for i, s in enumerate(subset):
+            if X is not None:
                 traces.append(
-                    _kde_trace(
+                    kde_trace(
                         x=X[:, s],
-                        opacity=0.6,
-                        color=colors[i % len(colors)],
-                        name=f"{self.feature_names_in_[s]} Empirical",
-                        visible=True if i == 0 else "legendonly",
+                        sample_weight=None,
+                        percentile_cutoff=percentile_cutoff,
+                        name=f"{asset} Empirical",
+                        line_color=color,
+                        fill_opacity=0.17,
+                        line_dash="dash",
+                        line_width=1.5,
+                        visible=visible,
                     )
                 )
+
         fig = go.Figure(data=traces)
         fig.update_layout(
             title=title,
@@ -1234,21 +1253,3 @@ def _inverse_partial_derivative(
     if is_count:
         return np.array([np.nan])
     return edge.copula.inverse_partial_derivative(X)
-
-
-def _kde_trace(
-    x: np.ndarray, opacity: float, color: str, name: str, visible: bool
-) -> go.Scatter:
-    """Gaussian KDE line plot."""
-    kde = st.gaussian_kde(x)
-    x = np.linspace(min(x), max(x), 500)
-    return go.Scatter(
-        x=x,
-        y=kde(x),
-        mode="lines",
-        name=name,
-        line=dict(color=color),
-        fill="tozeroy",
-        opacity=opacity,
-        visible=visible,
-    )

{skfolio-0.9.0 → skfolio-0.10.0}/src/skfolio/distribution/univariate/_base.py

@@ -202,6 +202,23 @@ class BaseUnivariateDist(BaseDistribution, ABC):
         x = np.linspace(lower_bound, upper_bound, 1000)
 
         traces = []
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=UserWarning)
+            pdfs = np.exp(self.score_samples(x.reshape(-1, 1)))
+        traces.append(
+            go.Scatter(
+                x=x,
+                y=pdfs.flatten(),
+                mode="lines",
+                name=self.__class__.__name__,
+                line=dict(color="rgb(31, 119, 180)", dash="solid", width=1),
+                fill="tozeroy",
+                fillcolor="rgba(31, 119, 180, 0.17)",
+                opacity=1.0,
+            )
+        )
+
         if X is not None:
             with warnings.catch_warnings():
                 warnings.filterwarnings(
@@ -216,25 +233,13 @@ class BaseUnivariateDist(BaseDistribution, ABC):
                     y=y_kde,
                     mode="lines",
                     name="Empirical KDE",
-                    line=dict(color="rgb(85,168,104)"),
+                    line=dict(color="rgb(85, 168, 104)", dash="dash", width=2),
                     fill="tozeroy",
+                    fillcolor="rgba(85, 168, 104, 0.17)",
+                    opacity=1.0,
                 )
             )
 
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore", category=UserWarning)
-            pdfs = np.exp(self.score_samples(x.reshape(-1, 1)))
-        traces.append(
-            go.Scatter(
-                x=x,
-                y=pdfs.flatten(),
-                mode="lines",
-                name=self.__class__.__name__,
-                line=dict(color="rgb(31, 119, 180)"),
-                fill="tozeroy",
-            )
-        )
-
         fig = go.Figure(data=traces)
         fig.update_layout(
             title=title,

{skfolio-0.9.0 → skfolio-0.10.0}/src/skfolio/exceptions.py

@@ -13,6 +13,7 @@ __all__ = [
     "GroupNotFoundError",
     "NonPositiveVarianceError",
     "OptimizationError",
+    "SolverError",
 ]
 
 
@@ -20,6 +21,10 @@ class OptimizationError(Exception):
     """Optimization Did not converge."""
 
 
+class SolverError(Exception):
+    """Solver error."""
+
+
 class EquationToMatrixError(Exception):
     """Error while processing equations."""
 

{skfolio-0.9.0 → skfolio-0.10.0}/src/skfolio/measures/__init__.py

@@ -13,6 +13,7 @@ from skfolio.measures._enums import (
 from skfolio.measures._measures import (
     average_drawdown,
     cdar,
+    correlation,
     cvar,
     drawdown_at_risk,
     edar,
@@ -49,6 +50,7 @@ __all__ = [
     "RiskMeasure",
     "average_drawdown",
     "cdar",
+    "correlation",
     "cvar",
     "drawdown_at_risk",
     "edar",