# ta reference

> Technical analysis: averages, oscillators, volatility, crosses and pivots.

`ta.*` functions keep history per call site, advancing once per confirmed bar of the handler's subscription. Call them unconditionally in handlers and use the result conditionally. They return null during warm-up.

## Functions

### ta.alma {#ta-alma}

```flowscope
ta.alma(source: float?, len: int, offset: float, sigma: float) -> float?
```

Returns the Arnaud Legoux moving average of the last `len` valid samples.

`source` supplies one sample each time the calculation runs. `len` sets the
valid-sample window; values outside its allowed range stop the script with an
error. Sample `i` (0 = oldest, `len - 1` = newest) carries Gaussian weight
`exp(-(i - m)^2 / (2 * s^2))` with `m = offset * (len - 1)` and `s = len /
sigma`; the result is the weight-normalized sum (weights divided by their
total). Null `source` samples output null and do not enter the window. The
result stays null until `len` valid samples are available.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |
| `offset` | `float` |
| `sigma` | `float` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.barsSince {#ta-barssince}

```flowscope
ta.barsSince(condition: bool) -> int?
```

Returns the number of bars since `condition` was last true.

`condition` is checked each time the calculation runs. A true bar returns 0,
and later false bars increment the count. The result is null until the first
true bar has been observed.

| Parameter | Type |
|---|---|
| `condition` | `bool` |

**Returns** `int?`

**Available in** Handlers and functions called from handlers.

### ta.change {#ta-change}

```flowscope
ta.change(source: float?, len: int = 1) -> float?
```

Returns the change from `source` to a prior valid sample.

`source` supplies one sample each time the calculation runs. `len` sets how
many valid samples to look back, defaults to 1, and values outside its allowed
range stop the script with an error. Null `source` samples output null and do
not advance the lookback. The result stays null until the referenced prior
valid sample exists.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.cross {#ta-cross}

```flowscope
ta.cross(left: float?, right: float?) -> bool
```

Returns true when `left` and `right` cross in either direction.

`left` and `right` are compared each time the calculation runs. Returns false
during warmup or when either operand is null. Null operands do not update the
stored comparison pair.

| Parameter | Type |
|---|---|
| `left` | `float?` |
| `right` | `float?` |

**Returns** `bool`

**Available in** Handlers and functions called from handlers.

### ta.crossover {#ta-crossover}

```flowscope
ta.crossover(left: float?, right: float?) -> bool
```

Returns true when `left` crosses above `right`.

`left` and `right` are compared each time the calculation runs. Returns true
when `left > right` now and `left <= right` on the previous valid comparison
pair. Returns false during warmup or when either operand is null. Null
operands do not update the stored comparison pair.

| Parameter | Type |
|---|---|
| `left` | `float?` |
| `right` | `float?` |

**Returns** `bool`

**Available in** Handlers and functions called from handlers.

### ta.crossunder {#ta-crossunder}

```flowscope
ta.crossunder(left: float?, right: float?) -> bool
```

Returns true when `left` crosses below `right`.

`left` and `right` are compared each time the calculation runs. Returns true
when `left < right` now and `left >= right` on the previous valid comparison
pair. Returns false during warmup or when either operand is null. Null
operands do not update the stored comparison pair.

| Parameter | Type |
|---|---|
| `left` | `float?` |
| `right` | `float?` |

**Returns** `bool`

**Available in** Handlers and functions called from handlers.

### ta.cum {#ta-cum}

```flowscope
ta.cum(source: float?, reset: bool = false) -> float?
```

Returns the cumulative sum of valid `source` samples.

`source` supplies one sample each time the calculation runs. The first valid
sample starts the running total. Null `source` samples output null and leave
the running total unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `reset` | `bool` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.dev {#ta-dev}

```flowscope
ta.dev(source: float?, len: int) -> float?
```

Returns the mean absolute deviation of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
This is the average absolute distance from the mean.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.ema {#ta-ema}

```flowscope
ta.ema(source: float?, len: int) -> float?
```

Returns the exponential moving average.

`source` supplies the next sample. `len` sets the smoothing weight to
`2 / (len + 1)`; values outside its allowed range stop the script with an error.

The first non-null sample starts the average and is returned immediately.
A null `source` returns null and leaves the average unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.falling {#ta-falling}

```flowscope
ta.falling(source: float?, len: int) -> bool
```

Reports whether `source` is below every earlier sample in the window.

`source` supplies the next sample. `len` sets the number of samples, including
the current one; values outside its allowed range stop the script with an error.

Returns true when the current sample is strictly less than each of the
`len - 1` earlier non-null samples. Returns false until enough samples are
available or when `source` is null. Null samples do not enter the history.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `bool`

**Available in** Handlers and functions called from handlers.

### ta.highest {#ta-highest}

```flowscope
ta.highest(source: float?, len: int) -> float?
```

Returns the highest value of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
Infinities compare normally.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.hma {#ta-hma}

```flowscope
ta.hma(source: float?, len: int) -> float?
```

Returns the Hull moving average of `source`.

`source` supplies one sample each time the calculation runs. `len` sets the
weighted-average window; values outside its allowed range stop the script with
an error. The calculation combines weighted moving averages and a final
`sqrt(len)` smoothing window. The result stays null until `len + sqrt(len) -
1` valid samples are available; null `source` samples output null and do not
advance the windows.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.linreg {#ta-linreg}

```flowscope
ta.linreg(source: float?, len: int, offset: int = 0) -> float?
```

Returns a linear-regression value over the last `len` valid samples.

`source` supplies one sample each time the calculation runs. `len` sets the
valid-sample window; values outside its allowed range stop the script with an
error. `offset` selects where the fitted line is evaluated and defaults to 0.
Null `source` samples output null and do not enter the window. The result
stays null until `len` valid samples are available.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |
| `offset` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.lowest {#ta-lowest}

```flowscope
ta.lowest(source: float?, len: int) -> float?
```

Returns the lowest value of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
Infinities compare normally.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.max {#ta-max}

```flowscope
ta.max(source: float?, reset: bool = false) -> float?
```

Returns the running maximum of valid `source` samples.

`source` supplies one sample each time the calculation runs. The first valid
sample starts the running maximum. Null `source` samples output null and leave
the running maximum unchanged. `reset` true forgets the running maximum before
this bar's sample is compared, even when that sample is null.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `reset` | `bool` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.median {#ta-median}

```flowscope
ta.median(source: float?, len: int) -> float?
```

Returns the median of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.


Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.min {#ta-min}

```flowscope
ta.min(source: float?, reset: bool = false) -> float?
```

Returns the running minimum of valid `source` samples.

`source` supplies one sample each time the calculation runs. The first valid
sample starts the running minimum. Null `source` samples output null and leave
the running minimum unchanged. `reset` true forgets the running minimum before
this bar's sample is compared, even when that sample is null.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `reset` | `bool` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.mode {#ta-mode}

```flowscope
ta.mode(source: float?, len: int) -> float?
```

Returns the most frequent value of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
If several values tie, returns the smallest of them.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.pivotHigh {#ta-pivothigh}

```flowscope
ta.pivotHigh(source: float?, left: int, right: int) -> float?
```

Returns a pivot high once later samples confirm it.

`source` supplies the next sample. `left` sets how many earlier samples to
check, and `right` sets how many later samples must confirm the pivot. Values
outside either allowed range stop the script with an error.

A sample qualifies when none of the other `left + right` samples is higher.
Equal values do not disqualify it. The pivot is returned `right` non-null samples
after it occurs, on the confirmation bar. Otherwise the result is null.

A null `source` returns null and does not enter the sample history.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `left` | `int` |
| `right` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.pivotLow {#ta-pivotlow}

```flowscope
ta.pivotLow(source: float?, left: int, right: int) -> float?
```

Returns a pivot low once later samples confirm it.

`source` supplies the next sample. `left` sets how many earlier samples to
check, and `right` sets how many later samples must confirm the pivot. Values
outside either allowed range stop the script with an error.

A sample qualifies when none of the other `left + right` samples is lower.
Equal values do not disqualify it. The pivot is returned `right` non-null samples
after it occurs, on the confirmation bar. Otherwise the result is null.

A null `source` returns null and does not enter the sample history.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `left` | `int` |
| `right` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.rising {#ta-rising}

```flowscope
ta.rising(source: float?, len: int) -> bool
```

Reports whether `source` is above every earlier sample in the window.

`source` supplies the next sample. `len` sets the number of samples, including
the current one; values outside its allowed range stop the script with an error.

Returns true when the current sample is strictly greater than each of the
`len - 1` earlier non-null samples. Returns false until enough samples are
available or when `source` is null. Null samples do not enter the history.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `bool`

**Available in** Handlers and functions called from handlers.

### ta.rma {#ta-rma}

```flowscope
ta.rma(source: float?, len: int) -> float?
```

Returns the Wilder's smoothed moving average.

`source` supplies the next sample. `len` sets the smoothing weight to
`1 / len`; values outside its allowed range stop the script with an error.

The first non-null sample starts the average and is returned immediately.
A null `source` returns null and leaves the average unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.roc {#ta-roc}

```flowscope
ta.roc(source: float?, len: int) -> float?
```

Returns the rate of change from a prior valid sample.

`source` supplies one sample each time the calculation runs. `len` sets how
many valid samples to look back; values outside its allowed range stop the
script with an error. Null `source` samples output null and do not advance the
lookback. The result stays null until the referenced prior sample exists, and
is null when that prior value is zero.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.rsi {#ta-rsi}

```flowscope
ta.rsi(source: float?, len: int) -> float?
```

Returns the relative strength index over valid source changes.

`source` supplies one sample each time the calculation runs. `len` sets the
Wilder smoothing window; values outside its allowed range stop the script with
an error. The result stays null until `len + 1` valid samples provide enough
changes. Null `source` samples output null and leave the average gain and loss
unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.sma {#ta-sma}

```flowscope
ta.sma(source: float?, len: int) -> float?
```

Returns the simple moving average of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.


Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.stdev {#ta-stdev}

```flowscope
ta.stdev(source: float?, len: int) -> float?
```

Returns the population standard deviation of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
The calculation divides by `len`.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.stoch {#ta-stoch}

```flowscope
ta.stoch(source: float?, high: float?, low: float?, len: int) -> float?
```

Returns the stochastic position of `source` within the recent range.

`source`, `high`, and `low` supply the current values. `len` sets how many
non-null samples to include; values outside its allowed range stop the script
with an error.

Returns the percentage position of `source` between the lowest low and highest
high in that window. If any input is null, returns null and does not add a sample.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `high` | `float?` |
| `low` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.sum {#ta-sum}

```flowscope
ta.sum(source: float?, len: int) -> float?
```

Returns the sum of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
Null samples do not count as zero.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.swma {#ta-swma}

```flowscope
ta.swma(source: float?) -> float?
```

Returns a four-sample symmetrically weighted moving average.

`source` supplies one sample each time the calculation runs. The fixed window
uses four valid samples with symmetric weights 1, 2, 2, 1 (oldest to newest)
divided by 6. Null `source` samples output null and do not enter the window.
The result stays null until four valid samples are available.

| Parameter | Type |
|---|---|
| `source` | `float?` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.variance {#ta-variance}

```flowscope
ta.variance(source: float?, len: int) -> float?
```

Returns the population variance of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
The calculation divides by `len`.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.wma {#ta-wma}

```flowscope
ta.wma(source: float?, len: int) -> float?
```

Returns the linearly weighted moving average of the last `len` non-null samples.

`source` supplies the next sample. `len` chooses how many non-null samples to
include; values outside its allowed range stop the script with an error.
Newer samples receive larger weights.

Returns null until `len` non-null samples are available. A null `source`
returns null and leaves the sample history unchanged.

| Parameter | Type |
|---|---|
| `source` | `float?` |
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

## Methods

### ta.accDist {#ta-accdist}

```flowscope
ta.accDist() -> float?
```

Returns the accumulation/distribution line for the subscription.

Uses the subscription's high, low, close, and volume. The first non-null sample
starts the cumulative line. A null input returns null and leaves the running
total unchanged.

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.atr {#ta-atr}

```flowscope
ta.atr(len: int) -> float?
```

Returns the average true range over valid OHLCV samples.

`len` sets Wilder smoothing; values outside its allowed range stop the script
with an error. Uses the subscription's high, low, and close. True range uses
the current high and low and the previous close.

The first non-null sample returns a result immediately. A null input returns
null and leaves the average unchanged.

| Parameter | Type |
|---|---|
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.mfi {#ta-mfi}

```flowscope
ta.mfi(len: int) -> float?
```

Returns the money flow index over valid OHLCV samples.

`len` sets the valid-sample window; values outside its allowed range stop the
script with an error. The subscription supplies high, low, close, and volume.
Null input fields make the bar output null and do not update the window. The
result stays null until `len + 1` valid samples are available.

| Parameter | Type |
|---|---|
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.tr {#ta-tr}

```flowscope
ta.tr() -> float?
```

Returns true range for the subscription's current bar.

Uses the current high and low and the previous close. The first non-null
sample returns a result immediately. A null input returns null and leaves the
previous close unchanged.

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.vwap {#ta-vwap}

```flowscope
ta.vwap(reset: bool = false, source: float? = null) -> float?
```

Returns the volume-weighted average price since the last reset.

The subscription supplies price and volume.

- `reset` starts a new average before adding the current sample, even when
  that sample is null. The first valid sample starts the new average.
- `source` optionally replaces the close price. Omitting it uses close;
  a supplied expression that returns null counts as a missing sample.

A null input returns null and leaves the totals unchanged. The result is also
null while accumulated volume is zero. A non-null reset sample with volume
returns its own price. During a forming candle, resets are temporary and are
recalculated on the next update.

| Parameter | Type |
|---|---|
| `reset` | `bool` |
| `source` | `float?` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.vwapDev {#ta-vwapdev}

```flowscope
ta.vwapDev(reset: bool = false, source: float? = null) -> float?
```

Returns the volume-weighted standard deviation around VWAP.

The subscription supplies price and volume. Use `vwap + mult * vwapDev` and
`vwap - mult * vwapDev` for upper and lower bands.

- `reset` starts new totals before adding the current sample, even when it is null.
- `source` optionally replaces the close price. Omitting it uses close;
  a supplied expression that returns null counts as a missing sample.

This is a population standard deviation over the bars since the last reset.
The first valid sample with volume returns 0. A null input returns null and
leaves the totals unchanged. The result is also null while accumulated volume
is zero.

Use the same `reset` and `source` as the matching `vwap` call so both cover the
same bars.

| Parameter | Type |
|---|---|
| `reset` | `bool` |
| `source` | `float?` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.

### ta.vwma {#ta-vwma}

```flowscope
ta.vwma(len: int) -> float?
```

Returns a volume-weighted moving average over valid OHLCV samples.

`len` sets the valid-sample window; values outside its allowed range stop the
script with an error. The subscription supplies close and volume. Null input
fields output null and do not enter the window. The result stays null until
`len` valid samples are available.

| Parameter | Type |
|---|---|
| `len` | `int` |

**Returns** `float?`

**Available in** Handlers and functions called from handlers.