# `ZenQuant.Helpers.Risk`
[🔗](https://github.com/ZenHive/zen_quant/blob/v0.8.1/lib/zen_quant/helpers/risk.ex#L1)

Risk calculation helpers for position analysis.

Pure functions for calculating margin headroom and liquidation distance
from position data. Works with plain maps containing `:mark_price` and
`:liquidation_price` keys.

## Example

    position = %{
      mark_price: 50_000.0,
      liquidation_price: 40_000.0
    }

    ZenQuant.Helpers.Risk.margin_headroom(position)
    # => 0.2 (20% headroom)

    ZenQuant.Helpers.Risk.liquidation_distance(position)
    # => 10_000.0 (absolute price distance)

# `liquidation_distance`

```elixir
@spec liquidation_distance(map()) :: float() | nil
```

Calculates the absolute price distance to liquidation.

Returns `abs(mark_price - liquidation_price)`.

Returns `nil` if either `mark_price` or `liquidation_price` is nil.

## Examples

    iex> ZenQuant.Helpers.Risk.liquidation_distance(%{mark_price: 50_000.0, liquidation_price: 40_000.0})
    10_000.0

    iex> ZenQuant.Helpers.Risk.liquidation_distance(%{mark_price: 50_000.0, liquidation_price: nil})
    nil

# `margin_headroom`

```elixir
@spec margin_headroom(map()) :: float() | nil
```

Calculates margin headroom as a percentage.

Returns the distance between mark price and liquidation price as a
percentage of the mark price: `abs(mark - liq) / mark`.

Returns `nil` if either `mark_price` or `liquidation_price` is nil.

## Examples

    iex> ZenQuant.Helpers.Risk.margin_headroom(%{mark_price: 50_000.0, liquidation_price: 40_000.0})
    0.2

    iex> ZenQuant.Helpers.Risk.margin_headroom(%{mark_price: nil, liquidation_price: 40_000.0})
    nil

---

*Consult [api-reference.md](api-reference.md) for complete listing*