Base

systematica.models.arbitrage_index.base

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

• 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

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) \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

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:

• 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

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:

• 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

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