QuanTAlib/lib/oscillators/eeo/Eeo.md

# EEO: Ehlers Elegant Oscillator

> *Where DSO shouts through a megaphone, EEO whispers through a compressor — the Inverse Fisher Transform tames extremes into a clean bounded signal.*

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Oscillator                       |
| **Inputs**       | Source (close)                   |
| **Parameters**   | `bandEdge` (default 20)          |
| **Outputs**      | Single series (Eeo)              |
| **Output range** | Bounded ≈ [-1, +1]              |
| **Warmup**       | `50 + bandEdge` bars             |
| **PineScript**   | [eeo.pine](eeo.pine)            |

- EEO (Elegant Oscillator) applies the Inverse Fisher Transform (tanh) to RMS-normalized 2-bar momentum, then smooths the result with a 2-pole Super Smoother filter, producing a bounded zero-crossing oscillator.
- **Similar:** [DSO](../dso/Dso.md), [RSIH](../rsih/Rsih.md) | **Complementary:** ADX for trend confirmation | **Trading note:** Output bounded ≈ [-1, +1]; ±0.5 levels indicate strong momentum. Unlike DSO (unbounded), EEO compresses extremes via tanh.
- No external validation libraries implement EEO. Validated through self-consistency and behavioral testing.

EEO is Ehlers' 2022 refinement of his earlier DSO (2018). Where DSO applies the Fisher Transform (arctanh) to expand a normalized signal, EEO applies the **Inverse Fisher Transform** (tanh) to compress it. The IFT naturally bounds the output to [-1, +1] without the ±0.99 clamping that DSO requires. A Super Smoother post-filter then removes residual noise. The fixed 50-bar RMS normalization window provides a stable volatility baseline independent of the BandEdge parameter.

## Historical Context

John F. Ehlers published the Elegant Oscillator in the February 2022 issue of *Technical Analysis of Stocks & Commodities* magazine under the title "An Elegant Oscillator: Inverse Fisher Transform Redux." The article presents EEO as a deliberate counterpart to his 2018 Deviation-Scaled Oscillator (DSO). While DSO uses the Fisher Transform (arctanh) to stretch readings near zero into large excursions, EEO uses the Inverse Fisher Transform (tanh) to compress them — producing a naturally bounded output without the artificial clamping that DSO requires.

## Architecture & Physics

### Stage 1: 2-Bar Momentum (Derivative)

$$\text{Deriv} = \text{Close} - \text{Close}[2]$$

This is the same "zeros" whitening used in DSO — it removes DC and Nyquist components, creating a band-limited derivative.

### Stage 2: RMS Normalization (Fixed 50-Bar Window)

$$\text{RMS} = \sqrt{\frac{1}{50}\sum_{k=0}^{49}\text{Deriv}[k]^2}$$

$$\text{NDeriv} = \frac{\text{Deriv}}{\text{RMS}}$$

The fixed 50-bar window (not parameterized) provides a stable normalization base. The RMS measures the "typical" derivative magnitude, so NDeriv represents "how many standard deviations" the current derivative is from zero.

### Stage 3: Inverse Fisher Transform (tanh)

$$\text{IFish} = \tanh(\text{NDeriv}) = \frac{e^{2 \cdot \text{NDeriv}} - 1}{e^{2 \cdot \text{NDeriv}} + 1}$$

The IFT compresses the normalized derivative into [-1, +1]. Values near ±1 indicate extreme momentum relative to recent history.

### Stage 4: Super Smoother Filter (2-Pole Butterworth)

$$a_1 = e^{-1.414\pi / \text{BandEdge}}$$

$$b_1 = 2 \cdot a_1 \cdot \cos\!\left(\frac{1.414 \cdot 180°}{\text{BandEdge}}\right)$$

$$c_2 = b_1, \quad c_3 = -a_1^2, \quad c_1 = 1 - c_2 - c_3$$

$$\text{SS} = \frac{c_1}{2}(\text{IFish} + \text{IFish}[1]) + c_2 \cdot \text{SS}[1] + c_3 \cdot \text{SS}[2]$$

The Super Smoother removes high-frequency chatter from the IFT output while preserving the phase relationship.

## Performance Profile

### Operation Count (Streaming Mode, Scalar)

| Operation               | Count | Notes                          |
|:----------------------- |:----- |:------------------------------ |
| Subtraction (Deriv)     | 1     | Close - Close[2]               |
| Multiply (deriv²)       | 1     | For RMS buffer                 |
| RingBuffer add/remove   | 1     | O(1) circular buffer           |
| FMA (running sum)       | 1     | SumSq update                   |
| Sqrt (RMS)              | 1     | √(sum/50)                      |
| Division (normalize)    | 1     | Deriv / RMS                    |
| Exp + tanh (IFT)        | 1     | Math.Tanh()                    |
| FMA × 2 (SSF)           | 2     | 2-pole recursive filter        |
| **Total per bar**       | **~9** | Constant O(1)                 |

### Batch Mode (SIMD Analysis)

The algorithm's IIR Super Smoother stage prevents full vectorization. Batch mode processes sequentially but avoids per-bar allocation overhead.

### Quality Metrics

| Metric              | Score | Notes                                    |
|:------------------- |:----- |:---------------------------------------- |
| Lag                 | Low   | SSF has minimal phase distortion         |
| Noise rejection     | High  | IFT compression + SSF smoothing          |
| Sensitivity         | High  | 2-bar derivative is very responsive      |
| Bounded output      | Yes   | ≈ [-1, +1] from tanh                    |
| Parameter count     | 1     | Only BandEdge                            |

## Validation

EEO is validated through self-consistency tests (streaming ≡ batch ≡ span ≡ eventing) and behavioral tests (constant input → 0, trending → non-zero, symmetry).

### Behavioral Test Summary

| Test                    | Expected Result           |
|:----------------------- |:------------------------- |
| Constant input          | Output → 0               |
| Strong uptrend          | Output > 0               |
| Strong downtrend        | Output < 0               |
| Ascending vs descending | Opposite signs            |
| NaN/Inf input           | Finite output (fallback)  |
| Bar correction (isNew)  | State restored correctly  |

## Common Pitfalls

1. **Fixed RMS window**: The 50-bar window is hardcoded per Ehlers' specification. Do not parameterize it — it provides a stable normalization base independent of BandEdge.

2. **BandEdge vs Period**: BandEdge is the Super Smoother cutoff, not an RMS lookback. Higher BandEdge = more smoothing but more lag.

3. **Bounded output**: Unlike DSO (which uses Fisher Transform producing unbounded output), EEO output is bounded to ≈ [-1, +1]. Signal levels of ±0.5 are typical thresholds, not ±2 as with DSO.

4. **Warmup**: Requires 50 + BandEdge bars. The first 50 bars fill the RMS window; then BandEdge more bars are needed for SSF convergence.