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

# Joe

> systematica.models.arbitrage_index.joe

## `Joe`

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

The Joe 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.

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

It is defined by:

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

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

<Note>
  The **Joe copula**  is a popular tool in statistics and quantitative finance
  for modeling dependencies between random variables, particularly when
  capturing **upper-tail dependence** . In many real-world scenarios—such as
  financial market stress or simultaneous extreme losses in risk management—the
  likelihood of very high outcomes occurring together is of central concern.
  The Joe copula's conditional probability formulas help quantify this joint
  behavior between two dependent random variables $U$ and $V$ (with
  uniform marginals).

  1. **Upper-Tail Dependence** :
     The Joe copula is specifically designed to capture strong upper-tail
     dependence. This means it excels at modeling situations where extreme high
     values in one variable are likely to be accompanied by extreme high values
     in another. This property is crucial for understanding joint extreme events.

  2. **Risk Management** :
     In the context of risk management, the Joe copula is used to assess the
     probability of simultaneous extreme events, such as large losses in
     multiple assets or catastrophic insurance claims. By accurately modeling
     the dependence in the upper tail, risk managers can better estimate the
     likelihood of coinciding adverse outcomes and design more robust mitigation
     strategies.

  3. **Joint and Conditional Probabilities** :
     The Joe copula provides a framework for computing joint and conditional
     probabilities of extreme events. The conditional probability formulas
     derived from the Joe copula allow analysts to determine, for example, the
     probability that one variable will take on a high value given that another
     variable is already in the extreme region. This information is vital for
     stress testing and scenario analysis in both finance and insurance.
</Note>

Rotation 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 Joe.

### Ancestors

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

### Instance variables

* `lower_tail_dependence: float`: Theoretical lower tail dependence coefficient.  The Joe copula has no lower tail dependence in its unrotated form.

* `upper_tail_dependence: float`: Theoretical upper tail dependence coefficient.  The Joe copula has upper tail dependence in its unrotated form.

### 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` | Joe Kendall's tau must be in (0, 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 density. |

**Raises**:

| Type             | Description                          |
| ---------------- | ------------------------------------ |
| `AssertionError` | Joe Kendall's tau must be in (0, 1). |

#### `arbitrage`

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

Compute the h-function (partial derivative) for the bivariate Joe
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` | Joe Kendall's tau must be in (0, 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 Joe
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` | Joe Kendall's tau must be in (0, 1). |

#### `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` | Joe Kendall's tau must be in (0, 1). |