HighestBars

Syntax

HighestBars[Period](source)

Parameters

Formula

For a window of Period bars ending at the current bar:

HighestBars[Period](x) = offset k in [0, Period - 1]
                         where x[k] is the maximum of the window

If no maximum can be determined within the window, the function returns -1.

How it works

HighestBars locates the position of the maximum rather than the maximum itself. Where Highest[20](close) answers "what was the highest close of the last 20 bars", HighestBars[20](close) answers "how long ago did it happen". The result is a bar offset counted backward from the current bar, so it plugs directly into series indexing: close[HighestBars[20](close)] reads the highest close of the window.

The offset is zero-based. A return value of 0 means the current bar carries the highest value, which is itself a useful signal, marking fresh highs of the window. When several bars share the same maximum value, the function reports the first occurrence found scanning backward from the current bar, that is, the most recent one.

The value updates on every bar. As the window slides forward, an old peak eventually drops out of the window and the function jumps to the offset of the next-highest bar still inside it.

Examples

Example 1, Labelling the peak close (Indicator)

myHighest = HighestBars[10](close)
IF myHighest > 0 THEN
  // Place a label on the bar that holds the highest close of the window
  DRAWTEXT("Highest close in last 10 bars", barindex - myHighest, close[myHighest])
ENDIF

HighestBars finds how many bars back the highest close of the last 10 bars occurred, and DRAWTEXT anchors a label at that bar. The check myHighest > 0 skips bars where the current close is itself the maximum.

Example 2, Bars since the 50-bar high (Indicator)

// Plot the age of the highest high inside a 50-bar window
RETURN HighestBars[50](high) AS "bars since 50-bar high"

The plotted line falls to 0 whenever a new 50-bar high prints and climbs by one on each bar that fails to exceed it, a compact measure of how stale the current high is.

Example 3, Entering only on fresh highs (ProOrder)

recency = HighestBars[20](close)
// An offset of 0 means this bar set the highest close of the window
IF recency = 0 AND NOT ONMARKET THEN
  BUY 1 CONTRACT AT MARKET
ENDIF
SET STOP PLOSS 40

The strategy buys only on bars that establish a new 20-bar closing high, using the zero offset as a breakout confirmation.

Common errors and gotchas

• Offset, not value. HighestBars returns a bar count, not a price. Plotting it as if it were the peak value produces a sawtooth between 0 and Period. Use Highest for the value itself.
• Zero-based counting. 0 refers to the current bar, so the largest possible return is Period - 1. Logic written as if counting started at 1 misses fresh highs entirely.
• The -1 case. When the window cannot produce a maximum, the function returns -1. Feeding that directly into a series index such as close[-1] is invalid, so guard the result before indexing.
• Ties resolve to the most recent bar. With duplicate maxima in the window, the smallest offset wins. Calculations that assume the oldest occurrence will be off by the gap between the duplicates.

Related instructions

• Highest, the highest value itself over a period.
• Lowest, the lowest value over a period.
• LowestBars, offset to the lowest value, the mirror of HighestBars.
• BarsSince, bars elapsed since an arbitrary condition was true.
• BarIndex, absolute bar number, used to convert offsets to chart positions.
• DRAWTEXT, draws a label at a bar located with the returned offset.
• Summation, fixed-window aggregation of a series.