Skip to main content

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:
NameTypeDefaultDescription
utp.Array1d--First uniform marginal.
vtp.Array1d--Second uniform marginal.
Returns:
TypeDescription
tp.Array1dLog 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)P(U<=u, V<=v) Parameters:
NameTypeDefaultDescription
utp.Array1d--First uniform marginal.
vtp.Array1d--Second uniform marginal.
Returns:
TypeDescription
tp.Array1dCumulative 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<uV=v) and P(V<vU=u).P(U < u | V = v) \text{ and } P(V < v | U = u). Parameters:
NameTypeDefaultDescription
utp.Array1d--The first component of the bivariate input.
vtp.Array1d--The second component of the bivariate input.
Returns:
TypeDescription
tp.Array2dThe 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:
NameTypeDefaultDescription
utp.Array1d--The first component of the bivariate input.
vtp.Array1d--The second component of the bivariate input.
Returns:
TypeDescription
tp.Array2dThe 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:
NameTypeDefaultDescription
utp.Array1d--The first component of the bivariate input.
vtp.Array1d--The second component of the bivariate input.
Returns:
TypeDescription
tp.Array1dThe 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:
TypeDescription
tp.Array2dProbability density function (PDF).

set_rotation

set_rotation(
    self,
    u: numpy.ndarray,
    v: numpy.ndarray,
) ‑> Self
Set rotation. Parameters:
NameTypeDefaultDescription
utp.Array1d--First uniform marginal.
vtp.Array1d--Second uniform marginal.
Returns:
TypeDescription
tp.SelfCopula 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:
NameTypeDefaultDescription
utp.Array1d--First uniform marginal.
vtp.Array1d--Second uniform marginal.
Returns:
TypeDescription
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:
NameTypeDefaultDescription
uArray1d--The array of the first component values.
vArray1d--The array of the second component values.
model_validation_methodstraicThe method to use for the criterion calculation. Defaults to “aic”.
Returns:
TypeDescription
floatThe criterion value for the model, or NaN if score cannot be computed.
Raises:
TypeDescription
ValueErrorIf 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 q0.5q ≤ 0.5: C(q)=P(Uq,Vq)/qC(q) = P(U ≤ q, V ≤ q) / q
  • For quantiles q>0.5q > 0.5: C(q)=(12q+P(Uq,Vq))/(1q)C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)
where UU and VV are the pseudo-observations of the first and second variables, respectively. This function returns the concentration values for each qq provided. References:
  • “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)
Parameters:
NameTypeDefaultDescription
u_or_vtp.Array1d--A 1D array of quantile levels (values between 0 and 1) at which to compute the tail concentration.
Raises:
TypeDescription
ValueErrorIf any value in quantiles is not in the interval [0, 1].
Returns:
TypeDescription
tp.Array1dThe 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:
λL(q)=P(U2qU1q)\lambda_L(q) = P(U_2 ≤ q | U_1 ≤ q)
  • Upper tail:
λU(q)=P(U2qU1q)\lambda_U(q) = P(U_2 ≥ q | U_1 ≥ q) where U1U_1 and U2U_2 are the pseudo-observations. Parameters:
NameTypeDefaultDescription
utp.Array1d--The array of the first component values.
vtp.Array1d--The array of the second component values.
quantilestp.Array1d--A 1D array of quantile levels (values between 0 and 1) at which to compute the concentration.
Raises:
TypeDescription
ValueErrorIf X is not a 2D array with exactly 2 columns or if quantiles are not in [0, 1].
Returns:
TypeDescription
tp.Array1dAn 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:
NameTypeDefaultDescription
to_numpyboolsto True Return numpy array if True. pandas.DataFrame otherwise. The default is True.
Returns:
TypeDescription
tp.Array | pd.DataFrameProbability density matrix.

partial_derivative_matrix

partial_derivative_matrix(
    self,
    to_numpy: bool = True,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray
Create partial derivative matrix. Parameters:
NameTypeDefaultDescription
to_numpyboolsto True Return numpy array if True. pandas.DataFrame otherwise. The default is True.
Returns:
TypeDescription
tp.Array | pd.DataFrameProbability 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:
NameTypeDefaultDescription
alphafloatsto 0.9 Lower quantile is found with lower_quantile = np.quantile(pdfs, 1.0 - alpha), then removed from matrix. Defaults to 0.9.
truncatefloatsto 0.5 Truncate filter at specific point. Ignored if None. Defaults to 0.5.
to_numpyboolsto True Return numpy array if True. pandas.DataFrame otherwise. The default is True.
Returns:
TypeDescription
tp.Array2d | pd.DataFrameBoolean 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:
NameTypeDefaultDescription
lower_trianglefloatsto 0.5 Lower triangle coordinate point. Defaults to 0.5.
upper_trianglefloatsto 0.5 Upper triangle coordinate point. Defaults to 0.5.
to_numpyboolsto True Return numpy array if True. pandas.DataFrame otherwise. The default is True.
Returns:
TypeDescription
tp.Array2d | pd.DataFrameBoolean 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:
NameTypeDefaultDescription
mask_methodstr--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.
featurestp.Array2dsto 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_kwargstp.Kwargs--Tail mask key-word arguments.
Returns:
TypeDescription
tp.Array2d | pd.DataFrameBoolean 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:
NameTypeDefaultDescription
featurestp.Array2d--The array of the component values.
mask_methodstr--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_kwargstp.Kwargs--Mask key-word arguments.
Returns:
TypeDescription
tp.Array2d | pd.DataFrameFiltered 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:
δL(q)=P(U2qU1q)\delta_L(q) = P(U_2 ≤ q | U_1 ≤ q)
  • Upper tail:
δU(q)=P(U2qU1q)\delta_U(q) = P(U_2 ≥ q | U_1 ≥ q) where U1U_1 and U2U_2 are the pseudo-observations of the first and second variables, respectively. Parameters:
NameTypeDefaultDescription
uArray1d--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.
vArray1d--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.
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
smoothingfloat1.3Smoothing parameter for the spline line shape. If provided, the curves will be smoothed using a spline interpolation.
Returns:
TypeDescription
fig : go.FigureA 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:
NameTypeDefaultDescription
unp.array--The array of the first component values.
vnp.array--The array of the second component values.
layout_kwargstp.Kwargs--Additional arguments passed to the scatter plot.
Returns:
TypeDescription
vbt.FigureWidgetThe 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:
NameTypeDefaultDescription
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
figtp.BaseFigureNoneExisting figure to update. If None, a new figure is created. Defaults to None.
layout_kwargstp.Kwargs--Additional keyword arguments for customizing the layout.
Returns:
TypeDescription
fig : go.FigureA 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:
NameTypeDefaultDescription
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
figtp.BaseFigureNoneExisting figure to update. If None, a new figure is created. Defaults to None.
layout_kwargstp.Kwargs--Additional keyword arguments for customizing the layout.
Returns:
TypeDescription
fig : go.FigureA 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[strint | 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:
NameTypeDefaultDescription
unp.arrayNoneThe array of the first component values. Ignored it None. Defaults to None.
vnp.array--The array of the second component values. Ignored it None. Defaults to None.
signalsSignalsNoneSignal namedtuple object. Array should be the same size as u and v.
select_signalstp.Literal[VALID_SIGNALS]NoneFilter Signals by a signal (e.g. long_entries). If None, It is ignored. Defaults to None.
show_contourboolTrueShow contour if True. Defaults to True.
show_databoolTrueIf True, display selected data. Defaults to True.
show_latest_pointbool, Default True“--If True, show latest values as red dot. Defaults to True.
show_pointstp.Dict[str, int | pd.Timestamp], Default None“--Show selected color and values mapping. Ignored if None. Defauts to None.
mask_arraytp.Array2d--Boolean mask to focus on specific regions of a probability density distribution. Applied to u and v. Defaults to None.
alphafloat0.5Contour alpha size. Defaults to 0.5.
opacityfloat0.2Point opacity. Defaults to 0.2.
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
showlegendboolTrueShow legend. Defaults to True.
figtp.BaseFigureNoneExisting figure to update. If None, a new figure is created. Defaults to None.
layout_kwargstp.Kwargs--Additional keyword arguments for customizing the layout.
Returns:
TypeDescription
fig : go.FigureA 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:
NameTypeDefaultDescription
arrtp.Array2d--Input data of shape (n_samples, 2) representing the 2D points.
stdfloat2.0Standard 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_databoolTrueIf True, display selected data. Defaults to True.
opacityfloat0.2Point opacity. Defaults to 0.2.
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
showlegendboolTrueShow legend. Defaults to True.
figtp.BaseFigureNoneExisting figure to update. If None, a new figure is created. Defaults to None.
layout_kwargstp.Kwargs--Additional keyword arguments for customizing the layout.
Returns:
TypeDescription
vbt.FigureWidgetScatter 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:
NameTypeDefaultDescription
mask_methodstr--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_kwargstp.Kwargs--Additional keyword arguments passed to the mask functions.
featurestp.Array2d--Input data of shape (n_samples, 2) representing the 2D points.
opacityfloat0.8Point opacity. Defaults to 0.8.
titlestrNoneThe title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
showlegendboolTrueShow legend. Defaults to True.
figtp.BaseFigureNoneExisting figure to update. If None, a new figure is created. Defaults to None.
layout_kwargstp.Kwargs--Additional keyword arguments for customizing the layout.
Returns:
TypeDescription
vbt.FigureWidgetMatrix plot.
Raises:
TypeDescription
RuntimeError:Failed to generate heatmap