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

Stochastic oscillator [Wikipedia](https://en.wikipedia.org/wiki/Stochastic_oscillator).

* `%K = (Close - Lowest Low) / (Highest High - Lowest Low) * 100`
* `%D = SMA(%K, d_period)`

See `TAlib` for the input conventions: prices are always given in
chronological order, oldest first, and series are returned aligned with
the input. `nil` is returned when there is not enough data or the window
has no range (flat prices), since `%K` is then undefined.

Note that with a plain price list, close, high and low all come from the
same series; for proper high/low support an OHLC input shape is needed.

# `k_init`

```elixir
@spec k_init([number()], pos_integer()) ::
  {TAlib.Indicators.Stochastic.KState.t(), [float() | nil]}
```

Warm up streaming fast-%K state from `history`.

Returns `{state, values}` with `values` the full %K series of
`history` (identical to `stochastic_k_list/2`), and `state` ready to
continue it one price at a time in O(1) via `k_next/2`. History
needs at least `period` prices.

## Examples

    iex> {state, values} = TAlib.Indicators.Stochastic.k_init([1, 6, 2, 5, 3], 3)
    iex> values
    [nil, nil, 20.0, 75.0, 33.33333333333333]
    iex> {_state, 100.0} = TAlib.Indicators.Stochastic.k_next(state, 7)

# `k_next`

```elixir
@spec k_next(TAlib.Indicators.Stochastic.KState.t(), number()) ::
  {TAlib.Indicators.Stochastic.KState.t(), float() | nil}
```

Advance streaming fast-%K state by one price, in O(1). A flat window
(no range) yields `nil`, like the batch series.

    iex> {state, _} = TAlib.Indicators.Stochastic.k_init([1, 6, 2, 5, 3], 3)
    iex> {_state, value} = TAlib.Indicators.Stochastic.k_next(state, 7)
    iex> value
    100.0

# `slow`

```elixir
@spec slow([number()], pos_integer(), pos_integer(), pos_integer()) :: %{
  k: float() | nil,
  d: float() | nil
}
```

The slow stochastic (TA-Lib STOCH): the slowed %K line is the SMA of the
fast %K over `slowing` bars, and %D is the SMA of the slowed %K.

## Parameters

  - prices: list of prices, oldest first.
  - period: %K lookback window, a positive integer (default 14).
  - slowing: SMA period applied to fast %K (default 3).
  - d_period: SMA period applied to the slowed %K (default 3).

## Examples

    iex> prices = [1, 6, 2, 5, 3, 7, 4]
    iex> %{k: k, d: d} = TAlib.Indicators.Stochastic.slow(prices, 3, 2, 2)
    iex> {Float.round(k, 4), Float.round(d, 4)}
    {62.5, 64.5833}

# `slow_init`

```elixir
@spec slow_init([number()], pos_integer(), pos_integer(), pos_integer()) ::
  {TAlib.Indicators.Stochastic.SlowState.t(),
   %{k: [float() | nil], d: [float() | nil]}}
```

Warm up streaming slow-stochastic state (TA-Lib STOCH) from
`history`: fast %K over `period`, slowed by an SMA of `slowing`, %D
an SMA of `d_period` over the slowed line.

Returns `{state, values}` with `values` the two aligned series
(`%{k: , d: }`), and `state` ready to continue them one price at a
time in O(1) via `slow_next/2`. History needs at least
`period + slowing + d_period - 2` prices.

## Examples

    iex> {state, values} = TAlib.Indicators.Stochastic.slow_init([1, 6, 2, 5, 3, 7, 4], 3, 2, 2)
    iex> {List.last(values.k), List.last(values.d)}
    {62.49999999999999, 64.58333333333333}
    iex> {_state, %{k: k, d: d}} = TAlib.Indicators.Stochastic.slow_next(state, 5)
    iex> {Float.round(k, 4), Float.round(d, 4)}
    {29.1667, 45.8333}

# `slow_next`

```elixir
@spec slow_next(TAlib.Indicators.Stochastic.SlowState.t(), number()) ::
  {TAlib.Indicators.Stochastic.SlowState.t(),
   %{k: float() | nil, d: float() | nil}}
```

Advance streaming slow-stochastic state by one price, in O(1):
`{state, %{k: , d: }}`.

    iex> {state, _} = TAlib.Indicators.Stochastic.slow_init([1, 6, 2, 5, 3, 7, 4], 3, 2, 2)
    iex> {_state, %{k: k, d: d}} = TAlib.Indicators.Stochastic.slow_next(state, 5)
    iex> {Float.round(k, 4), Float.round(d, 4)}
    {29.1667, 45.8333}

# `stochastic_d`

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

%D: the `d_period`-period simple moving average of %K.

## Parameters

  - prices: list of prices, oldest first.
  - period: %K lookback window, a positive integer (default 14).
  - d_period: SMA period applied to %K, a positive integer (default 3).

## Examples

    iex> TAlib.Indicators.Stochastic.stochastic_d([1, 6, 2, 5, 3, 7, 4], 5, 3)
    60.0

# `stochastic_k`

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

%K = (Current Close - Lowest Low) / (Highest High - Lowest Low) * 100

## Parameters

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

## Examples

    iex> TAlib.Indicators.Stochastic.stochastic_k([1, 2, 5, 1, 4], 5)
    75.0

    iex> TAlib.Indicators.Stochastic.stochastic_k([5, 5, 5], 3)
    nil

# `stochastic_k_list`

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

Calculate the full %K series.

Returns a list aligned with `prices`: the first `period - 1` entries are
`nil`, and every later entry is %K of the window ending at that point.
Windows with no range (flat prices) produce `nil`, since %K is then
undefined.

## Parameters

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

## Examples

    iex> TAlib.Indicators.Stochastic.stochastic_k_list([1, 6, 2, 5, 3], 3)
    [nil, nil, 20.0, 75.0, 33.33333333333333]

---

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