skfolio.distribution.BaseMultivariateDist#

class skfolio.distribution.BaseMultivariateDist(random_state=None)[source]#

Base class for Multivariate Distribution Estimators.

This abstract class defines the interface for multivariate distribution models.

Parameters:
random_stateint, RandomState instance or None, default=None

Seed or random state to ensure reproducibility.

Attributes:
fitted_repr

String representation of the fitted copula.

n_params

Number of model parameters.

Methods

aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

fit(X[, y])

Fit the multivariate distribution model.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

plot_scatter_matrix([X, conditioning, ...])

Plot the vine copula scatter matrix by generating samples from the fitted distribution model and comparing it versus the empirical distribution of X if provided.

sample([n_samples, conditioning])

Generate random samples from the distribution model.

score(X[, y])

Compute the total log-likelihood under the model.

score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the distribution model.

set_params(**params)

Set the parameters of this estimator.
aic(X)#

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

\[\mathrm{AIC} = -2 \, \log L \;+\; 2 k,\]

where

  • \(\log L\) is the total log-likelihood

  • \(k\) is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

Parameters:
Xarray-like of shape (n_observations, n_features)

The input data on which to compute the AIC.

Returns:
aicfloat

The AIC 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 \(n\) because of the \(\ln(n)\) term.

References

[1]

“A new look at the statistical model identification”, Akaike (1974).

bic(X)#

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

\[\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),\]

where

  • \(\log L\) is the (maximized) total log-likelihood

  • \(k\) is the number of parameters in the model

  • \(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:
Xarray-like of shape (n_observations, n_features)

The input data on which to compute the BIC.

Returns:
bicfloat

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 \(n\) because of the \(\ln(n)\) term.

References

[1]

“Estimating the dimension of a model”, Schwarz, G. (1978).

abstractmethod fit(X, y=None)[source]#

Fit the multivariate distribution model.

Parameters:
Xarray-like of shape (n_observations, n_assets)

Price returns of the assets.

yNone

Ignored. Provided for compatibility with scikit-learn’s API.

Returns:
selfBaseMultivariateDist

Returns the instance itself.

abstract property fitted_repr#

String representation of the fitted copula.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:
routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:
deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:
paramsdict

Parameter names mapped to their values.

abstract property n_params#

Number of model parameters.

plot_scatter_matrix(X=None, conditioning=None, n_samples=1000, title='Scatter Matrix')[source]#

Plot the vine copula scatter matrix by generating samples from the fitted distribution model and comparing it versus the empirical distribution of X if provided.

Parameters:
Xarray-like of shape (n_samples, n_assets), optional

If provided, it is used to plot the empirical scatter matrix for comparison versus the vine copula scatter matrix.

conditioningdict[int | str, float | tuple[float, float] | array-like], optional

A dictionary specifying conditioning information for one or more assets. The dictionary keys are asset indices or names, and the values define how the samples are conditioned for that asset. Three types of conditioning values are supported:

  1. Fixed value (float): If a float is provided, all samples are generated under the condition that the asset takes exactly that value.

  2. Bounds (tuple of two floats): If a tuple (min_value, max_value) is provided, samples are generated under the condition that the asset’s value falls within the specified bounds. Use -np.Inf for no lower bound or np.Inf for no upper bound.

  3. Array-like (1D array): If an array-like of length n_samples is provided, each sample is conditioned on the corresponding value in the array for that asset.

n_samplesint, default=1000

Number of samples used to control the density and readability of the plot. If X is provided and contains more than n_samples rows, a random subsample of size n_samples is selected. Conversely, if X has fewer rows than n_samples, the value is adjusted to match the number of rows in X to ensure balanced visualization.

titlestr, default=”Scatter Matrix”

The title for the plot.

Returns:
figplotly.graph_objects.Figure

A figure object containing the scatter matrix.

abstractmethod sample(n_samples=1, conditioning=None)[source]#

Generate random samples from the distribution model.

Parameters:
n_samplesint, default=1

Number of samples to generate.

conditioningdict[int | str, float | tuple[float, float] | array-like], optional

A dictionary specifying conditioning information for one or more assets. The dictionary keys are asset indices or names, and the values define how the samples are conditioned for that asset. Three types of conditioning values are supported:

  1. Fixed value (float): If a float is provided, all samples are generated under the condition that the asset takes exactly that value.

  2. Bounds (tuple of two floats): If a tuple (min_value, max_value) is provided, samples are generated under the condition that the asset’s value falls within the specified bounds. Use -np.Inf for no lower bound or np.Inf for no upper bound.

  3. Array-like (1D array): If an array-like of length n_samples is provided, each sample is conditioned on the corresponding value in the array for that asset.

Returns:
Xarray-like of shape (n_samples, n_assets)

A two-dimensional array where each row is a multivariate observation sampled from the fitted distribution model.

score(X, y=None)#

Compute the total log-likelihood under the model.

Parameters:
Xarray-like of shape (n_observations, n_features)

An array of data points for which the total log-likelihood is computed.

yNone

Ignored. Provided for compatibility with scikit-learn’s API.

Returns:
logprobfloat

The total log-likelihood (sum of log-pdf values).

abstractmethod score_samples(X)[source]#

Compute the log-likelihood of each sample (log-pdf) under the distribution model.

Parameters:
Xarray-like of shape (n_observations, n_assets)

Price returns of the assets.

Returns:
densityndarray of shape (n_observations,)

The log-likelihood of each sample under the fitted distribution model.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:
**paramsdict

Estimator parameters.

Returns:
selfestimator instance

Estimator instance.