ta.valuewhen Function in Pine Script

One of the versatile functions available in Pine Script is ta.valuewhen. This function allows you to retrieve the value of a series (like price, volume, or another indicator) when a specific condition was true on its nth occurrence in the past. In this tutorial, we will delve deep into the ta.valuewhen function, covering its syntax, use cases, and intricacies.

Understanding the ta.valuewhen Function

Syntax & Overloads

The ta.valuewhen function comes with multiple overloads to accommodate different types of series. The general syntax is:

ta.valuewhen(condition, source, occurrence)

Where:

• condition is a series of boolean values representing when a certain condition is true.
• source is the series from which we want to retrieve a value. It can be of type int, float, bool, or color.
• occurrence is an integer indicating which occurrence of the condition we’re interested in. Counting starts from 0 (most recent occurrence) and increases as we go back in time.

The available overloads are:

• ta.valuewhen(condition, source, occurrence) → series float
• ta.valuewhen(condition, source, occurrence) → series int
• ta.valuewhen(condition, source, occurrence) → series bool
• ta.valuewhen(condition, source, occurrence) → series color

Example

Consider the following code:

//@version=5
indicator("ta.valuewhen")
slow = ta.sma(close, 7)
fast = ta.sma(close, 14)
// Get value of `close` on second most recent cross
plot(ta.valuewhen(ta.cross(slow, fast), close, 1))

In this snippet:

1. We define two simple moving averages (SMA) – slow with a period of 7 bars and fast with a period of 14 bars.
2. We utilize ta.valuewhen to fetch the closing price (close) from the bar where the slow SMA last crossed the fast SMA (second most recent occurrence).
3. The result is then plotted on the chart.

Remarks

While ta.valuewhen is potent, there are a couple of things to keep in mind:

• The function executes on every bar, so you must be cautious about its placement in your script.
• Avoid using it inside loops (for or while) since it can lead to unexpected behavior.
• Be aware that employing ta.valuewhen might result in indicator repainting.

A Unique Use Case: Detecting Volume Spikes

Let’s explore a scenario where ta.valuewhen can be handy.

Suppose you want to detect significant volume spikes and fetch the closing price of the bar when the volume was exceptionally high. We can achieve this using ta.valuewhen.

//@version=5
indicator("Volume Spike Detector")
avgVolume = ta.sma(volume, 20)
// Define a condition for volume spikes - volume being 3 times the average volume
volumeSpikeCondition = volume > 3 * avgVolume
// Get the close price on the most recent volume spike
spikeClose = ta.valuewhen(volumeSpikeCondition, close, 0)
plot(spikeClose, color=color.red, style=plot.style_cross)

In the above code:

1. We first calculate a 20-bar SMA of the volume to determine the average trading volume.
2. A volumeSpikeCondition is defined, which is true when the volume exceeds three times the average volume.
3. Using ta.valuewhen, we get the closing price of the most recent bar that experienced a volume spike.
4. We then plot these points on the chart using red crosses.

Key Takeaway

The ta.valuewhen function in Pine Script is an invaluable tool for obtaining series values under specific conditions from historical data. By understanding its syntax and nuances, you can harness its potential to craft sophisticated trading indicators and strategies. Whether you’re trying to detect crossovers, volume spikes, or other significant events, ta.valuewhen can be a critical component in your Pine Script toolbox.

Conclusion

Mastering functions like ta.valuewhen paves the way to creating advanced scripts in Pine Script. Remember to use it judiciously, keeping in mind the potential pitfalls like indicator repainting. With the right approach, you can employ ta.valuewhen to craft insightful trading indicators that can significantly aid in decision-making. Happy coding!