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

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
@@ -17,6 +17,7 @@ import sklearn.base as skb
 import sklearn.linear_model as skl
 import sklearn.multioutput as skmo
 import sklearn.utils.metadata_routing as skm
+import sklearn.utils.validation as skv
 
 from skfolio.prior._base import BasePrior, PriorModel
 from skfolio.prior._empirical import EmpiricalPrior
@@ -199,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,
@@ -265,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)
@@ -273,7 +277,7 @@ class FactorModel(BasePrior):
 
         # we validate and convert to numpy after all models have been fitted to keep
         # features names information.
-        X, y = self._validate_data(X, y, multi_output=True)
+        X, y = skv.validate_data(self, X, y, multi_output=True)
         n_assets = X.shape[1]
         n_factors = y.shape[1]
 
@@ -292,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)))

skfolio/prior/_synthetic_data.py

@@ -0,0 +1,239 @@
+"""Synthetic Data Prior Model estimator."""
+
+# Copyright (c) 2025
+# Author: Hugo Delatte <delatte.hugo@gmail.com>
+# SPDX-License-Identifier: BSD-3-Clause
+
+import inspect
+
+import numpy as np
+import numpy.typing as npt
+import sklearn.base as skb
+import sklearn.utils.metadata_routing as skm
+import sklearn.utils.validation as skv
+
+from skfolio.distribution import VineCopula
+from skfolio.prior._base import BasePrior
+from skfolio.prior._empirical import EmpiricalPrior
+from skfolio.utils.tools import check_estimator
+
+
+class SyntheticData(BasePrior):
+    """Synthetic Data Estimator.
+
+    The Synthetic Data model estimates a :class:`~skfolio.prior.PriorModel` by
+    fitting a `distribution_estimator` and sampling new returns data from it.
+
+    The default ``distribution_estimator`` is a Regular Vine Copula model. Other common
+    choices are Generative Adversarial Networks (GANs) or Variational Autoencoders
+    (VAEs).
+
+    This class is particularly useful when the historical distribution tail dependencies
+    are sparse and need extrapolation for tail optimizations or when optimizing under
+    conditional or stressed scenarios.
+
+    Parameters
+    ----------
+    distribution_estimator : BaseEstimator, optional
+        Estimator to model the distribution of asset returns. It must inherit from
+        `BaseEstimator` and implements a `sample` method. If None, the default
+        `VineCopula()` model is used.
+
+    n_samples : int, default=1000
+        Number of samples to generate from the `distribution_estimator`, default is
+        1000.
+
+    sample_args : dict, optional
+        Additional keyword arguments to pass to the `sample` method of the
+        `distribution_estimator`.
+
+    Attributes
+    ----------
+    prior_model_ : PriorModel
+        The assets :class:`~skfolio.prior.PriorModel`.
+
+    distribution_estimator_ : BaseEstimator
+        The fitted distribution estimator.
+
+    n_features_in_ : int
+       Number of assets seen during `fit`.
+
+    feature_names_in_ : ndarray of shape (`n_features_in_`,)
+       Names of features seen during `fit`. Defined only when `X`
+       has feature names that are all strings.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from skfolio.datasets import load_sp500_dataset, load_factors_dataset
+    >>> from skfolio.preprocessing import prices_to_returns
+    >>> from skfolio.distribution import VineCopula
+    >>> from skfolio.optimization import MeanRisk
+    >>> from skfolio.prior import FactorModel, SyntheticData
+    >>> from skfolio import RiskMeasure
+    >>>
+    >>> # Load historical prices and convert them to returns
+    >>> prices = load_sp500_dataset()
+    >>> factors = load_factors_dataset()
+    >>> X, y = prices_to_returns(prices, factors)
+    >>>
+    >>> # Instanciate the SyntheticData model and fit it
+    >>> model = SyntheticData()
+    >>> model.fit(X)
+    >>> print(model.prior_model_)
+    >>>
+    >>> # Minimum CVaR optimization on synthetic returns
+    >>> model = MeanRisk(
+    ...    risk_measure=RiskMeasure.CVAR,
+    ...    prior_estimator=SyntheticData(
+    ...        distribution_estimator=VineCopula(log_transform=True, n_jobs=-1),
+    ...        n_samples=2000,
+    ...    )
+    ... )
+    >>> model.fit(X)
+    >>> print(model.weights_)
+    >>>
+    >>> # Minimum CVaR optimization on Stressed Factors
+    >>> factor_model = FactorModel(
+    ...    factor_prior_estimator=SyntheticData(
+    ...        distribution_estimator=VineCopula(
+    ...            central_assets=["QUAL"],
+    ...            log_transform=True,
+    ...            n_jobs=-1,
+    ...        ),
+    ...        n_samples=5000,
+    ...        sample_args=dict(conditioning={"QUAL": -0.2}),
+    ...    )
+    ... )
+    >>> model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)
+    >>> model.fit(X, y)
+    >>> print(model.weights_)
+    >>>
+    >>> # Stress Test the Portfolio
+    >>> factor_model.set_params(factor_prior_estimator__sample_args=dict(
+    ...     conditioning={"QUAL": -0.5}
+    ... ))
+    >>> factor_model.fit(X,y)
+    >>> stressed_X = factor_model.prior_model_.returns
+    >>> stressed_ptf = model.predict(stressed_X)
+    """
+
+    distribution_estimator_: skb.BaseEstimator
+    prior_estimator_: BasePrior
+    n_features_in_: int
+    feature_names_in_: np.ndarray
+
+    def __init__(
+        self,
+        distribution_estimator: skb.BaseEstimator | None = None,
+        n_samples: int = 1000,
+        sample_args: dict | None = None,
+    ):
+        self.distribution_estimator = distribution_estimator
+        self.n_samples = n_samples
+        self.sample_args = sample_args
+
+    def get_metadata_routing(self):
+        # noinspection PyTypeChecker
+        router = skm.MetadataRouter(owner=self.__class__.__name__).add(
+            distance_estimator=self.distribution_estimator,
+            method_mapping=skm.MethodMapping().add(caller="fit", callee="fit"),
+        )
+        return router
+
+    def fit(self, X: npt.ArrayLike, y=None, **fit_params) -> "SyntheticData":
+        """Fit the Synthetic Data estimator.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_assets)
+            Price returns of the assets.
+
+        y : Ignored
+            Not used, present for API consistency by convention.
+
+        **fit_params : dict
+            Parameters to pass to the underlying estimators.
+            Only available if `enable_metadata_routing=True`, which can be
+            set by using ``sklearn.set_config(enable_metadata_routing=True)``.
+            See :ref:`Metadata Routing User Guide <metadata_routing>` for
+            more details.
+
+        Returns
+        -------
+        self : SyntheticData
+            Fitted estimator.
+        """
+        routed_params = skm.process_routing(self, "fit", **fit_params)
+
+        self.distribution_estimator_ = check_estimator(
+            self.distribution_estimator,
+            default=VineCopula(),
+            check_type=skb.BaseEstimator,
+        )
+        _check_sample_method(self.distribution_estimator_)
+
+        # fitting distribution estimator on prior returns
+        # noinspection PyUnresolvedReferences
+        self.distribution_estimator_.fit(
+            X, y, **routed_params.distribution_estimator.fit
+        )
+
+        # We validate after all models have been fitted to keep feature names
+        # information.
+        skv.validate_data(self, X)
+
+        # sample from the distribution estimator
+        sample_args = self.sample_args if self.sample_args is not None else {}
+        # noinspection PyUnresolvedReferences
+        synthetic_data = self.distribution_estimator_.sample(
+            n_samples=self.n_samples, **sample_args
+        )
+
+        # When performing conditional sampling, the conditioning samples are often
+        # constant. To avoid null variance, we add a small white noise.
+        constant_returns = np.var(synthetic_data, axis=0) < 1e-14
+        if np.any(constant_returns):
+            noise = 1e-6 * np.random.randn(len(synthetic_data), 1)
+            synthetic_data[:, constant_returns] += noise
+
+        # Fit empirical posterior estimator
+        posterior_estimator = EmpiricalPrior()
+        posterior_estimator.fit(synthetic_data)
+        self.prior_model_ = posterior_estimator.prior_model_
+
+        return self
+
+
+def _check_sample_method(distribution_estimator: skb.BaseEstimator) -> None:
+    """Check that the distribution_estimator implements a valid 'sample' method.
+
+    This helper function verifies that the given estimator has a callable 'sample'
+    method and that this method accepts an 'n_samples' parameter.
+
+    Parameters
+    ----------
+    distribution_estimator : BaseEstimator
+        The estimator whose 'sample' method is to be validated.
+
+    Raises
+    ------
+    ValueError
+        If the 'sample' method is missing or does not have an 'n_samples' parameter.
+    """
+    # Get the 'sample' attribute; if it doesn't exist, return False.
+    sample_method = getattr(distribution_estimator, "sample", None)
+    if sample_method is None or not callable(sample_method):
+        raise ValueError(
+            f"The distribution_estimator {distribution_estimator} must implement a "
+            "`sample` method"
+        )
+
+    sig = inspect.signature(sample_method)
+
+    # Check if the parameter 'n_samples' is in the method's parameters.
+    if "n_samples" not in sig.parameters:
+        raise ValueError(
+            "The `sample` method of the distribution_estimator "
+            f"{distribution_estimator} must have `n_samples` as parameter"
+        )

skfolio/synthetic_returns/__init__.py

@@ -0,0 +1 @@
+"""Synthetic Data module."""

skfolio/typing.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 collections.abc import Callable
 
@@ -14,20 +14,20 @@ import plotly.graph_objects as go
 from skfolio.measures import ExtraRiskMeasure, PerfMeasure, RatioMeasure, RiskMeasure
 
 __all__ = [
+    "CvxMeasure",
+    "ExpressionFunction",
+    "Factor",
     "Groups",
     "Inequality",
     "LinearConstraints",
+    "Measure",
     "MultiInput",
-    "Target",
+    "Names",
     "ParametersValues",
-    "Factor",
     "Result",
     "RiskResult",
-    "ExpressionFunction",
-    "Measure",
-    "CvxMeasure",
-    "Names",
     "Tags",
+    "Target",
 ]
 
 Measure = PerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure

skfolio/uncertainty_set/__init__.py

@@ -1,3 +1,5 @@
+"""Uncertainty Set module."""
+
 from skfolio.uncertainty_set._base import (
     BaseCovarianceUncertaintySet,
     BaseMuUncertaintySet,
@@ -13,11 +15,11 @@ from skfolio.uncertainty_set._empirical import (
 )
 
 __all__ = [
-    "UncertaintySet",
-    "BaseMuUncertaintySet",
     "BaseCovarianceUncertaintySet",
-    "EmpiricalMuUncertaintySet",
-    "EmpiricalCovarianceUncertaintySet",
-    "BootstrapMuUncertaintySet",
+    "BaseMuUncertaintySet",
     "BootstrapCovarianceUncertaintySet",
+    "BootstrapMuUncertaintySet",
+    "EmpiricalCovarianceUncertaintySet",
+    "EmpiricalMuUncertaintySet",
+    "UncertaintySet",
 ]

skfolio/uncertainty_set/_base.py

@@ -1,8 +1,8 @@
-"""Base Uncertainty estimator"""
+"""Base Uncertainty 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
@@ -11,6 +11,7 @@ import numpy as np
 import numpy.typing as npt
 import sklearn.base as skb
 import sklearn.utils.metadata_routing as skm
+import sklearn.utils.validation as skv
 
 from skfolio.prior import BasePrior
 
@@ -113,9 +114,9 @@ class BaseCovarianceUncertaintySet(skb.BaseEstimator, ABC):
             Validated price returns of factors or a target benchmark if provided.
         """
         if y is None:
-            X = self._validate_data(X)
+            X = skv.validate_data(self, X)
         else:
-            X, y = self._validate_data(X, y, multi_output=True)
+            X, y = skv.validate_data(self, X, y, multi_output=True)
         return X, y
 
     def get_metadata_routing(self):

skfolio/uncertainty_set/_bootstrap.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.
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier

skfolio/uncertainty_set/_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
 # 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

skfolio/utils/__init__.py

@@ -0,0 +1 @@
+"""Utils module."""

skfolio/utils/bootstrap.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.
 
@@ -71,7 +71,7 @@ def stationary_bootstrap(
     block_size: float | None = None,
     seed: int | None = None,
 ) -> np.ndarray:
-    """Creates `n_bootstrap_samples` samples from a multivariate return series via
+    """Create `n_bootstrap_samples` samples from a multivariate return series via
     stationary bootstrapping.
 
     Parameters

skfolio/utils/equations.py

@@ -1,8 +1,8 @@
-"""Equation module"""
+"""Equation module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import re
 import warnings
@@ -44,7 +44,8 @@ def equations_to_matrix(
     groups : array-like of shape (n_groups, n_assets)
         2D array of assets groups.
 
-        Examples:
+        For example:
+
              groups = np.array(
                 [
                     ["SPX", "SX5E", "NKY", "TLT"],
@@ -66,7 +67,8 @@ def equations_to_matrix(
         The second expression means that the sum of all assets in "group_1" should be
         less or equal to "number" times the sum of all assets in "group_2".
 
-        Examples:
+        For example:
+
              equations = [
                 "Equity <= 3 * Bond",
                 "US >= 1.5",
@@ -143,9 +145,10 @@ def group_cardinalities_to_matrix(
     Parameters
     ----------
     groups : array-like of shape (n_groups, n_assets)
-       2D array of assets groups.
+        2D array of assets groups.
+
+        For example:
 
-       Examples:
              groups = np.array(
                 [
                     ["Equity", "Equity", "Equity", "Bond"],
@@ -154,8 +157,8 @@ def group_cardinalities_to_matrix(
             )
 
     group_cardinalities : dict[str, int]
-       Dictionary of cardinality constraint per group.
-       Examples: {"Equity": 1, "US": 3}
+        Dictionary of cardinality constraint per group.
+        For example: {"Equity": 1, "US": 3}
 
     raise_if_group_missing : bool, default=False
         If this is set to True, an error is raised when a group is not found in the
@@ -302,7 +305,7 @@ def _comparison_operator_sign(operator: str) -> int:
 
 
 def _sub_add_operator_sign(operator: str) -> int:
-    """Convert the operators '+' and '-' into 1 or -1
+    """Convert the operators '+' and '-' into 1 or -1.
 
     Parameters
     ----------
@@ -342,7 +345,7 @@ def _string_to_float(string: str) -> float:
 
 
 def _split_equation_string(string: str) -> list[str]:
-    """Split an equation strings by operators"""
+    """Split an equation strings by operators."""
     comp_pattern = "(?=" + "|".join([".+\\" + e for e in _COMPARISON_OPERATORS]) + ")"
     if not bool(re.match(comp_pattern, string)):
         raise EquationToMatrixError(

skfolio/utils/sorting.py

@@ -1,8 +1,8 @@
-"""Fast non-dominated sorting module"""
+"""Fast non-dominated sorting 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
 

skfolio/utils/stats.py

@@ -1,10 +1,10 @@
-"""Tools module"""
+"""Tools module."""
 
 import warnings
 
 # 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.
 # Statsmodels, Copyright (C) 2006, Jonathan E. Taylor, Licensed under BSD 3 clause.
@@ -23,25 +23,25 @@ from skfolio.utils.tools import AutoEnum
 
 __all__ = [
     "NBinsMethod",
-    "n_bins_freedman",
-    "n_bins_knuth",
-    "is_cholesky_dec",
+    "assert_is_distance",
     "assert_is_square",
     "assert_is_symmetric",
-    "assert_is_distance",
-    "cov_nearest",
-    "cov_to_corr",
-    "corr_to_cov",
     "commutation_matrix",
     "compute_optimal_n_clusters",
+    "corr_to_cov",
+    "cov_nearest",
+    "cov_to_corr",
+    "is_cholesky_dec",
+    "minimize_relative_weight_deviation",
+    "n_bins_freedman",
+    "n_bins_knuth",
     "rand_weights",
     "rand_weights_dirichlet",
-    "minimize_relative_weight_deviation",
 ]
 
 
 class NBinsMethod(AutoEnum):
-    """Enumeration of the Number of Bins Methods
+    """Enumeration of the Number of Bins Methods.
 
     Parameters
     ----------
@@ -82,7 +82,7 @@ def n_bins_freedman(x: np.ndarray) -> int:
     if d == 0:
         return 5
     n_bins = max(1, np.ceil((np.max(x) - np.min(x)) / d))
-    return int(round(n_bins))
+    return round(n_bins)
 
 
 def n_bins_knuth(x: np.ndarray) -> int:
@@ -122,12 +122,12 @@ def n_bins_knuth(x: np.ndarray) -> int:
 
     n_bins_init = n_bins_freedman(x)
     n_bins = sco.fmin(func, n_bins_init, disp=0)[0]
-    return int(round(n_bins))
+    return round(n_bins)
 
 
 def rand_weights_dirichlet(n: int) -> np.array:
     """Produces n random weights that sum to one from a dirichlet distribution
-    (uniform distribution over a simplex)
+    (uniform distribution over a simplex).
 
     Parameters
     ----------
@@ -144,7 +144,7 @@ def rand_weights_dirichlet(n: int) -> np.array:
 
 def rand_weights(n: int, zeros: int = 0) -> np.array:
     """Produces n random weights that sum to one from an uniform distribution
-    (non-uniform distribution over a simplex)
+    (non-uniform distribution over a simplex).
 
     Parameters
     ----------