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

MACD indicator [Wikipedia](https://en.wikipedia.org/wiki/MACD).

Calculates the MACD line, the signal line and the histogram. See `TAlib`
for the input conventions: prices are always given in chronological
order, oldest first. Every function returns `nil` when there is not
enough data.

The MACD line at a point is defined once `max(fast, slow)` prices have
been seen, but — keeping the behavior of earlier releases — the scalar
functions require twice that much history (and `macd_all/4` derives its
guards from the same rule) so that the EMA seed has had time to wash out.

# `histogram`

```elixir
@spec histogram([number()], pos_integer(), pos_integer(), pos_integer()) ::
  float() | nil
```

Calculate the latest MACD histogram value: MACD line minus signal line.

## Parameters

  - prices: list of prices, oldest first.
  - macd_fast: fast EMA period of the MACD line (default 12).
  - macd_slow: slow EMA period of the MACD line (default 26).
  - signal_period: EMA period of the signal line (default 9).

## Examples

    iex> TAlib.Indicators.MACD.histogram([5, 1, 6, 4, 7, 3, 8, 2, 9], 3, 2, 2) |> Float.round(4)
    0.316

# `init`

```elixir
@spec init([number()], pos_integer(), pos_integer(), pos_integer()) ::
  {TAlib.Indicators.MACD.State.t(),
   %{macd: [float() | nil], signal: [float() | nil], histogram: [float() | nil]}}
```

Warm up streaming MACD state from `history`.

Returns `{state, values}` where `values` carries the three aligned
series — `%{macd: , signal: , histogram: }` — of `history`: the MACD
line equals `macd_list/3`, and the signal line is the whole-series
EMA of it (the `macd_fix/4` convention). `state` continues all three
one price at a time in O(1) via `next/2`.

## Examples

    iex> {state, values} = TAlib.Indicators.MACD.init([5, 1, 6, 4, 7, 3, 8, 2, 9], 3, 2, 2)
    iex> List.last(values.macd) |> Float.round(4)
    0.6532
    iex> {_state, %{macd: m, signal: s, histogram: h}} = TAlib.Indicators.MACD.next(state, 7)
    iex> {Float.round(m, 4), Float.round(s, 4), Float.round(h, 4)}
    {0.2959, 0.3165, -0.0206}

# `macd`

```elixir
@spec macd([number()], pos_integer(), pos_integer()) :: float() | nil
```

Calculate the latest MACD line value: `EMA(prices, fast) - EMA(prices, slow)`.

## Parameters

  - prices: list of prices, oldest first.
  - fast: period of the fast EMA (default 12).
  - slow: period of the slow EMA (default 26).

At least `max(fast, slow) * 2` prices are required; otherwise `nil` is
returned.

## Examples

    iex> TAlib.Indicators.MACD.macd([1, 4, 3, 5, 2, 6], 3, 2) |> Float.round(4)
    0.4861

# `macd_all`

```elixir
@spec macd_all([number()], pos_integer(), pos_integer(), pos_integer()) :: %{
  macd: float() | nil,
  signal: float() | nil,
  histogram: float() | nil
}
```

Calculate the MACD line, signal line and histogram of the latest point
in a single pass over the prices (one fast/slow EMA walk shared by all
three values).

## Parameters

  - prices: list of prices, oldest first.
  - fast: period of the fast MACD EMA (default 12).
  - slow: period of the slow MACD EMA (default 26).
  - signal_period: EMA period of the signal line (default 9).

Returns a map with `:macd`, `:signal` and `:histogram`. Each value is
`nil` when its own data requirement is not met, so e.g. the MACD line can
be defined while the signal line is still `nil`.

## Examples

    iex> %{macd: m, signal: s, histogram: h} = TAlib.Indicators.MACD.macd_all([5, 1, 6, 4, 7, 3, 8, 2, 9], 3, 2, 2)
    iex> {Float.round(m, 4), Float.round(s, 4), Float.round(h, 4)}
    {0.6532, 0.3372, 0.316}

# `macd_ext`

```elixir
@spec macd_ext([number()], pos_integer(), pos_integer(), pos_integer(), atom()) :: %{
  macd: float() | nil,
  signal: float() | nil,
  histogram: float() | nil
}
```

MACD with configurable moving-average types (TA-Lib MACDEXT): the
fast line, slow line and signal EMA all use the given `type`
(default `:ema`, the plain `macd/3` behaviour). Supported types are
those of `MA.ma/3`.

    iex> %{macd: m, signal: s, histogram: h} = TAlib.Indicators.MACD.macd_ext([1, 4, 3, 5, 2, 6], 3, 2, 2, :sma)
    iex> {Float.round(m, 4), Float.round(s, 4), Float.round(h, 4)}
    {0.3333, 0.0833, 0.25}

# `macd_fix`

```elixir
@spec macd_fix([number()], pos_integer(), pos_integer(), pos_integer()) :: %{
  macd: float() | nil,
  signal: float() | nil,
  histogram: float() | nil
}
```

MACD with the TA-Lib MACDFIX signal convention: the signal line is
the EMA over the whole MACD series starting at its first defined
value (rather than a trailing window).

    iex> TAlib.Indicators.MACD.macd_fix([1, 4, 3, 5, 2, 6], 3, 2, 2) |> Map.get(:macd) |> Float.round(4)
    0.4861

# `macd_list`

```elixir
@spec macd_list([number()], pos_integer(), pos_integer()) :: [float() | nil]
```

Calculate the full MACD line series from one fast/slow EMA pass.

Returns a list aligned with `prices`: entries before index
`max(fast, slow) - 1` are `nil`, every later entry is
`EMA(fast) - EMA(slow)` at that point.

## Parameters

  - prices: list of prices, oldest first.
  - fast: period of the fast EMA (default 12).
  - slow: period of the slow EMA (default 26).

## Examples

    iex> [1, 4, 3, 5, 2, 6] |> TAlib.Indicators.MACD.macd_list(3, 2) |> List.last() |> Float.round(4)
    0.4861

# `next`

```elixir
@spec next(TAlib.Indicators.MACD.State.t(), number()) ::
  {TAlib.Indicators.MACD.State.t(),
   %{macd: float() | nil, signal: float() | nil, histogram: float() | nil}}
```

Advance streaming MACD state by one price, in O(1):
`{state, %{macd: , signal: , histogram: }}`.

    iex> {state, _} = TAlib.Indicators.MACD.init([5, 1, 6, 4, 7, 3, 8, 2, 9], 3, 2, 2)
    iex> {_state, %{macd: m, signal: s, histogram: h}} = TAlib.Indicators.MACD.next(state, 7)
    iex> {Float.round(m, 4), Float.round(s, 4), Float.round(h, 4)}
    {0.2959, 0.3165, -0.0206}

# `signal`

```elixir
@spec signal([number()], pos_integer(), pos_integer(), pos_integer()) :: float() | nil
```

Calculate the latest signal line value: an EMA with the given `period`
over the MACD series of the last `period * 2` windows.

## Parameters

  - prices: list of prices, oldest first.
  - period: EMA period applied to the MACD series (default 9).
  - fast: period of the fast MACD EMA (default 12).
  - slow: period of the slow MACD EMA (default 26).

At least `max(fast, slow) * 2 + period * 2 - 1` prices are required for
every MACD value in the signal window to be defined; otherwise `nil` is
returned.

## Examples

    iex> TAlib.Indicators.MACD.signal([5, 1, 6, 4, 7, 3, 8, 2, 9], 2, 3, 2) |> Float.round(4)
    0.3372

---

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