ABS Companion Oscillator — Trend / Exhaustion / New Trend (v1.1)

# ABS Companion Oscillator — Trend / Exhaustion / New Trend (v1.1)

## What it is (quick take)

**ABS CO** is a unified **–100…+100 trend oscillator** that fuses:

* **Regime**: EMA stack (fast/slow/long) + **HTF slope** (e.g., 60-minute)
* **Momentum**: **TSI** vs its signal
* **Stretch**: session-anchored **VWAP Z-score** for exhaustion and “fresh-trend” sanity checks

It paints the oscillator with **lime** in upstate, **red** in downstate, **gray** in neutral, and tags:

* **NEW↑ / NEW↓** when a **new trend** likely starts (zero-line cross with acceptable stretch)
* **EXH↑ / EXH↓** when an **existing trend looks exhausted** (large |Z| + momentum rollback)

> Use it as a **direction filter and context layer**. Works great in front of an entry engine and behind an exit tool.

---

## How to use it (operational workflow)

1. **Read the state**

* **Uptrend** when the oscillator is **≥ upThresh** (default +55) → prefer **long-side** plays.
* **Downtrend** when the oscillator is **≤ dnThresh** (default −55) → prefer **short-side** plays.
* **Neutral** between thresholds → be selective or flat; expect chop.

2. **Act on events**

* **NEW↑ / NEW↓**: zero-line cross with acceptable |Z| (not already overstretched). Treat as **trend start** cues.
* **EXH↑ / EXH↓**: trend state with **high |Z|** and TSI rollback versus its signal. Treat as **trend fatigue**; avoid fresh go-with entries and tighten risk.

3. **Practical pairing**

* Use **up/down state** (or above/below **neutralBand**) as your go/no-go filter for entries.
* Prioritize entries **with** NEW↑/NEW↓ and **without** nearby EXH tags.
* Keep holding while the oscillator stays in state and no EXH appears; consider scaling out on EXH or on your exit tool.

---

## Visual semantics & alerts

* **ABS CO line** (–100…+100): lime in upstate, red in downstate, gray in neutral.
* **Horizontal guides**: `Up` threshold, `Down` threshold, `Zero`, and optional **neutral band** lines.
* **Background heat** (optional): shaded when EXH conditions trigger (lime/red tint with intensity scaled by |Z|).
* **Tags**: `NEW↑`, `NEW↓`, `EXH↑`, `EXH↓`.

**Alerts (stable):**

* **ABS CO — New Uptrend** (NEW↑)
* **ABS CO — New Downtrend** (NEW↓)
* **ABS CO — Exhausted Up** (EXH↑)
* **ABS CO — Exhausted Down** (EXH↓)

Set alerts to **“Once per bar close”** for clean signals.

---

## Non-repainting behavior

* HTF queries use **lookahead\_off**.
* With **Strict NR = true**, the HTF slope is taken from the **prior completed** HTF bar; events evaluate on confirmed bars → **safer, fewer, cleaner**.
* NEW/EXH tags finalize at bar close. Disabling strictness yields earlier but noisier responses.

---

## Every input explained (and how it changes behavior)

### A) Trend & HTF structure

* **EMA Fast / Slow / Long (`emaFastLen`, `emaSlowLen`, `emaLongLen`)**
Control the baseline regime. Larger = smoother, fewer flips; smaller = snappier, more flips.
* **HTF EMA Len (`htfLen`)** & **HTF timeframe (`htfTF`)**
HTF slope filter. Longer len or higher TF = steadier bias (fewer state changes); shorter/ lower = more sensitive.
* **Strict NR (`strictNR`)**
`true` uses the **previous** HTF bar for slope and evaluates on confirmed bars → cleaner, slower.

### B) Momentum (TSI)

* **TSI Long / Short / Signal (`tsiLong`, `tsiShort`, `tsiSig`)**
Standard TSI. Larger values = smoother momentum, fewer EXH triggers; smaller = snappier, more EXH sensitivity.

### C) Stretch (VWAP Z-score)

* **VWAP Z-score length (`zLen`)**
Window for Z over session-anchored VWAP distance. Larger = smoother |Z|; smaller = more reactive stretch detection.
* **Exhaustion |Z| (`zHot`)**
Minimum |Z| to flag **EXH**. Raise to demand **bigger** stretch (fewer EXH); lower to catch milder excess.
* **Max |Z| for NEW (`zNewMax`)**
NEW requires |Z| **≤ zNewMax** (avoid “new trend” when already stretched). Lower = stricter; higher = more NEW tags.

### D) States & thresholds

* **Uptrend threshold (`upThresh`)** / **Downtrend threshold (`dnThresh`)**
Where the oscillator flips into trend states. Widen (e.g., +60/−60) to reduce false states; narrow to get earlier signals.
* **Neutral band (`neutralBand`)**
Visual buffer around zero for “meh” momentum. Larger band = fewer go/no-go flips near zero.

### E) Visuals & tags

* **Show New / Show Exhausted (`showNew`, `showExh`)**
Toggle the tag labels.
* **Shade exhaustion heat (`plotHeat`)**
On = color background when EXH fires. Helpful for scanning.

### F) Smoothing

* **Osc smoothing (`smoothLen`)**
EMA over the raw composite. Higher = steadier line (fewer whip flips); lower = faster turns.

---

## Tuning recipes

* **Trend-day bias (follow moves longer)**

* Raise **`upThresh`** to \~60 and **`dnThresh`** to \~−60
* Keep **`zNewMax`** low (1.0–1.2) to avoid “fresh trend” when stretched
* **`smoothLen`** 3–5 to reduce noise

* **Range-day bias (fade edges)**

* Keep thresholds closer (e.g., +50/−50) for quicker state changes
* Lower **`zHot`** slightly (1.6–1.7) to catch earlier exhaustion
* Consider slightly shorter TSI (e.g., 21/9/5) for faster EXH response

* **Scalping LTF (1–3m)**

* TSI 21/9/5, **`smoothLen`** 1–2
* Thresholds +/-50; **`zNewMax`** 1.0–1.2; **`zHot`** 1.6–1.8
* StrictNR **off** if you want earlier calls (accept more noise)

* **Swing / HTF (1h–D)**

* TSI 35/21/9, **`smoothLen`** 4–7
* Thresholds +/-60\~65; **`zNewMax`** 1.2; **`zHot`** 1.8–2.0
* StrictNR **on** for cleaner bias

---

## Playbooks (how to actually trade it)

* **Go/No-Go Filter**

* Only take **long entries** when the oscillator is **above the neutral band** (preferably ≥ `upThresh`).
* Only take **short entries** when **below** the neutral band (preferably ≤ `dnThresh`).
* Avoid fresh go-with entries if an **EXH** tag appears; let the next setup re-arm.

* **Trend Genesis**

* Treat **NEW↑ / NEW↓** as “green light” for **first pullback** entries in the new direction (ideally within acceptable |Z|).

* **Trend Maturity**

* When in a position and **EXH** prints **against** you, tighten stops, take partials, or lean on your exit tool to protect gains.

---

## Suggested starting points

* **Day trading (5–15m):**

* TSI 25/13/7, `smoothLen=3`, thresholds **+55 / −55**, `zNewMax = 1.2`, `zHot = 1.8`, **StrictNR = true**

* **Scalping (1–3m):**

* TSI 21/9/5, `smoothLen=1–2`, thresholds **+50 / −50**, `zNewMax = 1.1–1.2`, `zHot = 1.6–1.8`, **StrictNR = false** (optional)

* **Swing (1h–D):**

* TSI 35/21/9, `smoothLen=4–6`, thresholds **+60 / −60**, `zNewMax = 1.2`, `zHot = 1.9–2.0`, **StrictNR = true**

---

## Notes & best practices

* **Session anchoring**: Z-score is session-anchored (resets by trading date). If you trade outside standard sessions, verify your data session.
* **Instrument specificity**: Tune **`zHot`**, **`zNewMax`**, and thresholds per symbol and timeframe.
* **Bar-close discipline**: Evaluate tags at **bar close** to avoid intrabar flip-flop.
* This is a **context/confirmation tool**, not a broker or strategy. Combine with your entry/exit rules and position sizing.

---

**Tip:** Start with the suggested day-trading profile. Use this oscillator as your **gate** (only trade with it), let your entry engine time executions, and rely on your exit tool for standardized profit-taking.