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

skfolio/__init__.py

@@ -1,7 +1,7 @@
-"""skfolio package"""
+"""skfolio package."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 import importlib.metadata
 
 from skfolio.measures import (

skfolio/cluster/__init__.py

@@ -1,7 +1,7 @@
 """Hierarchical Clustering estimators."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from skfolio.cluster._hierarchical import HierarchicalClustering, LinkageMethod
 

skfolio/cluster/_hierarchical.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 enum import auto
 

skfolio/datasets/__init__.py

@@ -1,7 +1,7 @@
 """Datasets module."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from skfolio.datasets._base import (
     load_factors_dataset,

skfolio/datasets/_base.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:
 # scikit-portfolio, Copyright (c) 2022, Carlo Nicolini, Licensed under MIT Licence.
 # scikit-learn, Copyright (c) 2007-2010 David Cournapeau, Fabian Pedregosa, Olivier
@@ -74,7 +74,7 @@ def load_gzip_compressed_csv_data(
     encoding="utf-8",
     datetime_index: bool = True,
 ) -> pd.DataFrame:
-    """Loads gzip-compressed csv files with `importlib.resources`.
+    """Load gzip-compressed csv files with `importlib.resources`.
 
     1) Open resource file with `importlib.resources.open_binary`
     2) Decompress csv file with `gzip.open`

skfolio/datasets/data/__init__.py

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

skfolio/distance/__init__.py

@@ -1,7 +1,7 @@
 """Distance Estimators."""
 
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 from skfolio.distance._base import BaseDistance
 from skfolio.distance._distance import (

skfolio/distance/_base.py

@@ -1,8 +1,8 @@
-"""Base Distance Estimators"""
+"""Base Distance Estimators."""
 
 # 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
 

skfolio/distance/_distance.py

@@ -1,8 +1,8 @@
-"""Distance Estimators"""
+"""Distance Estimators."""
 
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
-# License: BSD 3 clause
+# SPDX-License-Identifier: BSD-3-Clause
 
 import numpy as np
 import numpy.typing as npt
@@ -215,7 +215,7 @@ class SpearmanDistance(BaseDistance):
         self.power = power
 
     def fit(self, X: npt.ArrayLike, y=None) -> "SpearmanDistance":
-        """Fit the Spearman Kendall estimator.
+        """Fit the Spearman estimator.
 
         Parameters
         ----------
@@ -384,7 +384,7 @@ class DistanceCorrelation(BaseDistance):
 
     @staticmethod
     def _dcorr(x: np.ndarray, y: np.ndarray):
-        """Calculate the distance correlation between two variables"""
+        """Calculate the distance correlation between two variables."""
         x = scd.squareform(scd.pdist(x.reshape(-1, 1)))
         y = scd.squareform(scd.pdist(y.reshape(-1, 1)))
         x = x - x.mean(axis=0)[np.newaxis, :] - x.mean(axis=1)[:, np.newaxis] + x.mean()

skfolio/distribution/__init__.py

@@ -0,0 +1,56 @@
+"""Distribution module."""
+
+from skfolio.distribution._base import BaseDistribution, SelectionCriterion
+from skfolio.distribution.copula import (
+    BaseBivariateCopula,
+    ClaytonCopula,
+    CopulaRotation,
+    GaussianCopula,
+    GumbelCopula,
+    IndependentCopula,
+    JoeCopula,
+    StudentTCopula,
+    compute_pseudo_observations,
+    empirical_tail_concentration,
+    plot_tail_concentration,
+    select_bivariate_copula,
+)
+from skfolio.distribution.multivariate import (
+    BaseMultivariateDist,
+    DependenceMethod,
+    VineCopula,
+)
+from skfolio.distribution.univariate import (
+    BaseUnivariateDist,
+    Gaussian,
+    JohnsonSU,
+    NormalInverseGaussian,
+    StudentT,
+    select_univariate_dist,
+)
+
+__all__ = [
+    "BaseBivariateCopula",
+    "BaseDistribution",
+    "BaseMultivariateDist",
+    "BaseUnivariateDist",
+    "ClaytonCopula",
+    "CopulaRotation",
+    "DependenceMethod",
+    "Gaussian",
+    "GaussianCopula",
+    "GumbelCopula",
+    "IndependentCopula",
+    "JoeCopula",
+    "JohnsonSU",
+    "NormalInverseGaussian",
+    "SelectionCriterion",
+    "StudentT",
+    "StudentTCopula",
+    "VineCopula",
+    "compute_pseudo_observations",
+    "empirical_tail_concentration",
+    "plot_tail_concentration",
+    "select_bivariate_copula",
+    "select_univariate_dist",
+]

skfolio/distribution/_base.py

@@ -0,0 +1,203 @@
+"""Base Distribution Estimator."""
+
+# Copyright (c) 2025
+# Authors: The skfolio developers
+# Credits: Matteo Manzi, Vincent Maladière, Carlo Nicolini
+# SPDX-License-Identifier: BSD-3-Clause
+
+from abc import ABC, abstractmethod
+from enum import auto
+
+import numpy as np
+import numpy.typing as npt
+import sklearn.base as skb
+
+from skfolio.utils.tools import AutoEnum
+
+
+class SelectionCriterion(AutoEnum):
+    """Enum representing the selection criteria.
+
+    Attributes
+    ----------
+    AIC : str
+        Akaike Information Criterion (AIC)
+
+    BIC : str
+        Bayesian Information Criterion (BIC)
+    """
+
+    AIC = auto()
+    BIC = auto()
+
+
+class BaseDistribution(skb.BaseEstimator, ABC):
+    """Base Distribution Estimator.
+
+    This abstract class serves as a foundation for distribution models in skfolio.
+
+    random_state : int, RandomState instance or None, default=None
+        Seed or random state to ensure reproducibility.
+    """
+
+    def __init__(self, random_state: int | None = None):
+        self.random_state = random_state
+
+    @property
+    @abstractmethod
+    def n_params(self) -> int:
+        """Number of model parameters."""
+        pass
+
+    @property
+    @abstractmethod
+    def fitted_repr(self) -> str:
+        """String representation of the fitted model."""
+        pass
+
+    @abstractmethod
+    def fit(self, X: npt.ArrayLike, y=None) -> "BaseDistribution":
+        """Fit the univariate distribution model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_features)
+            The input data.
+
+        y : None
+            Ignored. Provided for compatibility with scikit-learn's API.
+
+        Returns
+        -------
+        self : BaseDistribution
+            Returns the instance itself.
+        """
+        pass
+
+    @abstractmethod
+    def score_samples(self, X: npt.ArrayLike) -> np.ndarray:
+        """Compute the log-likelihood of each sample (log-pdf) under the model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_features)
+            The input data.
+
+        Returns
+        -------
+        density : ndarray of shape (n_observations,)
+            Log-likelihood values for each observation in X.
+        """
+        pass
+
+    def sample(self, n_samples: int = 1):
+        """Generate random samples from the fitted model.
+
+        Parameters
+        ----------
+        n_samples : int, default=1
+            Number of samples to generate.
+
+        Returns
+        -------
+        X : array-like of shape (n_samples, 1)
+            List of samples.
+        """
+        pass
+
+    def score(self, X: npt.ArrayLike, y=None):
+        """Compute the total log-likelihood under the model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_features)
+            An array of data points for which the total log-likelihood is computed.
+
+        y : None
+            Ignored. Provided for compatibility with scikit-learn's API.
+
+        Returns
+        -------
+        logprob : float
+            The total log-likelihood (sum of log-pdf values).
+        """
+        return np.sum(self.score_samples(X))
+
+    def aic(self, X: npt.ArrayLike) -> float:
+        r"""Compute the Akaike Information Criterion (AIC) for the model given data X.
+
+        The AIC is defined as:
+
+        .. math::
+            \mathrm{AIC} = -2 \, \log L \;+\; 2 k,
+
+        where
+
+        - :math:`\log L` is the total log-likelihood
+        - :math:`k` is the number of parameters in the model
+
+        A lower AIC value indicates a better trade-off between model fit and complexity.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_features)
+            The input data on which to compute the AIC.
+
+        Notes
+        -----
+        In practice, both AIC and BIC measure the trade-off between model fit and
+        complexity, but BIC tends to prefer simpler models for large :math:`n`
+        because of the :math:`\ln(n)` term.
+
+        Returns
+        -------
+        aic : float
+            The AIC of the fitted model on the given data.
+
+        References
+        ----------
+        .. [1] "A new look at the statistical model identification", Akaike (1974).
+        """
+        log_likelihood = self.score(X)
+        return 2 * (self.n_params - log_likelihood)
+
+    def bic(self, X: npt.ArrayLike) -> float:
+        r"""Compute the Bayesian Information Criterion (BIC) for the model given data X.
+
+        The BIC is defined as:
+
+        .. math::
+           \mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),
+
+        where
+
+        - :math:`\log L` is the (maximized) total log-likelihood
+        - :math:`k` is the number of parameters in the model
+        - :math:`n` is the number of observations
+
+        A lower BIC value suggests a better fit while imposing a stronger penalty
+        for model complexity than the AIC.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, n_features)
+            The input data on which to compute the BIC.
+
+        Returns
+        -------
+        bic : float
+           The BIC of the fitted model on the given data.
+
+        Notes
+        -----
+        In practice, both AIC and BIC measure the trade-off between model fit and
+        complexity, but BIC tends to prefer simpler models for large :math:`n`
+        because of the :math:`\ln(n)` term.
+
+        References
+        ----------
+        .. [1]  "Estimating the dimension of a model", Schwarz, G. (1978).
+        """
+        log_likelihood = self.score(X)
+        n = X.shape[0]
+        return -2 * log_likelihood + self.n_params * np.log(n)

skfolio/distribution/copula/__init__.py

@@ -0,0 +1,35 @@
+"""Copula module."""
+
+from skfolio.distribution.copula._base import (
+    UNIFORM_MARGINAL_EPSILON,
+    BaseBivariateCopula,
+)
+from skfolio.distribution.copula._clayton import ClaytonCopula
+from skfolio.distribution.copula._gaussian import GaussianCopula
+from skfolio.distribution.copula._gumbel import GumbelCopula
+from skfolio.distribution.copula._independent import IndependentCopula
+from skfolio.distribution.copula._joe import JoeCopula
+from skfolio.distribution.copula._selection import select_bivariate_copula
+from skfolio.distribution.copula._student_t import StudentTCopula
+from skfolio.distribution.copula._utils import (
+    CopulaRotation,
+    compute_pseudo_observations,
+    empirical_tail_concentration,
+    plot_tail_concentration,
+)
+
+__all__ = [
+    "UNIFORM_MARGINAL_EPSILON",
+    "BaseBivariateCopula",
+    "ClaytonCopula",
+    "CopulaRotation",
+    "GaussianCopula",
+    "GumbelCopula",
+    "IndependentCopula",
+    "JoeCopula",
+    "StudentTCopula",
+    "compute_pseudo_observations",
+    "empirical_tail_concentration",
+    "plot_tail_concentration",
+    "select_bivariate_copula",
+]