QuanTAlib/lib/channels/maenv/maenv.md

MAENV: Moving Average Envelope

"The simplest channels are often the most useful - a percentage above and below tells you when price is stretched."

The Moving Average Envelope (MAENV) creates a fixed percentage-based channel around a selectable moving average. Unlike volatility-adaptive channels like Keltner or Bollinger Bands, MAENV maintains constant proportional distance from the middle line, making it useful for mean-reversion strategies where you expect price to oscillate within predictable bounds.

Historical Context

Moving Average Envelopes are among the oldest channel indicators, predating volatility-based bands by decades. The concept is straightforward: if price tends to revert to a moving average, then defining zones at fixed percentages above and below that average provides natural support and resistance levels.

The choice of moving average type affects responsiveness:

• SMA: Equal weighting creates stable, predictable bands but slower reaction to price changes
• EMA: Exponential weighting responds faster to recent prices, making bands more dynamic
• WMA: Linear weighting provides a middle ground, emphasizing recent data without the sharp responsiveness of EMA

This implementation offers all three options, letting traders choose the smoothing behavior that matches their strategy.

Architecture & Physics

1. Moving Average Calculation

The middle band is computed using the selected MA type:

SMA (Simple Moving Average) - O(1) streaming via ring buffer:

\text{SMA}_t = \frac{1}{n} \sum_{i=0}^{n-1} P_{t-i}

Implementation uses circular buffer to maintain running sum, achieving constant-time updates.

EMA (Exponential Moving Average) - O(1) with warmup compensation:

\alpha = \frac{2}{n+1}

\text{sum}_t = \text{sum}_{t-1}(1-\alpha) + P_t \cdot \alpha

\text{weight}_t = \text{weight}_{t-1}(1-\alpha) + \alpha

\text{EMA}_t = \frac{\text{sum}_t}{\text{weight}_t}

Warmup compensation ensures accurate values from the first bar by tracking both weighted sum and weight.

WMA (Weighted Moving Average) - O(n):

\text{WMA}_t = \frac{\sum_{i=0}^{n-1} w_i \cdot P_{t-i}}{\sum_{i=0}^{n-1} w_i}

where w_i = (n-i) \times n giving highest weight to most recent values.

2. Band Calculation

Bands are symmetric percentage-based offsets:

\text{dist}_t = \text{Middle}_t \times \frac{\text{percentage}}{100}

\text{Upper}_t = \text{Middle}_t + \text{dist}_t

\text{Lower}_t = \text{Middle}_t - \text{dist}_t

Mathematical Foundation

Band Width Formula

Total band width scales linearly with both the middle value and percentage parameter:

\text{Width}_t = \text{Upper}_t - \text{Lower}_t = 2 \times \text{Middle}_t \times \frac{\text{percentage}}{100}

This creates proportional bands - a 2% envelope means bands are always 4% of the middle value apart.

EMA Warmup Derivation

Traditional EMA initialization (EMA_0 = P_0) creates bias when the first value differs significantly from subsequent values. The warmup compensation tracks:

\text{theoretical\_weight} = \alpha \sum_{i=0}^{t} (1-\alpha)^i = 1 - (1-\alpha)^{t+1}

By dividing sum by actual accumulated weight, the EMA converges to the true value faster and without initialization bias.

Performance Profile

Operation Count (Streaming Mode)

MA Type	Per-Bar Cost	Memory	Complexity
SMA	~5 ops	O(n) buffer	O(1)
EMA	~8 ops	O(1) scalars	O(1)
WMA	~3n ops	O(n) buffer	O(n)

SMA and EMA achieve constant-time streaming updates. WMA requires linear time due to weighted sum recalculation.

Batch Mode Performance

For batch processing of 1000 values:

MA Type	Streaming	Batch (SIMD)	Speedup
SMA	~5000 ops	~5000 ops	1×
EMA	~8000 ops	~8000 ops	1×
WMA	~3M ops	~3M ops	1×

Limited SIMD benefit due to recursive nature of MA calculations.

Quality Metrics

Metric	Score	Notes
Accuracy	10/10	Exact percentage-based calculation
Timeliness	7/10	Depends on MA type (EMA fastest)
Stability	9/10	No volatility-driven expansion
Predictability	10/10	Constant proportional width

Validation

Library	Status	Notes
TA-Lib	N/A	No direct equivalent
Skender	N/A	No direct equivalent
Tulip	N/A	No direct equivalent
Ooples	N/A	No direct equivalent
PineScript	✅	Reference implementation match

Validation performed against internal manual calculations and PineScript reference. No external library provides identical multi-MA-type envelope implementation.

Common Pitfalls

1. MA Type Selection: SMA provides most stable bands but slowest response. EMA responds quickly but may whipsaw. WMA balances both but costs O(n) per update.

2. Percentage Calibration: Optimal percentage varies by instrument volatility. Highly volatile assets need wider envelopes (3-5%), stable assets work with narrow bands (0.5-1%).

3. False Breakouts: Fixed percentage bands don't adapt to volatility regime changes. Price may consistently breach bands during high-volatility periods.

4. Warmup Period: All MA types need period bars for full accuracy. EMA warmup compensation accelerates convergence but initial bars still have reduced effective lookback.

5. Memory Footprint: SMA and WMA require period-sized buffers (~8 bytes × period per instance). EMA uses only scalar state (~32 bytes total).

6. Bar Correction (isNew=false): State restoration copies entire buffer for SMA/WMA. For large periods, this adds latency to tick-by-tick updates.

References

• Murphy, J.J. (1999). Technical Analysis of the Financial Markets. New York Institute of Finance.
• TradingView. "Moving Average Envelope." Pine Script Reference.