Logic
15 entries. What each one takes, what it returns, and a working example.
Number of bars since the condition was last true.
The number of bars since the condition was last true (na if it has not happened yet).
Note
E.g. to measure how many bars have passed since the last breakout.
When to use
To measure how many bars have passed since a condition was last true — bars since the last breakout/signal. For the value at that condition, use valuewhen.
plot(barssince(crossover(close, sma(close, 20))))
The number of bars since the last cross-above.
Gives the difference between the current value and the value N bars ago. A positive result means an increase, a negative one a decrease. Used to measure the direction or speed of an indicator; for a percentage use `roc`.
The difference between source and its value n bars ago.
Note
Measures momentum/difference; a positive value indicates an increase.
When to use
To take a series' difference versus n bars ago (momentum) — per-bar change, acceleration. For magnitude only, abs(change(...)).
plot(change(close, 1))
The price difference between this bar and the previous one.
true on the bar where the two series cross in either direction.
true on the crossing bar.
Note
crossover or crossunder; use those for direction distinction.
When to use
To catch the moment two series cross in either direction — a single rule when direction is irrelevant. Use crossover for up only, crossunder for down only.
plotshape(cross(close, sma(close, 20)), style="xcross", location="absolute")
A mark on every bar where price crosses SMA20 (regardless of direction).
Gives true on the bar where the first series crosses above the second — only on that bar, not afterwards. For a cross to happen the first must have been below on the previous bar and above on this one. For a downward cross use `crossunder`.
A boolean series that is true on the bar where a crosses above b, and false on all other bars.
Note
It is true only on the bar where the cross occurs. A constant number can be given instead of b (e.g. a threshold).
When to use
To catch the moment one series crosses ABOVE another (or a threshold) — a buy signal, an indicator crossing its zero line upward. Use crossunder for the reverse, cross for direction-agnostic.
plotshape(crossover(close, sma(close, 20)), style="triangleup", location="belowbar", color="#26a69a")
A green triangle below the bar where price crosses above SMA20.
Gives true on the bar where the first series crosses below the second. It is the mirror of `crossover` and follows the same rule: above on the previous bar, below on this one.
A boolean series that is true on the bar where a crosses below b, and false on all other bars.
Note
It is true only on the bar where the cross occurs. It is the downward counterpart of crossover.
When to use
To catch the moment one series crosses BELOW another (or a threshold) — a sell signal, dropping below an overbought level. Use crossover for the reverse.
plotshape(crossunder(close, sma(close, 20)), style="triangledown", location="abovebar", color="#ef5350")
A red triangle above the bar where price crosses below SMA20.
Cumulative sum (from the start up to this bar).
The cumulative sum from the start up to this bar.
Note
E.g. cum(volume) is total volume; the basis of cumulative indicators (like obv).
When to use
To accumulate a series from the first bar onward (running total) — cumulative volume, cumulative return, OBV-like indicators. For only the last N bars, use sum.
plot(cum(volume))
The cumulative total volume from the start (an ever-rising line).
true if source fell for `length` consecutive bars.
True if there is an uninterrupted decrease over the last length bars.
Note
length consecutive comparisons are made; if even one does not decrease, the result is false.
When to use
To confirm a series has fallen continuously over the last length bars — downtrend confirmation, a weakness filter. Use rising for the reverse.
plotshape(falling(close, 3), style="circle", location="abovebar", color="#ef5350")
A red circle above bars where the close fell without interruption over the last 3 bars.
Gives the highest value of the last N bars, recomputed on every bar — a rolling ceiling. Used to look for channel breakouts or to hold a resistance level. The current bar is included; to get the ceiling of the earlier bars, step back one bar with `prev`.
A series holding the highest value over the last length bars (rolling max).
Note
Commonly used in breakout rules: close > highest(high, 20).
When to use
To find the highest value over the last length bars (rolling peak) — a breakout threshold, upper envelope, Donchian upper band. Use highestbars for how many bars ago the peak was.
plot(highest(high, 20))
The highest peak of the last 20 bars (upper breakout level).
Offset to the highest value over `length` bars (0 = current, −k = k bars ago).
The distance to the highest value: 0 = current bar, −k = k bars ago.
Note
Answers the question of how long ago the peak formed (gives the location of the highest value).
When to use
To find how many bars ago the highest value over the last length bars occurred (an offset, ≤0) — the peak's age, timing. For the value itself, use highest.
plot(highestbars(high, 10))
How many bars ago the 10-bar peak was (0 = this bar, negative = past).
iff(condition, ifTrue, ifFalse)
Element-wise select (instead of ternary). Color or number. ⚠ This function does not accept named arguments; pass the values positionally.
For each bar, ifTrue or ifFalse depending on the condition (element-wise selection).
Note
Used in place of a ternary operator; commonly used to produce a color series.
When to use
Ternary conditional selection — picking a value/color per bar based on a condition. In simple cases the ? : operator does the same; common for producing a color series.
plot(close, color=iff(close > open, "#26a69a", "#ef5350"))
A line colored green on up bars and red on down bars.
Gives the lowest value of the last N bars, recomputed on every bar — a rolling floor. Used together with `highest` to build a channel. The current bar is included.
A series holding the lowest value over the last length bars (rolling min).
Note
Used for support breaks and tracking lows.
When to use
To find the lowest value over the last length bars (rolling trough) — support, lower envelope, Donchian lower band, a stop floor. Use lowestbars for the trough's age.
plot(lowest(low, 20))
The lowest trough of the last 20 bars (lower support level).
Offset to the lowest value over `length` bars (0 = current, −k = k bars ago).
The distance to the lowest value: 0 = current bar, −k = k bars ago.
Note
Answers the question of how long ago the bottom formed.
When to use
To find how many bars ago the lowest value over the last length bars occurred (an offset, ≤0) — the trough's age. For the value itself, use lowest.
plot(lowestbars(low, 10))
How many bars ago the 10-bar trough was (0 = this bar, negative = past).
Gives the value of a series N bars ago. Used to compare today with the past and to tell whether a breakout is really new: `prev(hh, 1)` gives the previous bar's high, and if today's price is above it the breakout happened on this bar. ⚠ Asking for a bar that does not exist (at the start of the chart) returns empty.
A series holding the value from n bars ago.
Note
For comparing with the previous bar: close > prev(close, 1).
When to use
To read a series' value from n bars ago — the previous close, a lagged comparison, a difference. For the change itself, change is shorter.
plot(prev(close, 1))
Carries the previous bar's close onto this bar (lag of 1).
true if source rose for `length` consecutive bars.
True if there is an uninterrupted increase over the last length bars.
Note
length consecutive comparisons are made; if even one does not increase, the result is false.
When to use
To confirm a series has risen continuously over the last length bars — trend confirmation, a smooth-uptrend filter. Use falling for the reverse.
plotshape(rising(close, 3), style="circle", location="belowbar", color="#26a69a")
A green circle below bars where the close rose without interruption over the last 3 bars.
valuewhen(condition, source, occurrence=0)
The value of `source` on the bar where `condition` was true the `occurrence`-th time back (0 = most recent).
The source value on the relevant true bar of the condition.
Note
E.g. to remember the price at the last buy signal: valuewhen(buySignal, close, 0).
When to use
To recall the value of another series on a past bar where a condition was true — the price at the last buy signal, the volume at the last peak. For how many bars passed, use barssince.
plot(valuewhen(crossover(close, sma(close, 20)), close, 0))
Carries the close from the most recent cross-above bar as a horizontal level.