Historical

This section documents the hitorical (ta.*) functions.

---

ta.barssince

Returns the number of bars since a specified condition was true for the nth occurrence.

Syntax:

ta.barssince(condition)
ta.barssince(condition, occurrence)

Parameters:

• condition: Boolean expression to evaluate

• occurrence: (Optional) Which occurrence to find (0 = most recent, 1 = second most recent, etc.). Defaults to 0.

Examples:

// Bars since last green candle (most recent occurrence)
ta.barssince($BTC.close >= $BTC.open)

// Bars since second-to-last green candle
ta.barssince($BTC.close >= $BTC.open, 1)

// Bars since RSI was overbought (most recent)
ta.barssince(ta.rsi($BTC, 14) > 70)

// Bars since RSI was overbought (previous occurrence)
ta.barssince(ta.rsi($BTC, 14) > 70, 1)

// Bars since price crossed above moving average
ta.barssince(ta.crossover($BTC.close, ta.sma($BTC, 20)))

// Bars since previous confirmed pivot high
ta.barssince(ta.pivothigh($BTC, 5, 5) !== null, 0)

// Bars since volume spike
ta.barssince($BTC.volume > ta.sma($BTC.volume, 20) * 2)

// Bars since MACD signal
ta.barssince(ta.crossover(ta.macd($BTC, 12, 26, 9).macd, ta.macd($BTC, 12, 26, 9).signal))

Returns: Number of bars since condition was true at the specified occurrence (null if never true or occurrence not found)

Use Cases:

• Time-based filters for signals

• Avoiding repeated signals too close together

• Measuring duration since key events

• Exit timing based on time elapsed

---

ta.valuewhen

Returns the value of a source series when a specified condition was true for the nth occurrence.

Syntax:

ta.valuewhen(condition, source)
ta.valuewhen(condition, source, occurrence)

Parameters:

• condition: Boolean expression or series that determines when to capture the source value

• source: The data series from which to retrieve values

• occurrence: (Optional) Which occurrence to return (0 = most recent, 1 = second most recent, etc.). Defaults to 0.

Examples:

// Get close price when RSI was last overbought
ta.valuewhen(ta.rsi($BTC, 14) > 70, $BTC.close)

// Get volume from the second most recent time price broke above SMA
ta.valuewhen(ta.crossover($BTC.close, ta.sma($BTC, 20)), $BTC.volume, 1)

// Get high price when MACD crossed above signal line
ta.valuewhen(ta.crossover(ta.macd($BTC, 12, 26, 9).macd, ta.macd($BTC, 12, 26, 9).signal), $BTC.high)

// Get the price level when volume spiked (third occurrence back)
ta.valuewhen($BTC.volume > ta.sma($BTC.volume, 20) * 2, $BTC.close, 2)

// Reference previous breakout level
ta.valuewhen($BTC.close > ta.highest($BTC.high, 20), $BTC.close)

// Get RSI value when price made a new low
ta.valuewhen($BTC.low < ta.lowest($BTC.low, 50), ta.rsi($BTC, 14))

// Track entry price from signal
ta.valuewhen(ta.crossover(ta.ema($BTC, 12), ta.ema($BTC, 26)), $BTC.close)

Returns:

• Value of source when condition was true for the specified occurrence

• undefined if the specified occurrence was not found or insufficient data

Advanced Examples:

// Compare current close to previous breakout level
$BTC.close > ta.valuewhen(ta.crossover($BTC.close, ta.sma($BTC, 50)), $BTC.close) * 1.05

// Stop loss based on previous swing low
ta.valuewhen(ta.pivotlow($BTC.low, 3, 3) != null, $BTC.low[3], 0)

// Resistance from last time RSI was overbought
ta.valuewhen(ta.rsi($BTC, 14) > 80, $BTC.high)

// Volume confirmation - compare to volume when similar pattern occurred
$BTC.volume > ta.valuewhen(ta.crossover($BTC.close, ta.bb($BTC, 20, 2).upper), $BTC.volume) * 0.5

Use Cases:

• Reference levels from previous signals or events

• Track entry prices for position management

• Compare current conditions to historical occurrences

• Set dynamic stop losses based on previous swing points

• Analyze pattern consistency by comparing volumes or prices

• Create conditional logic based on historical trigger levels