BaseCopula
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
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
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
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
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) 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
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
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
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
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
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
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
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
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:
λL(q)=P(U2≤q∣U1≤q)
λU(q)=P(U2≥q∣U1≥q)
where U1 and U2 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
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
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
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
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
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
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
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:
δL(q)=P(U2≤q∣U1≤q)
δU(q)=P(U2≥q∣U1≥q)
where U1 and U2 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
plot_ecdf(
self,
u: <built-in function array>,
v: <built-in function array>,
**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
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
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
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
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
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 |