QuanTAlib/lib/numerics/maxindex/Maxindex.md

MAXINDEX: Rolling Maximum Index

It's not just about the peak — it's about when the peak occurred.

Property	Value
Category	Numeric
Inputs	Source (close)
Parameters	period (default=14, min=2)
Outputs	Single series (Maxindex)
Output range	Streaming: 0 to period-1 (bars-ago); Batch span: absolute array index
Warmup	period bars

• MAXINDEX finds the position (index) of the maximum value within a rolling lookback window.
• Streaming mode outputs bars-ago offset (0 = current bar holds the max, period-1 = oldest bar).
• Batch span mode outputs absolute array indices (TA-Lib MAXINDEX compatible).
• Tie-breaking: last occurrence wins (most recent bar, >= comparison).
• Cross-validation: source[Maxindex.Batch[i]] == Highest.Batch[i] for all bars after warmup.

MAXINDEX identifies the position of the maximum value within a rolling window. While HIGHEST tells you the peak value, MAXINDEX tells you where that peak is relative to the current bar. This is essential for pattern recognition, timing analysis, and detecting how "stale" a high is.

Historical Context

The MAXINDEX function originates from TA-Lib (TA_MAXINDEX), used in quantitative trading systems to identify when the highest price in a lookback window occurred. This timing information is critical for:

• Breakout freshness: A max at position 0 means the breakout is happening now; at position period-1, the high is stale and fading.
• Pattern detection: Identifying head-and-shoulders, double tops, and other formations requires knowing when peaks occurred.
• Momentum analysis: The position of the high within the window indicates whether momentum is building or decaying.

Architecture & Physics

1. Streaming Mode — Bars-Ago Offset

In streaming mode, the output represents how many bars ago the maximum occurred:

\text{Maxindex}_t = t - \arg\max_{t-n+1 \leq k \leq t} V_k

where n is the lookback period. A value of 0 means the current bar is the maximum; a value of n-1 means the oldest bar in the window holds the maximum.

2. Batch Span Mode — Absolute Index

In the Batch(ReadOnlySpan) method, output is the absolute array index:

\text{output}[i] = \arg\max_{i-n+1 \leq k \leq i} V_k

This matches TA-Lib's MAXINDEX convention and enables direct array lookup: source[output[i]] yields the maximum value.

3. Tie-Breaking

When multiple values in the window are equal to the maximum, the most recent (rightmost) occurrence wins:

\text{Maxindex}_t = \max \{ k : V_k = \max(\text{window}) \}

This is achieved using >= comparison, matching TA-Lib behavior.

4. Monotonic Deque (Batch Mode)

The batch span method uses the same O(n) monotonic deque algorithm as Highest, but outputs the index stored at the deque head rather than the value at that index:

// Highest: output[i] = values[deque.PeekHead()]  → the VALUE
// Maxindex: output[i] = deque.PeekHead()          → the INDEX

5. Bar Correction via Rollback

When isNew=false, the indicator:

1. Restores previous state (_state = _p_state)
2. Replaces the last value in the buffer
3. Re-scans the buffer to find the new maximum position

Mathematical Foundation

Rolling Maximum Index Definition

\text{Maxindex}_t = \arg\max_{t-n+1 \leq k \leq t} V_k

where n is the lookback period and ties are broken in favor of the most recent occurrence.

Partial Window Behavior

Before the window is full:

\text{Maxindex}_t = \arg\max_{0 \leq k \leq t} V_k \quad \text{for } t < n

Complexity Analysis

Operation	Streaming	Batch (Deque)
Per-update (worst)	O(n)	O(n)
Per-update (amortized)	O(n)	O(1)
Total for N updates	O(N×n)	O(N)

Streaming uses a linear scan of the RingBuffer, which is O(period) per bar — acceptable for typical periods (5–30). Batch mode uses the monotonic deque for O(1) amortized.

Performance Profile

Streaming Mode (Linear Scan)

Operation	Count	Cost (cycles)	Subtotal
CMP (scan)	period	1	period
Array access	period	3	3×period
Index arithmetic	2	1	2
Total	—	—	~4×period cycles

Batch Mode (Monotonic Deque)

Operation	Count	Cost (cycles)	Subtotal
CMP (expired check)	1	1	1
CMP (monotonicity)	~2 avg	1	2
Array access	3	3	9
Index arithmetic	2	1	2
Total	~8	—	~14 cycles

Quality Metrics

Metric	Score	Notes
Accuracy	10/10	Exact index of maximum
Timeliness	10/10	Zero lag for index detection
Smoothness	2/10	Discrete jumps as window slides
Computational Cost	8/10	O(period) streaming, O(1) batch
Memory	7/10	O(n) for buffer + deque

Validation

Library	Status	Notes
TA-Lib MAXINDEX	✅	Batch span output matches absolute indices
Cross-validation	✅	source[Maxindex[i]] == Highest[i] for all valid bars
Known Values	✅	Manual verification

Common Pitfalls

1. Two Output Modes: Streaming returns bars-ago offset; Batch(ReadOnlySpan) returns absolute array index. Do not mix them up.

2. Period Minimum is 2: Unlike Highest (which accepts period=1), Maxindex requires period >= 2, since the index of a single element is trivially 0.

3. Tie-Breaking: Uses >= so the most recent (rightmost) occurrence wins ties. This matches TA-Lib convention.

4. Window Boundary Effects: When the previous max expires from the window, the index can jump abruptly. This is expected behavior.

5. Warmup Period: IsHot becomes true after period values. Before warmup, returns index within available data.

6. Using isNew Incorrectly: Use isNew: false only when correcting the current bar. New bars must use isNew: true.

References

• TA-Lib: MAXINDEX function documentation.
• Lemire, Daniel. (2006). "Streaming Maximum-Minimum Filter Using No More than Three Comparisons per Element."
• Tarjan, Robert E. (1985). "Amortized Computational Complexity." SIAM Journal on Algebraic Discrete Methods.