Understanding ta.highestbars() Function in Pine Script

Let’s delve into the syntax, usage, and practical application of ta.highestbars().

Syntax and Overloads

Pine Script provides two overloads of the ta.highestbars() function, catering to different needs:

Single Argument Overload

   ta.highestbars(length) → series int

length (series int): Specifies the number of bars to look back from the current bar.

Two Arguments Overload

   ta.highestbars(source, length) → series int

source (series): The data series (e.g., close, open, high, low) from which the highest value will be determined.
length (series int): The number of bars to look back from the current bar to find the highest value in the specified source.

Arguments

length (series int): Represents the window size or the count of bars to analyze backward from the current bar. This parameter is critical in defining the scope of data for the highest value search.
source (optional, series): Specifies the data series to search for the highest value. If omitted, the function defaults to using the high price series of the bars.

Returns

The function returns a series of integers representing the offset to the highest bar within the specified length. An offset of 0 indicates that the highest value is at the current bar.

Remarks

In the two-argument version, the function allows specifying a custom source series, which can be any series, such as close, open, high, or low. The one-argument version automatically uses the high series.
na (not available) values in the source series are ignored during the calculation, ensuring the function accurately identifies the highest bar without being skewed by missing data.

Practical Example

Let’s illustrate the use of ta.highestbars() with an example that highlights both syntaxes:

//@version=5
indicator("Highest Bars Example", overlay=true)

// Define the length for the lookback period
lookbackLength = input(14, title="Lookback Period")

// Example using the high series (one argument)
highestOffset = ta.highestbars(lookbackLength)

// Example using a specific series, e.g., close price (two arguments)
highestCloseOffset = ta.highestbars(close, lookbackLength)

// Plotting the highest bar for visual reference
plotshape(series=highestOffset == 0, location=location.abovebar, color=color.green, style=shape.triangleup, size=size.small, title="Highest High")
plotshape(series=highestCloseOffset == 0, location=location.belowbar, color=color.red, style=shape.triangledown, size=size.small, title="Highest Close")

Explanation

lookbackLength is defined to set the number of bars to look back. This value is adjustable via an input field on the chart.
highestOffset calculates the offset to the highest high over the specified period using the high series.
highestCloseOffset calculates the offset to the highest close over the same period using the close series.
plotshape functions are used to visually indicate the bars where the highest high and highest close are located relative to the lookback period.

Key Features and Takeaways

Flexibility: ta.highestbars() offers flexibility in technical analysis, allowing the examination of various data series over a customizable lookback period.
Efficiency: Efficiently identifies the highest value’s offset, aiding in strategy development and market analysis.
Versatility: Applicable in a wide range of trading strategies, from trend confirmation to reversal detection.

Incorporating ta.highestbars() into your Pine Script strategies can significantly enhance decision-making by providing clear insights into market dynamics over your specified periods.