> ## 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.

# Utils

> systematica.models.arbitrage_index.utils

## `get_best_copula_rotation`

```python theme={null}
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:

```python theme={null}
>>> 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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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)$.