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

# Frank

> systematica.models.arbitrage_index.frank

## `Frank`

```python theme={null}
Frank(
    kendall_tau: float,
    rotation: str | systematica.models.arbitrage_index.utils.BaseCopulaRotation = BaseCopulaRotation.R0,
    start: float = 0.001,
    stop: float = 0.999,
    num: int = 100,
)
```

Bivariate Clayton Copula Estimation.

The Clayton copula is an Archimedean copula characterized by strong lower
tail dependence and little to no upper tail dependence.

In its unrotated form, it is used for modeling extreme co-movements in the
lower tail (i.e. simultaneous extreme losses).

Rotations allow the copula to be adapted for different types of tail
dependence:

* A `180` rotation captures extreme co-movements in the upper tail (i.e.
  simultaneous extreme gains).
* A `90` rotation captures scenarios where one variable exhibits extreme
  gains
  while the other shows extreme losses.
* A `270` rotation captures the opposite scenario, where one variable
  experiences extreme losses while the other suffers extreme gains.

<Note>
  The Frank copula is a widely used copula in statistics and finance for
  modeling dependencies between random variables. The Frank copula captures
  symmetric dependence and is particularly useful when there is no tail
  dependence.

  1. **Symmetric Dependency** : The Frank copula is suitable for datasets
     where dependency between variables is symmetric and without tail dependence.

  2. **Modeling Joint Distributions** : Used in scenarios where the relationship
     between random variables is non-linear but consistent across their range.

  3. **Risk Management and Finance** : It can model dependencies between
     financial assets, insurance claims, or other risk variables with moderate
     dependencies.
</Note>

Rotations are needed for Archimedean copulas (e.g., Joe, Gumbel, Clayton)
because their parameters only model positive dependence, and they exhibit
asymmetric tail behavior. To model negative dependence, one uses rotations
to "flip" the copula's tail dependence.

Method generated by attrs for class Frank.

### Ancestors

* `systematica.models.arbitrage_index.base.BaseCopula`
* `abc.ABC`

### Instance variables

* `lower_tail_dependence: float`: Theoretical lower tail dependence coefficient.

* `upper_tail_dependence: float`: Theoretical upper tail dependence coefficient.

### Methods

#### `density`

```python theme={null}
density(
    self,
    u: numpy.ndarray,
    v: numpy.ndarray,
) ‑> numpy.ndarray
```

Calculate log probability 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` | Log probability density. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | Frank dependence (theta) must not be 0. |

#### `cumulative_density`

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

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | Frank dependence (theta) must not be 0. |

#### `arbitrage`

```python theme={null}
arbitrage(
    self,
    ui: float,
    vi: float,
) ‑> Tuple[float, float]
```

Compute the h-function (partial derivative) for the bivariate Frank
copula, a.k.a. the mispricing index, for every time step in the trading
period using the estimated copula.

**Parameters**:

| Name | Type    | Default | Description                                  |
| ---- | ------- | ------- | -------------------------------------------- |
| `ui` | `float` | `--`    | The first component of the bivariate input.  |
| `vi` | `float` | `--`    | The second component of the bivariate input. |

**Returns**:

| Type                      | Description                                              |
| ------------------------- | -------------------------------------------------------- |
| `tp.Tuple[float, float]:` | The mispricing indices for the copula, a.k.a. arbitrage. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | Frank dependence (theta) must not be 0. |

#### `partial_derivative`

```python theme={null}
partial_derivative(
    self,
    u: numpy.ndarray,
    v: numpy.ndarray,
) ‑> numpy.ndarray
```

Compute the h-function (partial derivative) for the bivariate Frank
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. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | u and v must have the same shape.       |
| `AssertionError` | Frank dependence (theta) must not be 0. |

#### `score`

```python theme={null}
score(
    self,
    u: numpy.ndarray,
    v: numpy.ndarray,
    best_fit: bool = False,
) ‑> numpy.ndarray
```

Compute the log-likelihood score of each sample (log-pdf) under the
model.

<Note>
  `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.
</Note>

**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.   |
| `best_fit` | `bool`       | `False` | Apply best fitted rotation. Defaults to False. |

**Returns**:

| Type         | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `tp.Array1d` | The log-likelihood score of each sample under the fitted copula. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | u and v must have the same shape.       |
| `AssertionError` | Frank dependence (theta) must not be 0. |