# `TAlib.Indicators.ATR`
[🔗](https://github.com/benyblack/talib/blob/main/lib/indicators/atr.ex#L1)

Average True Range [Wikipedia](https://en.wikipedia.org/wiki/Average_true_range).

The True Range of a bar is `max(high - low, |high - prev_close|,
|low - prev_close|)` (just `high - low` for the first bar). ATR is
Wilder's smoothed average (RMA) of the True Range series, seeded with
the SMA of the first `period` True Ranges — the standard TA-Lib
convention.

Bars are maps with at least `:high`, `:low` and `:close`; extra keys
are ignored. See `TAlib` for the remaining conventions: chronological
order, oldest first, series aligned with the input, `nil` when there is
not enough data.

# `atr`

```elixir
@spec atr([map()], pos_integer()) :: float() | nil
```

Calculate the latest Average True Range.

## Parameters

  - bars: list of bars, oldest first.
  - period: lookback window, a positive integer (default 14).

## Examples

    iex> bars = [
    ...>   %{high: 12, low: 8, close: 10},
    ...>   %{high: 11, low: 9, close: 10},
    ...>   %{high: 13, low: 9, close: 12}
    ...> ]
    iex> TAlib.Indicators.ATR.atr(bars, 2)
    3.0

# `atr_list`

```elixir
@spec atr_list([map()], pos_integer()) :: [float() | nil]
```

Calculate the full ATR series.

Returns a list aligned with `bars`: the first `period - 1` entries are
`nil`, and every later entry is the Wilder-smoothed average of the True
Ranges as of that point.

## Parameters

  - bars: list of bars, oldest first.
  - period: lookback window, a positive integer (default 14).

## Examples

    iex> bars = [
    ...>   %{high: 12, low: 8, close: 10},
    ...>   %{high: 11, low: 9, close: 10},
    ...>   %{high: 13, low: 9, close: 12}
    ...> ]
    iex> TAlib.Indicators.ATR.atr_list(bars, 2)
    [nil, nil, 3.0]

# `init`

```elixir
@spec init([map()], pos_integer()) ::
  {TAlib.Indicators.ATR.State.t(), [float() | nil]}
```

Warm up streaming ATR state from `history`.

Returns `{state, values}` with `values` the full ATR series of
`history` (identical to `atr_list/2`), and `state` ready to continue
it one bar at a time in O(1) via `next/2`. History needs at least
`period + 1` bars.

## Examples

    iex> bars = [
    ...>   %{high: 12, low: 8, close: 10},
    ...>   %{high: 11, low: 9, close: 10},
    ...>   %{high: 13, low: 9, close: 12}
    ...> ]
    iex> {state, values} = TAlib.Indicators.ATR.init(bars, 2)
    iex> values
    [nil, nil, 3.0]
    iex> {_state, 3.5} = TAlib.Indicators.ATR.next(state, %{high: 14, low: 10, close: 11})

# `natr`

```elixir
@spec natr([map()], pos_integer()) :: float() | nil
```

The Normalized ATR: `ATR / close * 100`, in percent.

    iex> bars = [
    ...>   %{high: 12, low: 8, close: 10},
    ...>   %{high: 11, low: 9, close: 10},
    ...>   %{high: 13, low: 9, close: 12}
    ...> ]
    iex> TAlib.Indicators.ATR.natr(bars, 2) |> Float.round(4)
    25.0

# `next`

```elixir
@spec next(TAlib.Indicators.ATR.State.t(), map()) ::
  {TAlib.Indicators.ATR.State.t(), float() | nil}
```

Advance streaming ATR state by one bar (a map with at least `:high`,
`:low` and `:close`), in O(1).

    iex> {state, _} = TAlib.Indicators.ATR.init([%{high: 12, low: 8, close: 10}, %{high: 11, low: 9, close: 10}, %{high: 13, low: 9, close: 12}], 2)
    iex> {_state, value} = TAlib.Indicators.ATR.next(state, %{high: 14, low: 10, close: 11})
    iex> value
    3.5

# `true_range`

```elixir
@spec true_range([map()]) :: [number()]
```

The True Range of every bar: `max(high - low, |high - prev_close|,
|low - prev_close|)` (`high - low` for the first bar).

    iex> bars = [
    ...>   %{high: 12, low: 8, close: 10},
    ...>   %{high: 11, low: 9, close: 10},
    ...>   %{high: 13, low: 9, close: 12}
    ...> ]
    iex> TAlib.Indicators.ATR.true_range(bars)
    [4, 2, 4]

---

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