Utils

systematica.models.arbitrage_index.utils

get_best_copula_rotation

get_best_copula_rotation(
    u: numpy.ndarray,
    v: numpy.ndarray,
    func_nb: Callable,
    theta: float,
) ‑> systematica.models.arbitrage_index.utils.BaseCopulaRotation

Select the optimal copula rotation based on a provided function.

This helper function applies each rotation defined in BaseCopulaRotation to the data u and v, computes a criterion value using the provided function which takes u, v and theta as arguments-and returns the rotation that minimizes this value.

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.
func_nb	Callable	--	A numba compiled function that computes a criterion (e.g., a negative log-likelihood) for a given rotated dataset and copula parameter theta.
theta	float	--	The estimated copula parameter.

Returns:

Type	Description
BaseCopulaRotation	The rotation (an element of BaseCopulaRotation) that minimizes the criterion value.

Note:

Equivalent to:

>>> results = {}
>>> for rotation in BaseCopulaRotation:
...     ur, vr = apply_copula_rotation_nb(u, v, rotation)
...     results[rotation] = func_nb(theta=theta, u=ur, v=vr)
>>> best_rotation = min(results, key=results.get)
>>> return best_rotation

apply_copula_rotation_nb

apply_copula_rotation_nb(
    u: numpy.ndarray,
    v: numpy.ndarray,
    rotation: int,
) ‑> Tuple[numpy.ndarray, numpy.ndarray]

Apply a bivariate copula rotation using the standard (clockwise) convention.

The transformations are defined as follows:

• BaseCopulaRotation.R0 (0°): $(u, v) \mapsto (u, v)$
• BaseCopulaRotation.R90 (90°): $(u, v) \mapsto (v, 1 - u)$
• BaseCopulaRotation.R180 (180°): $(u, v) \mapsto (1 - u, 1 - v)$
• BaseCopulaRotation.R270 (270°): $(u, v) \mapsto (1 - v, 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.
rotation	int	--	The rotation to apply to the copula.

Returns:

Type	Description
tp.Tuple[tp.Array1d, tp.Array1d]	The rotated u and v arrays.

apply_cumulative_density_rotation_nb

apply_cumulative_density_rotation_nb(
    u: numpy.ndarray,
    v: numpy.ndarray,
    cum_density: numpy.ndarray,
    rotation: int,
) ‑> Tuple[numpy.ndarray, numpy.ndarray]

Apply a copula rotation to u and v and compute the corresponding cumulative density values.

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.
cum_density	tp.Array1d	--	Cumulative density.
rotation	int	--	The rotation to apply.

Returns:

Type	Description
tp.Array1d	The transformed cumulative density values after applying the rotation.

apply_partial_derivatives_rotation_nb

apply_partial_derivatives_rotation_nb(
    arbitrage: numpy.ndarray,
    rotation: int,
) ‑> numpy.ndarray

Apply a copula rotation to u and v and compute the corresponding partial derivatives.

Parameters:

Name	Type	Default	Description
arbitrage	tp.Array2d	--	The mispricing indices for the copula, a.k.a. arbitrage.
rotation	int	--	The rotation to apply.

Returns:

Type	Description
tp.Array2d	The transformed partial derivative values after applying the rotation.

apply_truncate_rotation_nb

apply_truncate_rotation_nb(
    u: numpy.ndarray,
    v: numpy.ndarray,
    rotation: int,
    truncate: float,
) ‑> numpy.ndarray

Apply a copula rotation to truncate mask.

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.
rotation	int	--	The rotation to apply.
truncate	float	--	Truncate filter at specific point.

Returns:

Type	Description
tp.Array2d	boolean mask to focus on tail regions of a probability density distribution.

Raises:

Type	Description
AssertionError	Truncate must be in the range [0, 1].

apply_triangle_rotation_nb

apply_triangle_rotation_nb(
    mask: numpy.ndarray,
    lower_triangle: float,
    upper_triangle: float,
    rotation: int,
) ‑> numpy.ndarray

Apply a copula rotation to truncate mask.

Parameters:

Name	Type	Default	Description
mask	tp.Array2d	--	Probability density matrix mask.
lower_triangle	int	--	Lower coordinate point.
upper_triangle	int	--	Upper coordinate point.
rotation	int	--	The rotation to apply.

Returns:

Type	Description
tp.Array2d	boolean mask to focus on triangle regions of a probability density distribution.

Raises:

Type	Description
AssertionError	Lower and upper must be in the range [0, 1].

BaseCopulaRotation

BaseCopulaRotation(
    *args,
    **kwds,
)

Rotation (in degrees) to apply to a bivariate copula.

Ancestors

• enum.Enum

Class variables

• R0: int: No rotation (0°) $(u, v) \mapsto (u, v)$.

• R90: int: 90° rotation $(u, v) \mapsto (v, 1 - u)$.

• R180: int: 180° rotation $(u, v) \mapsto (1 - u, 1 - v)$.

• R270: int: 270° rotation $(u, v) \mapsto (1 - v, u)$.