> ## Documentation Index > Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Base > systematica.models.arbitrage_index.base ## `BaseCopula` ```python theme={null} BaseCopula( kendall_tau: float, rotation: str | systematica.models.arbitrage_index.utils.BaseCopulaRotation = BaseCopulaRotation.R0, start: float = 0.001, stop: float = 0.999, num: int = 100, ) ``` Abstract base class for copula models used for statistical arbitrage and copula-based modeling. Method generated by attrs for class BaseCopula. ### Ancestors * `abc.ABC` ### Descendants * `systematica.models.arbitrage_index.clayton.Clayton` * `systematica.models.arbitrage_index.frank.Frank` * `systematica.models.arbitrage_index.gumbel.Gumbel` * `systematica.models.arbitrage_index.joe.Joe` * `systematica.models.arbitrage_index.student_t.StudentT` ### Instance variables * `model_name: str`: Model name, incl. fitted rotation * `dependence: float`: Estimate the parameters from copulas and the Kendall rank correlation. * `lower_tail_dependence: float`: Theoretical lower tail dependence coefficient. * `upper_tail_dependence: float`: Theoretical upper tail dependence coefficient. * `kendall_tau: float`: Kendall's tau correlation coefficient, with values ranging from `-1` (perfect disagreement) to `1` (perfect agreement) and `0` indicating no correlation. * `linear_space: numpy.ndarray`: * `num: int`: Number of samples to generate. Must be at least 10. Default is `100`. * `rotation: str | systematica.models.arbitrage_index.utils.BaseCopulaRotation`: Rotations allow the copula to be adapted for different types of tail dependence. - A `180` rotation captures extreme co-movements in the lower tail (i.e. simultaneous extreme losses). - A `90` rotation captures scenarios where one variable exhibits extreme losses while the other shows extreme gains. - A `270` rotation captures the opposite scenario, where one variable experiences extreme gains while the other suffers extreme losses. See `BaseCopulaRotation`. If set to `auto`, applies best fitted rotation. Defaults to `BaseCopulaRotation.R0`. * `rotation_: systematica.models.arbitrage_index.utils.BaseCopulaRotation`: Best fitted rotation applied to the copula model, initialized to `R0` (no rotation). * `sample: Tuple[numpy.ndarray, numpy.ndarray]`: * `start: float`: The starting value of the sequence. Must be greater than 0. Defaults to `0.001`. * `stop: float`: The end value of the sequence. Must be less than 1. Defaults to `0.999`. ### Methods #### `density` ```python theme={null} density( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Estimate the log probability density function for given `ui` and `vi` values. **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | ------------------------ | | `u` | `tp.Array1d` | `--` | First uniform marginal. | | `v` | `tp.Array1d` | `--` | Second uniform marginal. | **Returns**: | Type | Description | | ------------ | ------------------------ | | `tp.Array1d` | Log probability density. | #### `cumulative_density` ```python theme={null} cumulative_density( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Calculate cumulative density of the bivariate copula: $$ P(U<=u, V<=v) $$ **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | ------------------------ | | `u` | `tp.Array1d` | `--` | First uniform marginal. | | `v` | `tp.Array1d` | `--` | Second uniform marginal. | **Returns**: | Type | Description | | ------------ | ------------------------------- | | `tp.Array1d` | Cumulative probability density. | #### `arbitrage` ```python theme={null} arbitrage( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Calculate the mispricing index for every time step in the trading period using the estimated copula. Mispricing indices are the conditional probabilities: $$ P(U < u | V = v) \text{ and } P(V < v | U = u). $$ **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | -------------------------------------------- | | `u` | `tp.Array1d` | `--` | The first component of the bivariate input. | | `v` | `tp.Array1d` | `--` | The second component of the bivariate input. | **Returns**: | Type | Description | | ------------ | -------------------------------------------------------- | | `tp.Array2d` | The mispricing indices for the copula, a.k.a. arbitrage. | #### `partial_derivative` ```python theme={null} partial_derivative( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Compute the h-function (partial derivative) for the bivariate copula, a.k.a. the mispricing index, for every time step in the trading period using the estimated copula. **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | -------------------------------------------- | | `u` | `tp.Array1d` | `--` | The first component of the bivariate input. | | `v` | `tp.Array1d` | `--` | The second component of the bivariate input. | **Returns**: | Type | Description | | ------------ | -------------------------------------------------------- | | `tp.Array2d` | The mispricing indices for the copula, a.k.a. arbitrage. | #### `score` ```python theme={null} score( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Compute the log-likelihood score of each sample (log-pdf) under the model. `u` and `v` are bivariate inputs `(u, v)` where each row represents a bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`, having been transformed to uniform marginals. **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | -------------------------------------------- | | `u` | `tp.Array1d` | `--` | The first component of the bivariate input. | | `v` | `tp.Array1d` | `--` | The second component of the bivariate input. | **Returns**: | Type | Description | | ------------ | ---------------------------------------------------------------- | | `tp.Array1d` | The log-likelihood score of each sample under the fitted copula. | #### `probability` ```python theme={null} probability( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> numpy.ndarray ``` Probability density function (PDF). `u` and `v` are bivariate inputs `(u, v)` where each row represents a bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`, having been transformed to uniform marginals. **Returns**: | Type | Description | | ------------ | ----------------------------------- | | `tp.Array2d` | Probability density function (PDF). | #### `set_rotation` ```python theme={null} set_rotation( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> Self ``` Set rotation. **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | ------------------------ | | `u` | `tp.Array1d` | `--` | First uniform marginal. | | `v` | `tp.Array1d` | `--` | Second uniform marginal. | **Returns**: | Type | Description | | --------- | --------------- | | `tp.Self` | Copula instance | #### `best_fit` ```python theme={null} best_fit( self, u: numpy.ndarray, v: numpy.ndarray, ) ‑> Tuple[numpy.ndarray, numpy.ndarray] ``` Transform `u` and `v` with rotated functions. Handle model fitting and rotation of uniform marginals. **Parameters**: | Name | Type | Default | Description | | ---- | ------------ | ------- | ------------------------ | | `u` | `tp.Array1d` | `--` | First uniform marginal. | | `v` | `tp.Array1d` | `--` | Second uniform marginal. | **Returns**: | Type | Description | | ---------------------------------- | ------------------ | | `tp.Tuple[tp.Array1d, tp.Array1d]` | Rotated marginals. | #### `criterion` ```python theme={null} criterion( self, u: numpy.ndarray, v: numpy.ndarray, model_validation_method: str = 'aic', ) ‑> float ``` Calculate the criterion value (e.g., `aic`) for the given copula model. **Parameters**: | Name | Type | Default | Description | | ------------------------- | --------- | ------- | ------------------------------------------------------------------- | | `u` | `Array1d` | `--` | The array of the first component values. | | `v` | `Array1d` | `--` | The array of the second component values. | | `model_validation_method` | `str` | `aic` | The method to use for the criterion calculation. Defaults to "aic". | **Returns**: | Type | Description | | ------- | ---------------------------------------------------------------------- | | `float` | The criterion value for the model, or NaN if score cannot be computed. | **Raises**: | Type | Description | | ------------ | ---------------------------------------- | | `ValueError` | If the provided method is not supported. | #### `tail_concentration` ```python theme={null} tail_concentration( self, u_or_v: numpy.ndarray, ) ‑> numpy.ndarray ``` Compute the tail concentration function for a set of quantiles. The tail concentration function is defined as follows: * For quantiles $q ≤ 0.5$: $$ C(q) = P(U ≤ q, V ≤ q) / q $$ * For quantiles $q > 0.5$: $$ C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q) $$ where $U$ and $V$ are the pseudo-observations of the first and second variables, respectively. This function returns the concentration values for each $q$ provided. **References**: * "Quantitative Risk Management: Concepts, Techniques, and Tools", McNeil, Frey, Embrechts (2005) **Parameters**: | Name | Type | Default | Description | | -------- | ------------ | ------- | -------------------------------------------------------------------------------------------------- | | `u_or_v` | `tp.Array1d` | `--` | A 1D array of quantile levels (values between 0 and 1) at which to compute the tail concentration. | **Raises**: | Type | Description | | ------------ | ------------------------------------------------------------ | | `ValueError` | If any value in `quantiles` is not in the interval `[0, 1]`. | **Returns**: | Type | Description | | ------------ | ---------------------------------------------------------------------- | | `tp.Array1d` | The computed tail concentration values corresponding to each quantile. | #### `empirical_tail_concentration` ```python theme={null} empirical_tail_concentration( self, u: numpy.ndarray, v: numpy.ndarray, quantiles: numpy.ndarray, ) ‑> numpy.ndarray ``` Compute empirical tail concentration for the two variables in X. This function computes the concentration at each quantile provided. The tail concentration are estimated as: * Lower tail: $$ \lambda_L(q) = P(U_2 ≤ q | U_1 ≤ q) $$ * Upper tail: $$ \lambda_U(q) = P(U_2 ≥ q | U_1 ≥ q) $$ where $U_1$ and $U_2$ are the pseudo-observations. **Parameters**: | Name | Type | Default | Description | | ----------- | ------------ | ------- | --------------------------------------------------------------------------------------------- | | `u` | `tp.Array1d` | `--` | The array of the first component values. | | `v` | `tp.Array1d` | `--` | The array of the second component values. | | `quantiles` | `tp.Array1d` | `--` | A 1D array of quantile levels (values between 0 and 1) at which to compute the concentration. | **Raises**: | Type | Description | | ------------ | ------------------------------------------------------------------------------------ | | `ValueError` | If `X` is not a 2D array with exactly 2 columns or if quantiles are not in `[0, 1]`. | **Returns**: | Type | Description | | ------------ | ------------------------------------------------------------------------ | | `tp.Array1d` | An array of empirical tail concentration values for the given quantiles. | #### `probability_density_matrix` ```python theme={null} probability_density_matrix( self, to_numpy: bool = True, ) ‑> pandas.core.frame.DataFrame | numpy.ndarray ``` Create probability density matrix. **Parameters**: | Name | Type | Default | Description | | ---------- | ------ | ------- | ---------------------------------------------------------------------------------------------- | | `to_numpy` | `bool` | `s` | to `True` Return `numpy` array if `True`. `pandas.DataFrame` otherwise. The default is `True`. | **Returns**: | Type | Description | | -------------------------- | --------------------------- | | `tp.Array \| pd.DataFrame` | Probability density matrix. | #### `partial_derivative_matrix` ```python theme={null} partial_derivative_matrix( self, to_numpy: bool = True, ) ‑> pandas.core.frame.DataFrame | numpy.ndarray ``` Create partial derivative matrix. **Parameters**: | Name | Type | Default | Description | | ---------- | ------ | ------- | ---------------------------------------------------------------------------------------------- | | `to_numpy` | `bool` | `s` | to `True` Return `numpy` array if `True`. `pandas.DataFrame` otherwise. The default is `True`. | **Returns**: | Type | Description | | -------------------------- | --------------------------- | | `tp.Array \| pd.DataFrame` | Probability density matrix. | #### `get_cross_tail_quantile_mask` ```python theme={null} get_cross_tail_quantile_mask( self, alpha: float = 0.9, truncate: float = 0.5, to_numpy: bool = True, ) ‑> pandas.core.frame.DataFrame | numpy.ndarray ``` Create a boolean mask to focus on tail regions of a probability density distribution. Compute the q-th quantile of the data. Masks values in `1 - alpha` quantile range of the PDF values. See `np.quantile` for more information. `u` and `v` are bivariate inputs `(u, v)` where each row represents a bivariate observation. In this context, `u` and `v` are evenly spaced numbers over \[start, stop, num] interval. **Parameters**: | Name | Type | Default | Description | | ---------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `alpha` | `float` | `s` | to `0.9` Lower quantile is found with `lower_quantile = np.quantile(pdfs, 1.0 - alpha)`, then removed from matrix. Defaults to `0.9`. | | `truncate` | `float` | `s` | to `0.5` Truncate filter at specific point. Ignored if None. Defaults to `0.5`. | | `to_numpy` | `bool` | `s` | to `True` Return `numpy` array if `True`. `pandas.DataFrame` otherwise. The default is `True`. | **Returns**: | Type | Description | | ---------------------------- | ---------------------------------------- | | `tp.Array2d \| pd.DataFrame` | Boolean array of same shape as `matrix`. | #### `get_cross_tail_triangle_mask` ```python theme={null} get_cross_tail_triangle_mask( self, lower_triangle: float = 0.5, upper_triangle: float = 0.5, to_numpy: bool = True, ) ‑> pandas.core.frame.DataFrame | numpy.ndarray ``` Create a boolean mask to focus on triangle regions of a probability density distribution. `u` and `v` are bivariate inputs `(u, v)` where each row represents a bivariate observation. In this context, `u` and `v` are evenly spaced numbers over \[start, stop, num] interval. **Parameters**: | Name | Type | Default | Description | | ---------------- | ------- | ------- | ---------------------------------------------------------------------------------------------- | | `lower_triangle` | `float` | `s` | to `0.5` Lower triangle coordinate point. Defaults to `0.5`. | | `upper_triangle` | `float` | `s` | to `0.5` Upper triangle coordinate point. Defaults to `0.5`. | | `to_numpy` | `bool` | `s` | to `True` Return `numpy` array if `True`. `pandas.DataFrame` otherwise. The default is `True`. | **Returns**: | Type | Description | | ---------------------------- | ---------------------------------------- | | `tp.Array2d \| pd.DataFrame` | Boolean array of same shape as `matrix`. | #### `cross_tail_mask` ```python theme={null} cross_tail_mask( self, mask_method: str = 'quantile', features: numpy.ndarray = None, **mask_method_kwargs, ) ‑> vectorbtpro.utils.figure.FigureWidget ``` Get cross-tail concentration mask. **Parameters**: | Name | Type | Default | Description | | -------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mask_method` | `str` | `--` | Type of mask to apply to the matrix. Options are: - 'quantile': Apply a quantile-based tail mask. - 'triangle': Apply a triangular mask. Defaults to `quantile`. | | `features` | `tp.Array2d` | `s` | to `None`. The array of the component values. Find linear space in the index array that correspond to adjusted values, then clip space to ensure they stay within bounds and apply mask only to valid indices. Useful to apply mask to array of ranked vectors. Defaults to `None`. | | `mask_method_kwargs` | `tp.Kwargs` | `--` | Tail mask key-word arguments. | **Returns**: | Type | Description | | ---------------------------- | ---------------------------------------- | | `tp.Array2d \| pd.DataFrame` | Boolean array of same shape as `matrix`. | #### `apply_cross_tail_concentration` ```python theme={null} apply_cross_tail_concentration( self, features: numpy.ndarray, mask_method: str = 'quantile', **mask_method_kwargs, ) ‑> vectorbtpro.utils.figure.FigureWidget ``` Apply cross-tail concentration mask. **Parameters**: | Name | Type | Default | Description | | -------------------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `features` | `tp.Array2d` | `--` | The array of the component values. | | `mask_method` | `str` | `--` | Type of mask to apply to the matrix. Options are: - 'quantile': Apply a quantile-based tail mask. - 'triangle': Apply a triangular mask. Defaults to `quantile`. | | `mask_method_kwargs` | `tp.Kwargs` | `--` | Mask key-word arguments. | **Returns**: | Type | Description | | ---------------------------- | --------------------------- | | `tp.Array2d \| pd.DataFrame` | Filtered scaled data array. | #### `plot_tail_concentration` ```python theme={null} plot_tail_concentration( self, u: numpy.ndarray = None, v: numpy.ndarray = None, title: str | None = None, smoothing: float | None = 1.3, ) ‑> vectorbtpro.utils.figure.Figure ``` Plot the tail concentration function. This method computes the tail concentration function at 100 evenly spaced quantile levels between 0.005 and 0.995. The plot displays the concentration values on the y-axis and the quantile levels on the x-axis. The tail concentration are estimated as: * Lower tail: $$ \delta_L(q) = P(U_2 ≤ q | U_1 ≤ q) $$ * Upper tail: $$ \delta_U(q) = P(U_2 ≥ q | U_1 ≥ q) $$ where $U_1$ and $U_2$ are the pseudo-observations of the first and second variables, respectively. **Parameters**: | Name | Type | Default | Description | | ----------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `u` | `Array1d` | `--` | The array of the first component values. If provided, it is used to plot the empirical tail concentration for comparison versus the model tail concentration. | | `v` | `Array1d` | `--` | The array of the second component values. If provided, it is used to plot the empirical tail concentration for comparison versus the model tail concentration. | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `smoothing` | `float` | `1.3` | Smoothing parameter for the spline line shape. If provided, the curves will be smoothed using a spline interpolation. | **Returns**: | Type | Description | | ----------------- | --------------------------------------------------------------- | | `fig : go.Figure` | A Plotly figure object containing the tail concentration curve. | #### `plot_ecdf` ```python theme={null} plot_ecdf( self, u: , v: , **layout_kwargs, ) ‑> vectorbtpro.utils.figure.FigureWidget ``` Plot the empirical cumulative distribution function (ECDF) surface. **Parameters**: | Name | Type | Default | Description | | --------------- | ----------- | ------- | ------------------------------------------------ | | `u` | `np.array` | `--` | The array of the first component values. | | `v` | `np.array` | `--` | The array of the second component values. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional arguments passed to the scatter plot. | **Returns**: | Type | Description | | ------------------ | --------------------------------------------------- | | `vbt.FigureWidget` | The figure containing the scatter plot of the ECDF. | #### `plot_heatmap` ```python theme={null} plot_heatmap( self, title: str | None = None, fig: plotly.basedatatypes.BaseFigure = None, **layout_kwargs, ) ‑> vectorbtpro.utils.figure.Figure ``` Plot a 2D heatmap contour of the estimated probability density function (PDF). This method generates a grid over `[0, 1]^2`, computes the PDF, and displays a contour plot of the PDF. Contour levels are limited to the 97th quantile to avoid extreme densities. **Parameters**: | Name | Type | Default | Description | | --------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `fig` | `tp.BaseFigure` | `None` | Existing figure to update. If None, a new figure is created. Defaults to `None`. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments for customizing the layout. | **Returns**: | Type | Description | | ----------------- | ----------------------------------------------------------------- | | `fig : go.Figure` | A Plotly figure object containing the 2D contour plot of the PDF. | #### `plot_surface` ```python theme={null} plot_surface( self, title: str | None = None, fig: plotly.basedatatypes.BaseFigure = None, **layout_kwargs, ) ‑> plotly.graph_objs._figure.Figure ``` Plot a 3D surface of the estimated probability density function (PDF). This method generates a grid over `[0, 1]^2`, computes the PDF, and displays a 3D surface plot of the PDF using Plotly. **Parameters**: | Name | Type | Default | Description | | --------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `fig` | `tp.BaseFigure` | `None` | Existing figure to update. If None, a new figure is created. Defaults to `None`. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments for customizing the layout. | **Returns**: | Type | Description | | ----------------- | --------------------------------------------------------------- | | `fig : go.Figure` | A Plotly figure object containing a 3D surface plot of the PDF. | #### `plot_contour` ```python theme={null} plot_contour( self, u: numpy.ndarray | pandas.core.series.Series | pandas.core.frame.DataFrame = None, v: numpy.ndarray | pandas.core.series.Series | pandas.core.frame.DataFrame = None, signals: systematica.signals.base.Signals | pandas.core.frame.DataFrame = None, select_signals: str = None, show_contour: bool = True, show_data: bool = True, show_latest_point: bool = False, show_points: Dict[str, int | pandas._libs.tslibs.timestamps.Timestamp] = None, mask_array: numpy.ndarray = None, alpha: float = 0.5, opacity: float = 0.2, title: str | None = None, showlegend: bool = True, fig: plotly.basedatatypes.BaseFigure = None, **layout_kwargs, ) ‑> vectorbtpro.utils.figure.Figure ``` Plot a 2D heatmap contour of the estimated probability density function (PDF). This method generates a grid over `[0, 1]^2`, computes the PDF, and displays a contour plot of the PDF. Contour levels are limited to the 97th quantile to avoid extreme densities. **Parameters**: | Name | Type | Default | Description | | ------------------- | ----------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | | `u` | `np.array` | `None` | The array of the first component values. Ignored it `None`. Defaults to `None`. | | `v` | `np.array` | `--` | The array of the second component values. Ignored it `None`. Defaults to `None`. | | `signals` | `Signals` | `None` | Signal namedtuple object. Array should be the same size as `u` and `v`. | | `select_signals` | `tp.Literal[VALID_SIGNALS]` | `None` | Filter `Signals` by a signal (e.g. `long_entries`). If None, It is ignored. Defaults to `None`. | | `show_contour` | `bool` | `True` | Show contour if `True`. Defaults to `True`. | | `show_data` | `bool` | `True` | If `True`, display selected data. Defaults to `True`. | | `show_latest_point` | `bool, Default `True\`\` | `--` | If True, show latest values as red dot. Defaults to True. | | `show_points` | `tp.Dict[str, int \| pd.Timestamp], Default `None\`\` | `--` | Show selected color and values mapping. Ignored if None. Defauts to None. | | `mask_array` | `tp.Array2d` | `--` | Boolean mask to focus on specific regions of a probability density distribution. Applied to `u` and `v`. Defaults to None. | | `alpha` | `float` | `0.5` | Contour alpha size. Defaults to `0.5`. | | `opacity` | `float` | `0.2` | Point opacity. Defaults to `0.2`. | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `showlegend` | `bool` | `True` | Show legend. Defaults to `True`. | | `fig` | `tp.BaseFigure` | `None` | Existing figure to update. If None, a new figure is created. Defaults to `None`. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments for customizing the layout. | **Returns**: | Type | Description | | ----------------- | ----------------------------------------------------------------- | | `fig : go.Figure` | A Plotly figure object containing the 2D contour plot of the PDF. | #### `plot_ellipse` ```python theme={null} plot_ellipse( self, u: numpy.ndarray | pandas.core.series.Series | pandas.core.frame.DataFrame, v: numpy.ndarray | pandas.core.series.Series | pandas.core.frame.DataFrame, std: float | List[float] = None, show_data: bool = True, opacity: float = 0.2, title: str | None = None, showlegend: bool = True, fig: plotly.basedatatypes.BaseFigure = None, **layout_kwargs, ) ‑> vectorbtpro.utils.figure.Figure ``` Plot an ellipse based on the covariance matrix of a 2D dataset. **Parameters**: | Name | Type | Default | Description | | --------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `arr` | `tp.Array2d` | `--` | Input data of shape (n\_samples, 2) representing the 2D points. | | `std` | `float` | `2.0` | Standard deviation threshold(s) defining the size of the ellipse (e.g., 2 for \~95% confidence). If None, threshold are 0.5, 1, 1.5 std from the mean. Defaults to None. | | `show_data` | `bool` | `True` | If `True`, display selected data. Defaults to `True`. | | `opacity` | `float` | `0.2` | Point opacity. Defaults to `0.2`. | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `showlegend` | `bool` | `True` | Show legend. Defaults to `True`. | | `fig` | `tp.BaseFigure` | `None` | Existing figure to update. If None, a new figure is created. Defaults to `None`. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments for customizing the layout. | **Returns**: | Type | Description | | ------------------ | -------------------------- | | `vbt.FigureWidget` | Scatter plot with ellipse. | #### `plot_density` ```python theme={null} plot_density( self, mask_method: Literal['qth', 'tri', None] = None, mask_method_kwargs: Dict[str, Any] = None, features: numpy.ndarray = None, opacity: float = 0.8, title: str | None = None, showlegend: bool = True, fig: plotly.basedatatypes.BaseFigure = None, **layout_kwargs, ) ‑> vectorbtpro.utils.figure.FigureWidget ``` Plot probability density matrix. **Parameters**: | Name | Type | Default | Description | | -------------------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mask_method` | `str` | `--` | Type of mask to apply to the matrix. Options are: - 'qth': Apply a quantile-based tail mask. - 'tri': Apply a triangular mask. - `None`: No mask applied. Defaults to None. | | `mask_method_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments passed to the mask functions. | | `features` | `tp.Array2d` | `--` | Input data of shape (n\_samples, 2) representing the 2D points. | | `opacity` | `float` | `0.8` | Point opacity. Defaults to `0.8`. | | `title` | `str` | `None` | The title for the plot. If not provided, a default title based on the fitted copula's representation is used. | | `showlegend` | `bool` | `True` | Show legend. Defaults to `True`. | | `fig` | `tp.BaseFigure` | `None` | Existing figure to update. If None, a new figure is created. Defaults to `None`. | | `layout_kwargs` | `tp.Kwargs` | `--` | Additional keyword arguments for customizing the layout. | **Returns**: | Type | Description | | ------------------ | ------------ | | `vbt.FigureWidget` | Matrix plot. | **Raises**: | Type | Description | | --------------- | -------------------------- | | `RuntimeError:` | Failed to generate heatmap |