Series helpers¶

Use these functions to describe relationships between values. They are available directly, with no imports. Unlike indicators such as SMA and RSI, most helpers return one value for the current evaluation, rather than a new historical series.

Crossover and crossunder¶

crossover(a, b) is true when a is above b now and was at or below it one bar ago. crossunder(a, b) reverses those comparisons. Both arguments must provide current and previous values.

crossover(ema(20), ema(50))
crossunder(ema(20), ema(50))
ema(20) crosses over ema(50)
ema(20) crosses under ema(50)

The phrase and function forms express the same transition. ema(20) > ema(50) instead stays true while the ordering holds. A blocked entry is not remembered for a later bar simply because a crossing occurred earlier.

Do not pass a scalar helper such as mean(close, 20) as a crossing input: it has no previous reading to inspect. Use a series-returning average such as sma(20). Numeric thresholds are also scalars, so use explicit current/previous comparisons for a threshold crossing:

rsi(14) > 50 and rsi(14)[1] <= 50

Highest and lowest¶

highest(series, length) and lowest(series, length) return the maximum or minimum among the latest N values, including now. Length is required and must be positive. The result is a scalar in the input's units.

close > lowest(low, 20)
highest(high, 20) - lowest(low, 20) > 5

Supply a complete window; these helpers can raise an out-of-history error if it is missing. Do not append [1] to the scalar result. For a previous-window breakout use a series-returning channel instead:

close > donchian_upper(20)[1]

The related highest_n(bars, "high", 20) and lowest_n(bars, "low", 20) return series, so history indexing is available on them. Their argument order is input, column name, period; highest_n(20) is not a valid shorthand.

close > highest_n(bars, "high", 20)[1]
close < lowest_n(bars, "low", 20)[1]

Mean and standard deviation¶

mean(series, length) returns the arithmetic average of the available recent observations, up to N. stdev(series, length) returns sample standard deviation, dividing squared deviations by count minus one. stddev is an accepted spelling for the same standard-deviation helper.

volume > mean(volume, 20)
stdev(close, 20) > 2
stddev(close, 20) > 2

Results are scalar and retain the input's units. Both lengths must be positive. mean uses a shorter available window during warmup and returns 0 if no values are readable; stdev returns 0 with fewer than two values. That differs from a complete-window SMA series. Do not append [1] or assume the requested full window has been read merely because the call returns a number.

Change and pct_change¶

Function	Form	Meaning
`change`	`change(close, 14)`	Current value minus the value 14 bars ago, in input units.
`pct_change`	`pct_change(close, 14)`	`(current − earlier) / earlier`, as a fraction.

Offset defaults to 1 in change(close) and pct_change(close). Offsets must be non-negative; N needs N+1 observations. Both results are scalar.

change(close, 14) > 5
pct_change(close, 14) > 0.05

A move from 100 to 105 gives change 5 and pct_change 0.05. roc(14) gives 5 for that same relative move. pct_change returns 0 if the earlier value is zero; that fallback is not a meaningful return measurement.

Rising and falling¶

rising(series, steps) requires a strict increase on every adjacent comparison. falling(series, steps) requires a strict decrease. Steps default to 1, must be at least 1, and require steps+1 observations. Both return a Boolean now.

rising(close, 3)
falling(close, 3)
rising(ema(20), 3)

rising(close, 3) means current > previous > two bars ago > three bars ago. A price above its value three bars ago is not enough if it fell in between. Equality breaks the strict test. These helpers do not claim Pine equivalence. For chronological prices [1, 3, 2, 4], rising(close, 3) is false even though 4 exceeds every earlier value in the window: the 3-to-2 step fell. Likewise, [4, 2, 3, 1] makes falling(close, 3) false. Check these counterexamples when porting a rule instead of relying on a similarly named function.

Bars since a condition¶

barssince(condition_series) returns a scalar count: 0 when true now, 1 when most recently true one bar ago, and so on. If never true in the available series, it returns that series' length. It requires a historical Boolean series, not just a Boolean calculated now.

The current TradeScript comparison rsi(14) > 70 produces a Boolean now, not a historical Boolean series. Consequently, barssince(rsi(14) > 70) does not reconstruct that event's history. A scalar price comparison does not either. This helper is exposed, but ordinary TradeScript conditions do not supply the historical Boolean input it needs; do not use it as a working event counter. The returned count is also bounded by supplied history and does not track an event forever.

For clock predicates and session ranges, use instruments and schedules. For combining these Boolean results, see conditions.