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

# Gumbel

> systematica.models.arbitrage_index.gumbel

## `Gumbel`

```python theme={null}
Gumbel(
    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 Gumbel Copula Estimation.

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

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

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.

Gumbel copula generally exhibits weaker upper tail dependence than the Joe
copula.

It is defined by:

$$
C_{\theta}(u, v) = \exp\Bigl(-\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{1/\theta}\Bigr)
$$

where $\theta \ge 1$ is the dependence parameter. When $\theta = 1$,
the Gumbel copula reduces to the independence copula. Larger values of
$\theta$ result in stronger upper-tail dependence.

<Note>
  The Gumbel copula is a widely used copula in statistics and quantitative
  finance, particularly for modeling **upper-tail dependence** , which
  captures the likelihood of extreme high values occurring simultaneously in
  two or more random variables. The **conditional probability formulas**\
  derived from the Gumbel copula describe the relationship between two
  dependent random variables $U$ and $V$ (uniform marginals).

  1. **Upper-Tail Dependence** : The Gumbel copula is ideal for scenarios
     where variables exhibit strong upper-tail dependence, such as extreme
     co-movements in financial markets.

  2. **Risk Management** : Used for modeling dependencies in extreme events
     like catastrophic losses in insurance or simultaneous stock crashes.

  3. **Joint Probabilities** : Helps compute joint or conditional probabilities
     for events involving highly correlated variables.
</Note>

Rotations are needed for Archimedean copulas (e.g., Joe, Gumbel, Gumbel)
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.

**References**:

* "An Introduction to Copulas (2nd ed.)", Nelsen (2006)
* "Multivariate Models and Dependence Concepts",  Joe, Chapman & Hall (1997)
* "Quantitative Risk Management: Concepts, Techniques and Tools", McNeil, Frey & Embrechts (2005)
* "The t Copula and Related Copulas", Demarta & McNeil (2005)
* "Copula Methods in Finance", Cherubini, Luciano & Vecchiato (2004)

Method generated by attrs for class Gumbel.

### 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              |
| ------- | ------------------------ |
| `float` | Log probability density. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | Gumbel dependence (theta) must be >= 1. |

#### `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 probability density. |

**Raises**:

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `AssertionError` | Gumbel dependence (theta) must be >= 1. |

#### `arbitrage`

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

Compute the h-function (partial derivative) for the bivariate Gumbel
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` | Gumbel dependence (theta) must be >= 1. |

#### `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 Gumbel
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` | Gumbel dependence (theta) must be >= 1. |

#### `score`

```python theme={null}
score(
    self,
    u: numpy.ndarray,
    v: numpy.ndarray,
) ‑> 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. |

**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` | Gumbel dependence (theta) must be >= 1. |