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

skfolio/distribution/univariate/_normal_inverse_gaussian.py

@@ -0,0 +1,153 @@
+"""Normal Inverse Gaussian Estimator."""
+
+# Copyright (c) 2025
+# Authors: The skfolio developers
+# Credits: Matteo Manzi, Vincent Maladière, Carlo Nicolini
+# SPDX-License-Identifier: BSD-3-Clause
+
+import numpy.typing as npt
+import scipy.stats as st
+
+from skfolio.distribution.univariate._base import BaseUnivariateDist
+
+
+class NormalInverseGaussian(BaseUnivariateDist):
+    r"""Normal Inverse Gaussian Distribution Estimation.
+
+    This estimator fits a univariate Normal Inverse Gaussian (NIG) distribution
+    to the input data.
+
+    The probability density function is:
+
+    .. math::
+
+        f(x, a, b) = \frac{a \, K_1(a \sqrt{1 + x^2})}{\pi \sqrt{1 + x^2}} \,
+                     \exp(\sqrt{a^2 - b^2} + b x)
+
+    where :math:`x` is a real number, the parameter :math:`a` is the tail
+    heaviness and :math:`b` is the asymmetry parameter satisfying :math:`a > 0`
+    and :math:`|b| <= a`. :math:`K_1` is the modified Bessel function of second kind
+    (`scipy.special.k1`).
+
+    The probability density above is defined in the "standardized" form. To shift
+    and/or scale the distribution use the loc and scale parameters. Specifically,
+    `pdf(x, a, b, loc, scale)` is equivalent to `pdf(y, a, b) / scale` with
+    `y = (x - loc) / scale`.
+
+    For more information, you can refer to the `scipy documentation <https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.norminvgauss.html#scipy.stats.norminvgauss>`_
+
+    Parameters
+    ----------
+    loc : float, optional
+        If provided, the location parameter is fixed to this value during fitting.
+        Otherwise, it is estimated from the data.
+
+    scale : float, optional
+        If provided, the scale parameter is fixed to this value during fitting.
+        Otherwise, it is estimated from the data.
+
+    random_state : int, RandomState instance or None, default=None
+        Seed or random state to ensure reproducibility.
+
+    Attributes
+    ----------
+    a_ : float
+        The fitted shape parameter a of the NIG distribution.
+
+    b_ : float
+        The fitted shape parameter b of the NIG distribution.
+
+    loc_ : float
+        The fitted location parameter.
+
+    scale_ : float
+        The fitted scale parameter.
+
+    Examples
+    --------
+    >>> from skfolio.datasets import load_sp500_index
+    >>> from skfolio.preprocessing import prices_to_returns
+    >>> from skfolio.distribution.univariate import NormalInverseGaussian
+    >>>
+    >>> # Load historical prices and convert them to returns
+    >>> prices = load_sp500_index()
+    >>> X = prices_to_returns(prices)
+    >>>
+    >>> # Initialize the estimator.
+    >>> model = NormalInverseGaussian()
+    >>>
+    >>> # Fit the model to the data.
+    >>> model.fit(X)
+    >>>
+    >>> # Display the fitted parameters.
+    >>> print(model.fitted_repr)
+    NormalInverseGaussian(0.422, -0.0321, 0.000913, 0.00739)
+    >>>
+    >>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
+    >>> log_likelihood = model.score_samples(X)
+    >>> score = model.score(X)
+    >>> cdf = model.cdf(X)
+    >>> ppf = model.ppf(X)
+    >>> aic = model.aic(X)
+    >>> bic = model.bic(X)
+    >>>
+    >>> # Generate 5 new samples from the fitted distribution.
+    >>> samples = model.sample(n_samples=5)
+    >>>
+    >>> # Plot the estimated probability density function (PDF).
+    >>> fig = model.plot_pdf()
+    >>> fig.show()
+    """
+
+    a_: float
+    b_: float
+    loc_: float
+    scale_: float
+    _scipy_model = st.norminvgauss
+
+    def __init__(
+        self,
+        loc: float | None = None,
+        scale: float | None = None,
+        random_state: int | None = None,
+    ):
+        super().__init__(random_state=random_state)
+        self.loc = loc
+        self.scale = scale
+
+    @property
+    def _scipy_params(self) -> dict[str, float]:
+        """Dictionary of parameters to pass to the underlying SciPy distribution."""
+        return {"a": self.a_, "b": self.b_, "loc": self.loc_, "scale": self.scale_}
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "NormalInverseGaussian":
+        """Fit the univariate Normal Inverse Gaussian distribution model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, 1)
+            The input data. X must contain a single column.
+
+        y : None
+            Ignored. Provided for compatibility with scikit-learn's API.
+
+        Returns
+        -------
+        self : NormalInverseGaussian
+            Returns the instance itself.
+        """
+        X = self._validate_X(X, reset=True)
+
+        if self.loc is not None and self.scale is not None:
+            raise ValueError("Either loc or scale must be None to be fitted")
+
+        fixed_params = {}
+        if self.loc is not None:
+            fixed_params["floc"] = self.loc
+        if self.scale is not None:
+            fixed_params["fscale"] = self.scale
+
+        self.a_, self.b_, self.loc_, self.scale_ = self._scipy_model.fit(
+            X, **fixed_params
+        )
+        return self

skfolio/distribution/univariate/_selection.py

@@ -0,0 +1,85 @@
+"""Univariate Distribution Selection."""
+
+# Copyright (c) 2025
+# Authors: The skfolio developers
+# Credits: Matteo Manzi, Vincent Maladière, Carlo Nicolini
+# SPDX-License-Identifier: BSD-3-Clause
+
+import numpy as np
+import numpy.typing as npt
+import sklearn as sk
+
+from skfolio.distribution._base import SelectionCriterion
+from skfolio.distribution.univariate._base import BaseUnivariateDist
+from skfolio.distribution.univariate._gaussian import Gaussian
+from skfolio.distribution.univariate._johnson_su import JohnsonSU
+from skfolio.distribution.univariate._student_t import StudentT
+
+
+def select_univariate_dist(
+    X: npt.ArrayLike,
+    distribution_candidates: list[BaseUnivariateDist] | None = None,
+    selection_criterion: SelectionCriterion = SelectionCriterion.AIC,
+) -> BaseUnivariateDist:
+    """Select the optimal univariate distribution estimator based on an information
+    criterion.
+
+    For each candidate distribution, the function fits the distribution to X and then
+    computes either the Akaike Information Criterion (AIC) or the Bayesian Information
+    Criterion (BIC). The candidate with the lowest criterion value is returned.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_observations, 1)
+        The input data used to fit each candidate distribution.
+
+    distribution_candidates : list of BaseUnivariateDist
+        A list of candidate distribution estimators. Each candidate must be an instance
+        of a class that inherits from `BaseUnivariateDist`.
+        If None, defaults to `[Gaussian(), StudentT(), JohnsonSU()]`.
+
+    selection_criterion : SelectionCriterion, default=SelectionCriterion.AIC
+        The criterion used for model selection. Possible values are:
+            - SelectionCriterion.AIC : Akaike Information Criterion
+            - SelectionCriterion.BIC : Bayesian Information Criterion
+
+    Returns
+    -------
+    BaseUnivariateDist
+        The fitted candidate estimator that minimizes the selected information
+        criterion.
+
+    Raises
+    ------
+    ValueError
+        If X does not have exactly one column or if any candidate in the list does not
+        inherit from BaseUnivariateDist.
+    """
+    if distribution_candidates is None:
+        distribution_candidates = [
+            Gaussian(),
+            StudentT(),
+            JohnsonSU(),
+        ]
+
+    X = np.asarray(X)
+    if X.ndim != 2 or X.shape[1] != 1:
+        raise ValueError("X must contains one column for Univariate Distribution")
+
+    results = {}
+    for dist in distribution_candidates:
+        if not isinstance(dist, BaseUnivariateDist):
+            raise ValueError("Each candidate must inherit from `BaseUnivariateDist`")
+        dist = sk.clone(dist)
+        dist.fit(X)
+
+        match selection_criterion:
+            case selection_criterion.AIC:
+                results[dist] = dist.aic(X)
+            case selection_criterion.BIC:
+                results[dist] = dist.bic(X)
+            case _:
+                raise ValueError(f"{selection_criterion} not implemented")
+
+    selected_dist = min(results, key=results.get)
+    return selected_dist

skfolio/distribution/univariate/_student_t.py

@@ -0,0 +1,144 @@
+"""Univariate Student's t Estimation."""
+
+# Copyright (c) 2025
+# Authors: The skfolio developers
+# Credits: Matteo Manzi, Vincent Maladière, Carlo Nicolini
+# SPDX-License-Identifier: BSD-3-Clause
+
+import numpy.typing as npt
+import scipy.stats as st
+
+from skfolio.distribution.univariate._base import BaseUnivariateDist
+
+
+class StudentT(BaseUnivariateDist):
+    r"""Student's t Distribution Estimation.
+
+    This estimator fits a univariate Student's t distribution to the input data.
+
+    The probability density function is:
+
+    .. math::
+
+        f(x, \nu) = \frac{\Gamma((\nu+1)/2)}
+                        {\sqrt{\pi \nu} \Gamma(\nu/2)}
+                    (1+x^2/\nu)^{-(\nu+1)/2}
+
+    where :math:`x` is a real number and the degrees of freedom parameter :math:`\nu`
+    (denoted `dof` in the implementation) satisfies :math:`\nu > 0`. :math:`\Gamma` is
+    the gamma function (`scipy.special.gamma`).
+
+    The probability density above is defined in the "standardized" form. To shift
+    and/or scale the distribution use the loc and scale parameters. Specifically,
+    `pdf(x, df, loc, scale)` is equivalent to `pdf(y, df) / scale` with
+    `y = (x - loc) / scale`.
+
+    For more information, you can refer to the `scipy documentation <https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.t.html#scipy.stats.t>`_
+
+
+    Parameters
+    ----------
+    loc : float or None, default=None
+        If provided, the location parameter is fixed to this value during fitting.
+        Otherwise, it is estimated from the data.
+
+    scale : float or None, default=None
+        If provided, the scale parameter is fixed to this value during fitting.
+        Otherwise, it is estimated from the data.
+
+    random_state : int, RandomState instance or None, default=None
+        Seed or random state to ensure reproducibility.
+
+    Attributes
+    ----------
+    dof_ : float
+        The fitted degrees of freedom for the Student's t distribution.
+
+    loc_ : float
+        The fitted location parameter.
+
+    scale_ : float
+        The fitted scale parameter.
+
+    Examples
+    --------
+    >>> from skfolio.datasets import load_sp500_index
+    >>> from skfolio.preprocessing import prices_to_returns
+    >>> from skfolio.distribution.univariate import StudentT
+    >>>
+    >>> # Load historical prices and convert them to returns
+    >>> prices = load_sp500_index()
+    >>> X = prices_to_returns(prices)
+    >>>
+    >>> # Initialize the estimator.
+    >>> model = StudentT()
+    >>>
+    >>> # Fit the model to the data.
+    >>> model.fit(X)
+    >>>
+    >>> # Display the fitted parameters.
+    >>> print(model.fitted_repr)
+    StudentT(2.75, 0.000618, 0.00681)
+    >>>
+    >>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
+    >>> log_likelihood = model.score_samples(X)
+    >>> score = model.score(X)
+    >>> cdf = model.cdf(X)
+    >>> ppf = model.ppf(X)
+    >>> aic = model.aic(X)
+    >>> bic = model.bic(X)
+    >>>
+    >>> # Generate 5 new samples from the fitted distribution.
+    >>> samples = model.sample(n_samples=5)
+    >>>
+    >>> # Plot the estimated probability density function (PDF).
+    >>> fig = model.plot_pdf()
+    >>> fig.show()
+    """
+
+    dof_: float
+    loc_: float
+    scale_: float
+    _scipy_model = st.t
+
+    def __init__(
+        self,
+        loc: float | None = None,
+        scale: float | None = None,
+        random_state: int | None = None,
+    ):
+        super().__init__(random_state=random_state)
+        self.loc = loc
+        self.scale = scale
+
+    @property
+    def _scipy_params(self) -> dict[str, float]:
+        """Dictionary of parameters to pass to the underlying SciPy distribution."""
+        return {"loc": self.loc_, "scale": self.scale_, "df": self.dof_}
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "StudentT":
+        """Fit the univariate Student's t distribution model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, 1)
+            The input data. X must contain a single column.
+
+        y : None
+            Ignored. Provided for compatibility with scikit-learn's API.
+
+        Returns
+        -------
+        self : StudentT
+            Returns the instance itself.
+        """
+        X = self._validate_X(X, reset=True)
+
+        fixed_params = {}
+        if self.loc is not None:
+            fixed_params["floc"] = self.loc
+        if self.scale is not None:
+            fixed_params["fscale"] = self.scale
+
+        self.dof_, self.loc_, self.scale_ = self._scipy_model.fit(X, **fixed_params)
+        return self

skfolio/exceptions.py

@@ -5,7 +5,7 @@ classes used across skfolio.
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 __all__ = [
     "DuplicateGroupsError",
@@ -17,20 +17,20 @@ __all__ = [
 
 
 class OptimizationError(Exception):
-    """Optimization Did not converge"""
+    """Optimization Did not converge."""
 
 
 class EquationToMatrixError(Exception):
-    """Error while processing equations"""
+    """Error while processing equations."""
 
 
 class GroupNotFoundError(Exception):
-    """Group name not found in the groups"""
+    """Group name not found in the groups."""
 
 
 class DuplicateGroupsError(Exception):
-    """Group name appear in multiple group levels"""
+    """Group name appear in multiple group levels."""
 
 
 class NonPositiveVarianceError(Exception):
-    """Variance negative or null"""
+    """Variance negative or null."""

skfolio/measures/__init__.py

@@ -1,7 +1,7 @@
 """Module that includes all Measures functions used across `skfolio`."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from skfolio.measures._enums import (
     BaseMeasure,

skfolio/measures/_enums.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 abc import abstractmethod
 from enum import auto
@@ -11,10 +11,10 @@ from skfolio.utils.tools import AutoEnum
 
 
 class BaseMeasure(AutoEnum):
-    """Base Enum of measures"""
+    """Base Enum of measures."""
 
     def __repr__(self) -> str:
-        """Enum representation for improved reading"""
+        """Enum representation for improved reading."""
         words = [
             (
                 word.capitalize()
@@ -73,7 +73,7 @@ class BaseMeasure(AutoEnum):
 
 
 class PerfMeasure(BaseMeasure):
-    """Enumeration of performance measures
+    """Enumeration of performance measures.
 
     Attributes
     ----------
@@ -103,7 +103,7 @@ class PerfMeasure(BaseMeasure):
 
 
 class RiskMeasure(BaseMeasure):
-    """Enumeration of risk measures
+    """Enumeration of risk measures.
 
     Attributes
     ----------
@@ -199,7 +199,7 @@ class RiskMeasure(BaseMeasure):
 
 
 class ExtraRiskMeasure(BaseMeasure):
-    """Enumeration of other risk measures not used in convex optimization
+    """Enumeration of other risk measures not used in convex optimization.
 
     Attributes
     ----------
@@ -247,7 +247,7 @@ class ExtraRiskMeasure(BaseMeasure):
 
 
 class RatioMeasure(BaseMeasure):
-    """Enumeration of ratio measures
+    """Enumeration of ratio measures.
 
     Attributes
     ----------

skfolio/measures/_measures.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
 # Gini mean difference and OWA GMD weights features are derived
 # from Riskfolio-Lib, Copyright (c) 2020-2023, Dany Cajas, Licensed under BSD 3 clause.
 
@@ -179,7 +179,6 @@ def third_central_moment(returns: np.ndarray) -> float:
     value : float
         Third central moment.
     """
-
     return np.sum(np.power(returns - np.mean(returns, axis=0), 3)) / len(returns)
 
 
@@ -200,7 +199,6 @@ def skew(returns: np.ndarray) -> float:
     value : float
         Skew.
     """
-
     return third_central_moment(returns) / standard_deviation(returns) ** 3
 
 
@@ -236,7 +234,6 @@ def kurtosis(returns: np.ndarray) -> float:
     value : float
         Kurtosis.
     """
-
     return fourth_central_moment(returns) / standard_deviation(returns) ** 4
 
 
@@ -571,7 +568,7 @@ def ulcer_index(drawdowns: np.ndarray) -> float:
 def owa_gmd_weights(n_observations: int) -> np.ndarray:
     """Compute the OWA weights used for the Gini mean difference (GMD) computation.
 
-     Parameters
+    Parameters
     ----------
     n_observations : int
         Number of observations.
@@ -610,8 +607,8 @@ def gini_mean_difference(returns: np.ndarray) -> float:
 
 
 def effective_number_assets(weights: np.ndarray) -> float:
-    r"""Computes the effective number of assets, defined as the inverse of the
-    Herfindahl index [1]_:
+    r"""Compute the effective number of assets, defined as the inverse of the
+    Herfindahl index.
 
     .. math:: N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}
 

skfolio/metrics/__init__.py

@@ -1,3 +1,5 @@
+"""Metrics module."""
+
 from skfolio.metrics._scorer import make_scorer
 
 __all__ = ["make_scorer"]

skfolio/metrics/_scorer.py

@@ -1,8 +1,8 @@
-"""Scorer module"""
+"""Scorer 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-portfolio, Copyright (c) 2022, Carlo Nicolini, Licensed under MIT Licence.
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
@@ -18,7 +18,7 @@ from skfolio.portfolio import Portfolio
 
 
 class _PortfolioScorer:
-    """Portfolio Scorer wrapper"""
+    """Portfolio Scorer wrapper."""
 
     def __init__(self, score_func: Callable, sign: int, kwargs: dict):
         self._score_func = score_func
@@ -119,7 +119,7 @@ def make_scorer(
                 greater_is_better = False
 
         def score_func(pred: Portfolio) -> float:
-            """Score function"""
+            """Score function."""
             return getattr(pred, measure.value)
 
     sign = 1 if greater_is_better else -1

skfolio/model_selection/__init__.py

@@ -1,7 +1,7 @@
-"""Model selection module"""
+"""Model selection module."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from skfolio.model_selection._combinatorial import (
     BaseCombinatorialCV,

skfolio/model_selection/_combinatorial.py

@@ -1,8 +1,8 @@
-"""Combinatorial module"""
+"""Combinatorial 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-portfolio, Copyright (c) 2022, Carlo Nicolini, Licensed under MIT Licence.
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
@@ -36,7 +36,7 @@ class BaseCombinatorialCV(ABC):
 
     @abstractmethod
     def get_path_ids(self) -> np.ndarray:
-        """Return the path id of each test sets in each split"""
+        """Return the path id of each test sets in each split."""
         pass
 
     __repr__ = sks.BaseCrossValidator.__repr__
@@ -196,18 +196,19 @@ class CombinatorialPurgedCV(BaseCombinatorialCV):
 
     @property
     def n_splits(self) -> int:
-        """Number of splits"""
+        """Number of splits."""
         return _n_splits(n_folds=self.n_folds, n_test_folds=self.n_test_folds)
 
     @property
     def n_test_paths(self) -> int:
         """Number of test paths that can be reconstructed from the train/test
-        combinations"""
+        combinations.
+        """
         return _n_test_paths(n_folds=self.n_folds, n_test_folds=self.n_test_folds)
 
     @property
     def test_set_index(self) -> np.ndarray:
-        """Location of each test set"""
+        """Location of each test set."""
         return np.array(
             list(itertools.combinations(np.arange(self.n_folds), self.n_test_folds))
         ).reshape(-1, self.n_test_folds)
@@ -215,7 +216,8 @@ class CombinatorialPurgedCV(BaseCombinatorialCV):
     @property
     def binary_train_test_sets(self) -> np.ndarray:
         """Identify training and test folds for each combinations by assigning `0` to
-        training folds and `1` to test folds"""
+        training folds and `1` to test folds.
+        """
         folds_train_test = np.zeros((self.n_folds, self.n_splits))
         folds_train_test[
             self.test_set_index, np.arange(self.n_splits)[:, np.newaxis]
@@ -230,7 +232,7 @@ class CombinatorialPurgedCV(BaseCombinatorialCV):
         )
 
     def get_path_ids(self) -> np.ndarray:
-        """Return the path id of each test sets in each split"""
+        """Return the path id of each test sets in each split."""
         recombine_paths = self.recombined_paths
         path_ids = np.zeros((self.n_splits, self.n_test_folds), dtype=int)
         for i in range(self.n_splits):
@@ -334,7 +336,7 @@ class CombinatorialPurgedCV(BaseCombinatorialCV):
         )
 
     def plot_train_test_folds(self) -> skt.Figure:
-        """Plot the train/test fold locations"""
+        """Plot the train/test fold locations."""
         values = self.binary_train_test_sets
         fill_color = np.where(values == 0, "blue", "red")
         fill_color = fill_color.astype(object)
@@ -367,7 +369,8 @@ class CombinatorialPurgedCV(BaseCombinatorialCV):
 
     def plot_train_test_index(self, X) -> skt.Figure:
         """Plot the training and test indices for each combinations by assigning `0` to
-        training, `1` to test and `-1` to both purge and embargo indices."""
+        training, `1` to test and `-1` to both purge and embargo indices.
+        """
         next(self.split(X))
         n_samples = X.shape[0]
         cond = [
@@ -425,12 +428,12 @@ def _n_splits(n_folds: int, n_test_folds: int) -> int:
     n_splits : int
         Number of splits
     """
-    return int(math.comb(n_folds, n_test_folds))
+    return math.comb(n_folds, n_test_folds)
 
 
 def _n_test_paths(n_folds: int, n_test_folds: int) -> int:
     """Number of test paths that can be reconstructed from the train/test
-    combinations
+    combinations.
 
     Parameters
     ----------