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

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
 

skfolio/uncertainty_set/__init__.py

@@ -1,3 +1,5 @@
+"""Uncertainty Set module."""
+
 from skfolio.uncertainty_set._base import (
     BaseCovarianceUncertaintySet,
     BaseMuUncertaintySet,

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

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.
@@ -41,7 +41,7 @@ __all__ = [
 
 
 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
     ----------

skfolio/utils/tools.py

@@ -1,12 +1,13 @@
-"""Tools module"""
+"""Tools module."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 # Implementation derived from:
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
 # Grisel Licensed under BSD 3 clause.
 
+import warnings
 from collections.abc import Callable, Iterator
 from enum import Enum
 from functools import wraps
@@ -36,19 +37,20 @@ __all__ = [
     "optimal_rounding_decimals",
     "safe_indexing",
     "safe_split",
+    "validate_input_list",
 ]
 
 GenericAlias = type(list[int])
 
 
 class AutoEnum(str, Enum):
-    """Base Enum class used in `skfolio`"""
+    """Base Enum class used in `skfolio`."""
 
     @staticmethod
     def _generate_next_value_(
         name: str, start: int, count: int, last_values: Any
     ) -> str:
-        """Overriding `auto()`"""
+        """Overriding `auto()`."""
         return name.lower()
 
     @classmethod
@@ -68,13 +70,13 @@ class AutoEnum(str, Enum):
         return value in cls._value2member_map_
 
     def __repr__(self) -> str:
-        """Representation of the Enum"""
+        """Representation of the Enum."""
         return self.name
 
 
 # noinspection PyPep8Naming
 class cached_property_slots:
-    """Cached property decorator for slots"""
+    """Cached property decorator for slots."""
 
     def __init__(self, func):
         self.func = func
@@ -83,10 +85,12 @@ class cached_property_slots:
         self.__doc__ = func.__doc__
 
     def __set_name__(self, owner, name):
+        """Set Name."""
         self.public_name = name
         self.private_name = f"_{name}"
 
     def __get__(self, instance, owner=None):
+        """Getter."""
         if instance is None:
             return self
         if self.private_name is None:
@@ -102,6 +106,7 @@ class cached_property_slots:
         return value
 
     def __set__(self, instance, owner=None):
+        """Setter."""
         raise AttributeError(
             f"'{type(instance).__name__}' object attribute '{self.public_name}' is"
             " read-only"
@@ -111,7 +116,7 @@ class cached_property_slots:
 
 
 def _make_key(args, kwds) -> int:
-    """Make a cache key from optionally typed positional and keyword arguments"""
+    """Make a cache key from optionally typed positional and keyword arguments."""
     key = args
     if kwds:
         for item in kwds.items():
@@ -248,7 +253,6 @@ def safe_split(
     y_subset : array-like
         Indexed targets.
     """
-
     X_subset = safe_indexing(X, indices=indices, axis=axis)
     if y is not None:
         y_subset = safe_indexing(y, indices=indices, axis=axis)
@@ -340,10 +344,9 @@ def check_estimator(
 
     Returns
     -------
-    estimator: Estimator
+    estimator : Estimator
         The checked estimator or the default.
     """
-
     if estimator is None:
         return default
     if not isinstance(estimator, check_type):
@@ -439,6 +442,67 @@ def input_to_array(
     return arr
 
 
+def validate_input_list(
+    items: list[int | str],
+    n_assets: int,
+    assets_names: np.ndarray[str] | None,
+    name: str,
+    raise_if_string_missing: bool = True,
+) -> list[int]:
+    """Convert a list of items (asset indices or asset names) into a list of
+    validated asset indices.
+
+    Parameters
+    ----------
+    items : list[int | str]
+       List of asset indices or asset names.
+
+    n_assets : int
+       Expected number of assets.
+       Used for verification.
+
+    assets_names : ndarray, optional
+       Asset names used when `items` contain strings.
+
+    name : str
+       Name of the items used for error messages.
+
+    raise_if_string_missing : bool, default=True
+        If set to True, raises an error if an item string is missing from assets_names;
+        otherwise, issue a User Warning.
+
+    Returns
+    -------
+    values : list[int]
+       Converted and validated list.
+    """
+    if len(set(items)) != len(items):
+        raise ValueError(f"Duplicates found in {items}")
+
+    asset_indices = set(range(n_assets))
+    res = []
+    for asset in items:
+        if isinstance(asset, str):
+            if assets_names is None:
+                raise ValueError(
+                    f"If `{name}` is provided as a list of string, you must input `X` "
+                    f"as a DataFrame with assets names in columns."
+                )
+            mask = assets_names == asset
+            if np.any(mask):
+                res.append(int(np.where(mask)[0][0]))
+            else:
+                if raise_if_string_missing:
+                    raise ValueError(f"{asset} not found in {assets_names}")
+                else:
+                    warnings.warn(f"{asset} not found in {assets_names}", stacklevel=2)
+        else:
+            if asset not in asset_indices:
+                raise ValueError(f"`central_assets` {asset} is not in {asset_indices}.")
+            res.append(int(asset))
+    return res
+
+
 def format_measure(x: float, percent: bool = False) -> str:
     """Format a measure number into a user-friendly string.
 
@@ -514,7 +578,7 @@ def fit_single_estimator(
     indices: np.ndarray | None = None,
     axis: int = 0,
 ):
-    """function used to fit an estimator within a job.
+    """Function used to fit an estimator within a job.
 
     Parameters
     ----------
@@ -622,7 +686,7 @@ def fit_and_predict(
 
 
 def default_asset_names(n_assets: int) -> np.ndarray:
-    """Default asset names are `["x0", "x1", ..., "x(n_assets - 1)"]`
+    """Default asset names are `["x0", "x1", ..., "x(n_assets - 1)"]`.
 
     Parameters
     ----------