<a id="skfolio-distribution-basemultivariatedist"></a>

# skfolio.distribution.BaseMultivariateDist

<a id="skfolio.distribution.BaseMultivariateDist"></a>

### *class* skfolio.distribution.BaseMultivariateDist(random_state=None)

Base class for Multivariate Distribution Estimators.

This abstract class defines the interface for multivariate distribution models.

* **Parameters:**
  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  [`fitted_repr`](#skfolio.distribution.BaseMultivariateDist.fitted_repr)
  : String representation of the fitted copula.

  [`n_params`](#skfolio.distribution.BaseMultivariateDist.n_params)
  : Number of model parameters.

### Methods

| [`aic`](#skfolio.distribution.BaseMultivariateDist.aic)(X)                                      | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                          |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](#skfolio.distribution.BaseMultivariateDist.bic)(X)                                      | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                        |
| [`fit`](#skfolio.distribution.BaseMultivariateDist.fit)(X[, y])                                 | Fit the multivariate distribution model.                                                                                                                            |
| [`get_metadata_routing`](#skfolio.distribution.BaseMultivariateDist.get_metadata_routing)()                      | Get metadata routing of this object.                                                                                                                                |
| [`get_params`](#skfolio.distribution.BaseMultivariateDist.get_params)([deep])                          | Get parameters for this estimator.                                                                                                                                  |
| [`plot_scatter_matrix`](#skfolio.distribution.BaseMultivariateDist.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`](#skfolio.distribution.BaseMultivariateDist.sample)([n_samples, conditioning])           | Generate random samples from the distribution model.                                                                                                                |
| [`score`](#skfolio.distribution.BaseMultivariateDist.score)(X[, y])                               | Compute the total log-likelihood under the model.                                                                                                                   |
| [`score_samples`](#skfolio.distribution.BaseMultivariateDist.score_samples)(X)                            | Compute the log-likelihood of each sample (log-pdf) under the distribution model.                                                                                   |
| [`set_params`](#skfolio.distribution.BaseMultivariateDist.set_params)(\*\*params)                      | Set the parameters of this estimator.                                                                                                                               |

<a id="skfolio.distribution.BaseMultivariateDist.aic"></a>

#### 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:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : 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

* <a id='r646ba6e97556-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.BaseMultivariateDist.bic"></a>

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

### References

* <a id='r01b6a2a128e4-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.BaseMultivariateDist.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the multivariate distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *BaseMultivariateDist*
  : Returns the instance itself.

<a id="skfolio.distribution.BaseMultivariateDist.fitted_repr"></a>

#### *abstract property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.BaseMultivariateDist.get_metadata_routing"></a>

#### get_metadata_routing()

Get metadata routing of this object.

Please check [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

* **Returns:**
  **routing** *MetadataRequest*
  : A `MetadataRequest` encapsulating
    routing information.

<a id="skfolio.distribution.BaseMultivariateDist.get_params"></a>

#### get_params(deep=True)

Get parameters for this estimator.

* **Parameters:**
  **deep** *bool, default=True*
  : If True, will return the parameters for this estimator and
    contained subobjects that are estimators.
* **Returns:**
  **params** *dict*
  : Parameter names mapped to their values.

<a id="skfolio.distribution.BaseMultivariateDist.n_params"></a>

#### *abstract property* n_params

Number of model parameters.

<a id="skfolio.distribution.BaseMultivariateDist.plot_scatter_matrix"></a>

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

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:**
  **X** *array-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.

  **conditioning** *dict[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_samples** *int, 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.

  **title** *str, default=”Scatter Matrix”*
  : The title for the plot.
* **Returns:**
  **fig** *plotly.graph_objects.Figure*
  : A figure object containing the scatter matrix.

<a id="skfolio.distribution.BaseMultivariateDist.sample"></a>

#### *abstractmethod* sample(n_samples=1, conditioning=None)

Generate random samples from the distribution model.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.

  **conditioning** *dict[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:**
  **X** *array-like of shape (n_samples, n_assets)*
  : A two-dimensional array where each row is a multivariate observation sampled
    from the fitted distribution model.

<a id="skfolio.distribution.BaseMultivariateDist.score"></a>

#### score(X, 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).

<a id="skfolio.distribution.BaseMultivariateDist.score_samples"></a>

#### *abstractmethod* score_samples(X)

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

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted distribution model.

<a id="skfolio.distribution.BaseMultivariateDist.set_params"></a>

#### 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:**
  **\*\*params** *dict*
  : Estimator parameters.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.