QuanTAlib/lib/numerics/lowest/Lowest.md

# LOWEST: Rolling Minimum

> *Know your floor. Support levels are just historical minimums waiting to be tested.*

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Numeric                        |
| **Inputs**       | Source (close)                          |
| **Parameters**   | `period`                      |
| **Outputs**      | Single series (Lowest)                       |
| **Output range** | Varies (see docs)                     |
| **Warmup**       | `period` bars                          |
| **PineScript**   | [lowest.pine](lowest.pine)                       |

- LOWEST calculates the minimum value over a rolling lookback window.
- **Similar:** [Highest](../highest/Highest.md), [MinIndex](../minindex/Minindex.md) | **Trading note:** Rolling minimum; identifies support levels and breakdown points.
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.

LOWEST calculates the minimum value over a rolling lookback window. This O(1) amortized streaming implementation uses a monotonic deque algorithm, enabling real-time updates without re-scanning the entire window. Validated against TA-Lib MIN and Tulip min functions.

## Historical Context

Rolling minimum is fundamental to technical analysis—support detection, drawdown calculation, and trailing stop placement all depend on tracking minimum values efficiently. The naive approach scans all values in the window on each update, requiring O(n) time per bar.

The monotonic deque algorithm, popularized by Lemire (2006), reduces this to O(1) amortized time by maintaining an increasing sequence of candidates. Values that can never become the minimum (because they're larger and will expire before smaller values) are immediately discarded.

QuanTAlib implements this optimal algorithm with full streaming support, SIMD batch optimization, and proper state management for bar corrections.

## Architecture & Physics

### 1. Monotonic Deque

The core data structure is a deque maintaining indices of values in monotonically increasing order:

$$
\text{deque} = [i_1, i_2, \ldots, i_k] \quad \text{where} \quad V_{i_1} \leq V_{i_2} \leq \cdots \leq V_{i_k}
$$

The front of the deque always holds the index of the minimum value in the current window.

### 2. Update Algorithm

On each new value $V_t$:

1. **Remove expired**: Pop indices from front if `index <= t - period`
2. **Maintain monotonicity**: Pop indices from back while `V[back] >= V_t`
3. **Add new**: Push current index $t$ to back
4. **Result**: Front of deque is the minimum's index

```
Window: [5, 2, 7, 3, 6]  Period: 5
Deque:  [1, 3]           // Index 1=2 (min), Index 3=3
        
Add 4 at index 5:
Deque:  [1, 3, 5]        // 2 < 3 < 4, keep all
        
Add 1 at index 6:
Deque:  [6]              // 1 < all others, 1 dominates
```

### 3. 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. Rebuilds the deque by scanning the buffer

This maintains correctness for real-time bar updates.

## Mathematical Foundation

### Rolling Minimum Definition

$$
\text{Lowest}_t = \min(V_{t-n+1}, V_{t-n+2}, \ldots, V_t)
$$

where $n$ is the lookback period.

### Partial Window Behavior

Before the window is full:

$$
\text{Lowest}_t = \min(V_0, V_1, \ldots, V_t) \quad \text{for } t < n
$$

### Complexity Analysis

| Operation | Naive | Monotonic Deque |
| :--- | :---: | :---: |
| Per-update (worst) | O(n) | O(n) |
| Per-update (amortized) | O(n) | O(1) |
| Total for N updates | O(N×n) | O(N) |

Each element is pushed and popped from the deque at most once across all operations.

## Performance Profile

### Operation Count (Streaming Mode, Amortized)

| 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** |

### Batch Mode (SIMD)

For batch processing, SIMD can parallelize comparisons within segments. However, the monotonic deque's sequential nature limits full vectorization. The span-based Calculate method uses a stackalloc deque buffer for cache efficiency.

### Quality Metrics

| Metric | Score | Notes |
| :--- | :---: | :--- |
| **Accuracy** | 10/10 | Exact minimum |
| **Timeliness** | 10/10 | Zero lag for minima |
| **Smoothness** | 2/10 | Step changes at window boundaries |
| **Computational Cost** | 9/10 | O(1) amortized |
| **Memory** | 7/10 | O(n) for buffer + deque |

## Validation

| Library | Status | Notes |
| :--- | :---: | :--- |
| **TA-Lib MIN** | ✅ | Exact match |
| **Tulip min** | ✅ | Exact match |
| **Known Values** | ✅ | Manual verification |

## Common Pitfalls

1. **Window Boundary Effects**: Minimum changes abruptly when the previous min expires from the window. This creates step changes in the output.

2. **Warmup Period**: `IsHot` becomes true after `period` values. Before warmup, returns minimum of available data.

3. **Memory Footprint**: O(n) memory for both the ring buffer and deque indices. For period=200: ~3.2KB (200 doubles + 200 ints).

4. **Deque Rebuild on Correction**: When `isNew=false`, the entire deque is rebuilt by scanning the buffer. Frequent corrections are O(n) each.

5. **Support Level Detection**: The minimum often acts as support, but LOWEST reports raw values, not significance levels. Consider combining with volume or multiple timeframes.

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

## References

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