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

skfolio/distribution/univariate/__init__.py

@@ -0,0 +1,19 @@
+"""Univariate Distribution module."""
+
+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._normal_inverse_gaussian import (
+    NormalInverseGaussian,
+)
+from skfolio.distribution.univariate._selection import select_univariate_dist
+from skfolio.distribution.univariate._student_t import StudentT
+
+__all__ = [
+    "BaseUnivariateDist",
+    "Gaussian",
+    "JohnsonSU",
+    "NormalInverseGaussian",
+    "StudentT",
+    "select_univariate_dist",
+]

skfolio/distribution/univariate/_base.py

@@ -0,0 +1,308 @@
+"""Base Univariate Estimator."""
+
+# Copyright (c) 2025
+# Authors: The skfolio developers
+# Credits: Matteo Manzi, Vincent Maladière, Carlo Nicolini
+# SPDX-License-Identifier: BSD-3-Clause
+
+import warnings
+from abc import ABC, abstractmethod
+
+import numpy as np
+import numpy.typing as npt
+import plotly.graph_objects as go
+import scipy.stats as st
+import sklearn.utils as sku
+import sklearn.utils.validation as skv
+
+from skfolio.distribution._base import BaseDistribution
+
+
+class BaseUnivariateDist(BaseDistribution, ABC):
+    """Base Univariate Distribution Estimator.
+
+    This abstract class serves as a foundation for univariate distribution models
+    based on scipy.
+
+    random_state : int, RandomState instance or None, default=None
+        Seed or random state to ensure reproducibility.
+    """
+
+    _scipy_model: st.rv_continuous
+
+    def __init__(self, random_state: int | None = None):
+        super().__init__(random_state=random_state)
+
+    @property
+    @abstractmethod
+    def _scipy_params(self) -> dict[str, float]:
+        """Dictionary of parameters to pass to the underlying SciPy distribution."""
+        pass
+
+    @property
+    def n_params(self) -> int:
+        """Number of model parameters."""
+        return len(self._scipy_params)
+
+    @property
+    def fitted_repr(self) -> str:
+        """String representation of the fitted univariate distribution."""
+        skv.check_is_fitted(self)
+        params = ", ".join([f"{k}={v:0.2g}" for k, v in self._scipy_params.items()])
+        return f"{self.__class__.__name__}({params})"
+
+    @abstractmethod
+    def fit(self, X: npt.ArrayLike, y=None) -> "BaseUnivariateDist":
+        """Fit the univariate 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 : BaseUnivariateDist
+            Returns the instance itself.
+        """
+        pass
+
+    def _validate_X(self, X: npt.ArrayLike, reset: bool) -> np.ndarray:
+        """Validate and convert the input data X.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, 1)
+            The input data. X must contain a single column.
+
+        reset : bool, default=True
+            Whether to reset the `n_features_in_` attribute.
+            If False, the input will be checked for consistency with data
+            provided when reset was last True.
+
+        Returns
+        -------
+        validated_X : ndarray of shape (n_observations, 1).
+            The validated input array
+        """
+        X = skv.validate_data(self, X, dtype=np.float64, reset=reset)
+        if X.shape[1] != 1:
+            raise ValueError(
+                "X should contain a single column for Univariate Distribution"
+            )
+        return X
+
+    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, 1)
+            An array of points at which to evaluate the log-probability density.
+            The data should be a single feature column.
+
+        Returns
+        -------
+        density : ndarray of shape (n_observations,)
+            Log-likelihood values for each observation in X.
+        """
+        X = self._validate_X(X, reset=False)
+        log_density = self._scipy_model.logpdf(X, **self._scipy_params).ravel()
+        return log_density
+
+    def sample(self, n_samples: int = 1):
+        """Generate random samples from the fitted distribution.
+
+        Currently, this is implemented only for gaussian and tophat kernels.
+
+        Parameters
+        ----------
+        n_samples : int, default=1
+            Number of samples to generate.
+
+        Returns
+        -------
+        X : array-like of shape (n_samples, 1)
+            List of samples.
+        """
+        skv.check_is_fitted(self)
+        rng = sku.check_random_state(self.random_state)
+        sample = self._scipy_model.rvs(
+            size=(n_samples, 1), random_state=rng, **self._scipy_params
+        )
+        return sample
+
+    def cdf(self, X: npt.ArrayLike) -> np.ndarray:
+        """Compute the cumulative distribution function (CDF) for the given data.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, 1)
+            Data points at which to evaluate the CDF.
+
+        Returns
+        -------
+        cdf : ndarray of shape (n_observations, 1)
+            The CDF evaluated at each data point.
+        """
+        skv.check_is_fitted(self)
+        return self._scipy_model.cdf(X, **self._scipy_params)
+
+    def ppf(self, X: npt.ArrayLike) -> np.ndarray:
+        """Compute the percent point function (inverse of the CDF) for the given
+         probabilities.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_observations, 1)
+            Probabilities for which to compute the corresponding quantiles.
+
+        Returns
+        -------
+         ppf : ndarray of shape (n_observations, 1)
+            The quantiles corresponding to the given probabilities.
+        """
+        skv.check_is_fitted(self)
+        return self._scipy_model.ppf(X, **self._scipy_params)
+
+    def plot_pdf(
+        self, X: npt.ArrayLike | None = None, title: str | None = None
+    ) -> go.Figure:
+        """Plot the probability density function (PDF).
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, 1), optional
+            If provided, it is used to plot the empirical data KDE for comparison
+            versus the model PDF.
+
+        title : str, optional
+           The title for the plot. If not provided, a default title based on the fitted
+           model's representation is used.
+
+        Returns
+        -------
+        fig : go.Figure
+           A Plotly figure object containing the PDF plot.
+        """
+        skv.check_is_fitted(self)
+        if title is None:
+            title = f"PDF of {self.__class__.__name__}"
+            if X is not None:
+                title += " vs Empirical KDE"
+
+        # Compute the quantile-based range
+        lower_bound = self.ppf(1e-4)
+        upper_bound = self.ppf(1 - 1e-4)
+        # Generate x values across this range
+        x = np.linspace(lower_bound, upper_bound, 1000)
+
+        traces = []
+        if X is not None:
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore", message="^X has feature names", category=UserWarning
+                )
+                X = self._validate_X(X, reset=False)
+            kde = st.gaussian_kde(X[:, 0])
+            y_kde = kde(x)
+            traces.append(
+                go.Scatter(
+                    x=x,
+                    y=y_kde,
+                    mode="lines",
+                    name="Empirical KDE",
+                    line=dict(color="rgb(85,168,104)"),
+                    fill="tozeroy",
+                )
+            )
+
+        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,
+            xaxis_title="x",
+            yaxis_title="Probability Density",
+        )
+        fig.update_xaxes(
+            tickformat=".0%",
+        )
+        return fig
+
+    def qq_plot(self, X: npt.ArrayLike, title: str | None = None) -> go.Figure:
+        """Plot the empirical quantiles of the sample X versus the quantiles of the
+        fitted model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, 1), optional
+            Used to plot the empirical quantiles for comparison versus the model
+            quantiles.
+
+        title : str, optional
+           The title for the plot. If not provided, a default title based on the fitted
+           model's representation is used.
+
+        Returns
+        -------
+        fig : go.Figure
+           A Plotly figure object containing the PDF plot.
+        """
+        skv.check_is_fitted(self)
+        if title is None:
+            title = f"Q-Q Plot of {self.__class__.__name__} vs Sample Data"
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore", message="^X has feature names", category=UserWarning
+            )
+            X = self._validate_X(X, reset=False)
+
+        X_sorted = np.sort(X[:, 0])
+        n = len(X)
+
+        # Compute theoretical quantiles from the model
+        theoretical_quantiles = self.ppf((np.arange(1, n + 1) - 0.5) / n)
+
+        # Create the Q-Q plot using Plotly
+        fig = go.Figure(
+            go.Scatter(
+                x=theoretical_quantiles,
+                y=X_sorted,
+                mode="markers",
+            )
+        )
+        # Add a reference line (45° line)
+        min_val = min(float(theoretical_quantiles[0]), float(X_sorted[0]))
+        max_val = max(float(theoretical_quantiles[-1]), float(X_sorted[-1]))
+        fig.add_trace(
+            go.Scatter(
+                x=[min_val, max_val],
+                y=[min_val, max_val],
+                mode="lines",
+            )
+        )
+        fig.update_layout(
+            title=title,
+            xaxis_title="Theoretical Quantiles",
+            yaxis_title="Sample Quantiles",
+            showlegend=False,
+        )
+        return fig

skfolio/distribution/univariate/_gaussian.py

@@ -0,0 +1,136 @@
+"""Univariate Gaussian 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 Gaussian(BaseUnivariateDist):
+    r"""Gaussian Distribution Estimation.
+
+    This estimator fits a univariate normal (Gaussian) distribution to the input data.
+
+    The probability density function is:
+
+    .. math::
+
+        f(x) = \frac{\exp(-x^2/2)}{\sqrt{2\pi}}
+
+    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, loc, scale)` is equivalent to `pdf(y) / 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.norm.html#scipy.stats.norm>`_
+
+    Parameters
+    ----------
+    loc : float, optional
+        If provided, the location parameter (mean) is fixed to this value.
+        Otherwise, it is estimated from the data.
+
+    scale : float, optional
+        If provided, the scale parameter (standard deviation) is fixed to this value.
+        Otherwise, it is estimated from the data.
+
+    random_state : int, RandomState instance or None, default=None
+        Seed or random state to ensure reproducibility.
+
+    Attributes
+    ----------
+    loc_ : float
+        The fitted location (mean) of the distribution.
+
+    scale_ : float
+        The fitted scale (standard deviation) of the distribution.
+
+    Examples
+    --------
+    >>> from skfolio.datasets import load_sp500_index
+    >>> from skfolio.preprocessing import prices_to_returns
+    >>> from skfolio.distribution.univariate import Gaussian
+    >>>
+    >>> # Load historical prices and convert them to returns
+    >>> prices = load_sp500_index()
+    >>> X = prices_to_returns(prices)
+    >>>
+    >>> # Initialize the Gaussian estimator.
+    >>> model = Gaussian()
+    >>>
+    >>> # Fit the Gaussian model to the data.
+    >>> model.fit(X)
+    >>>
+    >>> # Display the fitted parameters.
+    >>> print(model.fitted_repr)
+    Gaussian(0.00035, 0.0115)
+    >>>
+    >>> # 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 Gaussian distribution.
+    >>> samples = model.sample(n_samples=5)
+    >>>
+    >>> # Plot the estimated probability density function (PDF).
+    >>> fig = model.plot_pdf()
+    >>> fig.show()
+    """
+
+    loc_: float
+    scale_: float
+    _scipy_model = st.norm
+
+    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_}
+
+    def fit(self, X: npt.ArrayLike, y=None) -> "Gaussian":
+        """Fit the univariate 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 : Gaussian
+            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.loc_, self.scale_ = self._scipy_model.fit(X, **fixed_params)
+
+        return self

skfolio/distribution/univariate/_johnson_su.py

@@ -0,0 +1,152 @@
+"""Johnson SU 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 JohnsonSU(BaseUnivariateDist):
+    r"""Johnson SU Distribution Estimation.
+
+    This estimator fits a univariate Johnson SU distribution to the input data.
+    The Johnson SU distribution is flexible and can capture both skewness and fat tails,
+    making it appropriate for financial time series modeling.
+
+    The probability density function is:
+
+    .. math::
+
+        f(x, a, b) = \frac{b}{\sqrt{x^2 + 1}}
+                     \phi(a + b \log(x + \sqrt{x^2 + 1}))
+
+    where :math:`x`, :math:`a`, and :math:`b` are real scalars; :math:`b > 0`.
+    :math:`\phi` is the pdf of the normal distribution.
+
+    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.johnsonsu.html#scipy.stats.johnsonsu>`_
+
+    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 first shape parameter of the Johnson SU distribution.
+
+    b_ : float
+        The fitted second shape parameter of the Johnson SU 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 JohnsonSU
+    >>>
+    >>> # Load historical prices and convert them to returns
+    >>> prices = load_sp500_index()
+    >>> X = prices_to_returns(prices)
+    >>>
+    >>> # Initialize the estimator.
+    >>> model = JohnsonSU()
+    >>>
+    >>> # Fit the model to the data.
+    >>> model.fit(X)
+    >>>
+    >>> # Display the fitted parameters.
+    >>> print(model.fitted_repr)
+    JohnsonSU(0.0742, 1.08, 0.00115, 0.00774)
+    >>>
+    >>> # 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.johnsonsu
+
+    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) -> "JohnsonSU":
+        """Fit the univariate Johnson SU 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 : JohnsonSU
+            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