ATO - Adaptive trend Oscillator

ATO/MCL Color Coding — Deep Dive User Guide (Confidential Components Obfuscated)

Purpose: A practical, scenario‑driven manual that teaches users exactly what each color, line, and crossing signifies, and how to act on them—without revealing underlying indicator components. This expands on the basics in Color‑Code‑Guide.md and mirrors the behavior spec in Color‑Code.md.

Audience: Traders of all experience levels. Keep this open beside your charts.

---

Quick Settings Reference (names and how to use them)

Signal Candle Settings
- Signal Core Sensitivity
- Purpose: Controls how reactive the internal signal candle is.
- Increase/Decrease: Higher = smoother/slower; lower = faster/more responsive.
- Trading: Higher reduces noise but can lag; lower catches early shifts but may whipsaw.
- Open Blend Smoothing
- Purpose: Blends the candle’s open values to reduce jitter.
- Increase/Decrease: Higher = fewer false flips; lower = sharper turns/more detail.
- Trading: Higher favors stability; lower highlights micro‑structure.

Multi‑Core Blending
- Enable Multi‑Core Blending
- Purpose: Combines multiple signal horizons for robustness.
- Increase/Decrease: Toggle On for smoother behavior across regimes; Off for single‑core speed.
- Trading: On favors consistency; Off emphasizes reactivity.
- Core A/B/C Horizon
- Purpose: Control fast/balanced/deep horizons in the blend.
- Increase/Decrease: Higher = smoother; lower = quicker reactions.
- Trading: Tune per timeframe; mix for balance of timeliness vs stability.

Adaptive Action Bands
- Enable Adaptive Action Bands
- Purpose: Dynamic upper/lower decision bands that adapt to environment.
- Trading: On = bands scale to volatility; Off = fixed levels.
- Upper Band Base / Lower Band Base
- Purpose: Baselines for upper/lower bands.
- Increase/Decrease: Higher demands stronger moves to tag; lower increases sensitivity.
- Trading: Higher filters shallow extremes; lower surfaces more signals.
- Regime Reactivity
- Purpose: How strongly bands react to volatility changes.
- Increase/Decrease: Higher = faster expansion/contraction; lower = steadier bands.
- Trading: Higher tracks fast markets; lower avoids overreacting.
- Distribution Window
- Purpose: Anchor bands to recent behavior.
- Increase/Decrease: Larger = slower, stable anchors; smaller = faster, adaptive anchors.
- Trading: Larger for swing; smaller for scalps.
- Upper/Lower Anchor Level
- Purpose: Position of the upper/lower anchor within recent behavior.
- Increase/Decrease: Higher pushes bands farther; lower tightens thresholds.
- Trading: Higher reduces frequent signals; lower increases sensitivity.
- Trend Bias Strength / Bias Memory Window
- Purpose: Asymmetric tilt and how quickly tilt adapts.
- Increase/Decrease: Strength higher tilts more; memory longer adapts slower.
- Trading: Higher favors continuation; longer stabilizes bias; shorter captures quick rotations.
- Confidence Tightening / Compression Reactivity
- Purpose: Narrow bands when signals are confident or during compression.
- Increase/Decrease: Higher tightens more; lower stays neutral.
- Trading: Higher highlights strong trends or pre‑breakout states; lower reduces false narrowing.

Stability Engine
- Show Confidence Layers
- Purpose: Displays layered stability envelopes around the core signal.
- Trading: Visualizes reliability and risk zones.
- Enable Stability Smoothing
- Purpose: Adaptive smoothing to reduce noise while preserving structure.
- Increase/Decrease: On = cleaner lines; Off = raw movement.
- Trading: On clarifies context; Off emphasizes immediacy.
- Model Flexibility
- Purpose: How freely the model adjusts to new information.
- Increase/Decrease: Higher = faster adaptation; lower = steadier behavior.
- Trading: Higher tracks regime shifts; lower avoids overfitting.
- Signal Trust Level
- Purpose: How much the engine trusts the raw signal.
- Increase/Decrease: Higher = rely less on noisy ticks; lower = follow raw moves more closely.
- Trading: Higher smooths choppiness; lower emphasizes immediacy.
- Base Layer Width
- Purpose: Baseline width of stability layers around the core.
- Increase/Decrease: Higher = broader cushions; lower = tighter envelopes.
- Trading: Broader layers indicate wider risk tolerance.

Trend Memory
- Enable Trend Memory
- Purpose: Activates a persistence layer that rewards continuous directional flow.
- Trading: Helps distinguish noise from sustained motion.
- Memory Fade Speed
- Purpose: How quickly prior movement influence fades.
- Increase/Decrease: Higher = faster forgetting; lower = retain past momentum longer.
- Trading: Tune to market tempo.
- Consistency Requirement
- Purpose: Bars in the same direction needed to reach full consistency.
- Increase/Decrease: Higher = demand stronger sequences; lower = recognize shorter bursts.

Core Line & Envelope
- Core Line Source
- Purpose: Base price source the core line derives from.
- Increase/Decrease: Use blended sources (OHLC4) for stability; Close for immediacy.
- Trading: Stability vs responsiveness trade‑off.
- Smooth Core Line / Core Line Smoothing Window
- Purpose: Reduce jitter while preserving structure.
- Increase/Decrease: Longer window = smoother but slower; shorter = sharper detail.
- Trading: Longer lags reactive moves; shorter captures micro‑shifts.
- Envelope Base Window
- Purpose: Base window to build the dynamic envelope around the core line.
- Increase/Decrease: Higher = broader, slower envelopes; lower = tighter, faster envelopes.
- Trading: Wider envelopes reduce frequent touches; tighter envelopes surface more interactions.
- Envelope Expansion Factor
- Purpose: Controls how wide the envelope expands from its midline.
- Increase/Decrease: Higher = wider bands/fewer touches; lower = tighter/more interactions.
- Trading: Wider for trend; tighter for precision reversion.
- Envelope Midline Type
- Purpose: Midline calculation style for the envelope.
- Trading: Choose smoother types for stability or faster types for responsiveness.

Visual & Display Settings
- Show Core Line / Show Envelope Fill / Show Adaptive Zones / Visual Theme
- Purpose: Control visibility and theme.
- Trading: Adjust to environment; keep colors consistent for fast reading.

---

Foundations: Components and their color meanings

- Signal Candles (internal)
- bull_strong (green family): Bullish body above zero ⇒ trend‑friendly context
- bull_weak (tinted green): Bullish body below zero ⇒ bullish impulse but weaker context
- bear_strong (red family): Bearish body below zero ⇒ trend‑friendly bearish context
- bear_weak (tinted red): Bearish body above zero ⇒ bearish impulse but weaker context
- Opacity = confidence tier:
- <40 → 70% transp (faint), 40–64 → 40%, 65–84 → 20%, ≥85 → 10% (bold)
- Core Line
- core_bull when rising this bar; core_bear when falling this bar
- Opacity tightens as confidence rises; soft shadow adds depth
- Dynamic Envelope (around Core Line)
- Basis color: primary (rising) vs secondary (falling)
- Fills: yellow (compression), green (diverging/expanding), red (converging/contracting), subtle primary otherwise
- Adaptive Action Bands (upper/lower)
- Dynamic guardrails based on distribution anchors, trend bias, confidence, and compression
- Stability Layers
- Gradient from low→high confidence around the line; width reflects uncertainty

---

Guided reading: A step‑by‑step method

1) Identify regime via envelope fill:
- Yellow compression ⇒ energy build; prepare for breakout
- Green diverging ⇒ expansion/trend continuation risk
- Red converging ⇒ consolidation/mean‑reversion bias
2) Check line vs basis:
- Cross up (basis rising) = early bullish impulse; cross down (basis falling) = early bearish impulse
3) Read candle state and opacity:
- Prefer signals where hue (bull/bear) and context (above/below zero) agree with basis slope + higher opacity (confidence)
4) Use Adaptive Action Band interactions to decide trend vs mean‑reversion tactics

---

Pattern library — high‑probability scenarios

A) Compression Breakout (Trend Birth)
- Visuals: Yellow fill, line crosses above basis; candles shift bull_weak → bull_strong; opacity improves
- Interpretation: Pressure release; early trend formation
- Playbook: Breakout entries; trail using basis or prior swing; avoid fading extremes initially

B) Trend Continuation (Expansion)
- Visuals: Green fill (diverging), basis colored primary (rising), line holds above basis; candles persist bull_strong with low transp
- Interpretation: Momentum alignment across components
- Playbook: Buy pullbacks to basis/inner stability layer; scale out near Adaptive Action Band re‑tests

C) Mean‑Reversion Window (Re‑entry)
- Visuals: Line breaches upper/lower band then re‑enters while fill turns red (converging); candle opacity loosens
- Interpretation: Expansion cooling; revert‑to‑mean opportunity
- Playbook: Fade back toward basis/center; tighten risk if green fill returns

D) Failed Breakout (Fade Trap)
- Visuals: Line wicks beyond bands without support from basis slope (basis stays secondary), candles flip color quickly with low confidence
- Interpretation: Breakout lacked breadth
- Playbook: Fade the failure back toward basis; confirm with red fill or weak opacity

E) Zero‑Line Upgrade/Downgrade
- Visuals: Candle crosses zero (weak→strong or strong→weak of opposite side)
- Interpretation: Context upgrade/downgrade of the same direction
- Playbook: Join only when basis slope agrees; skip if basis contradicts and fill is red

F) Chop Filter (Avoid Zone)
- Visuals: Frequent line‑basis crossovers, alternating candle hues, red fill dominance, low confidence (high transparency)
- Interpretation: No edge; whipsaw risk
- Playbook: Stand aside or reduce size; wait for compression or alignment

---

Crossings — what they mean and how to analyze them

- Line × Basis
- Cross up with rising basis (primary) ⇒ constructive momentum shift
- Cross down with falling basis (secondary) ⇒ deteriorating momentum
- Repeated crosses with red fill ⇒ chop
- Line × Upper/Lower Action Bands
- Touch/near upper during green fill ⇒ healthy expansion; continuation bias
- Touch/near lower during green fill ⇒ downside expansion; continuation bias
- Touch during yellow ⇒ breakout watch
- Line × Adaptive Action Bands
- Breach outside with green fill ⇒ trend regime; don’t fade blindly
- Re‑enter with red fill ⇒ mean‑reversion opportunity
- Candle × Zero Line
- Upgrade to bull_strong above zero or bear_strong below zero strengthens signal context

Reading tips:
- Always cross‑check: crossing → basis slope → fill color → candle hue/opacity
- More components in agreement = higher conviction

---

Behavior correlations (what moves cause what visuals)

- Confidence ↑ ⇒ Candle/body opacity ↓ (more visible), core line opacity ↓; often coincides with alignment (line above a rising basis or below a falling basis)
- Basis slope change ⇒ Basis color flips (primary/secondary) and often precedes candle context upgrades/downgrades
- Fill transitions:
- Yellow → Green ⇒ breakout → expansion
- Green → Red ⇒ expansion cooling → consolidation
- Action Band interactions:
- Persistent stay outside with green fill ⇒ trend maturity; use pullback entries
- Quick pop‑and‑back with red fill ⇒ mean reversion favored

---

Tuning and customization

- Confidence tiers (40/65/85): Keep structure; you may shift thresholds slightly but preserve four‑step progression
- Line visibility: Raise/lower minimum opacity cautiously (default 10%) for background contrast
- Envelope fills: If visually heavy, increase transparency but keep event→color mapping (yellow compression, green diverge, red converge)
- Themes: Choose by environment (Light/Dark/Dusk/Night). For accessibility, convert bull/bear to blue/orange while keeping the same logic
- Action Bands: Adjust colors to match your theme but keep the adaptive engine intact

---

Troubleshooting interpretation

- “Two panes don’t match” → Ensure identical theme struct, opacity tiers, wick/border rules, and basis slope logic
- “Too many false signals” → Demand confluence: rising basis + line above + bull_strong candles + green fill
- “I can’t see the details” → Lower transparencies (more opaque) or switch theme; verify display toggles
- “Bands cross” → Rare in extremes; prioritize fill regime + basis slope + candle opacity for decisions
- “Whipsaw hell” → If red fill dominates and crosses pile up, stand aside until compression or clear alignment appears

---

Practical playbooks (ready‑to‑use)

- Breakout Playbook
- Preconditions: Yellow compression → cross up; basis turns/stays primary; candles upgrade toward bull_strong; confidence rising
- Entry: Break of recent line swing high
- Risk: Stop below basis/last swing; trail with basis or inner layer
- Exit: Partial into Action Band retests; exit on red fill return + basis roll‑over

- Pullback Continuation
- Preconditions: Green fill; line above rising basis; bull_strong candles
- Entry: Pullback to basis/inner layer
- Risk/Exit: Stop under basis; scale out into prior high or band re‑touch; exit on basis slope flip

- Mean‑Reversion Fade
- Preconditions: Line re‑enters from bands while fill turns red and candles lose opacity
- Entry: Toward basis/center; conservative size in strong trends
- Exit: At basis or when green fill resumes

---

Implementation parity across panes

- Port the same Theme struct and theme selector
- Reuse candle hue matrix (bull/bear × above/below zero) and confidence tiers
- Implement basis slope → primary/secondary mapping and fill regime logic
- Keep wick = body color; border = same hue, 0% transparency
- Validate with side‑by‑side charts for identical inputs and market

Keep this deep dive as your operational manual; it explains what you see and how to act. Once internalized, it will accelerate confluence recognition and decision‑making under live conditions.

Adaptive Action Bands — Calculation, Behavior, and Crossings

This section explains exactly how the Adaptive Action Bands are computed and how to interpret their movements and rare crossings.

A) What they represent
- Dynamic guardrails around the core line, adapting to recent distribution anchors, current trend bias, confidence, and compression state.
- Purpose: separate trend vs mean‑reversion regimes and scale thresholds to volatility and context.

B) The calculation (plain‑English and formulas)
1) Distribution anchors
- upper_baseline = Percentile(core_line, lookback = Distribution Window, p = Upper Anchor Level)
- lower_baseline = Percentile(core_line, lookback = Distribution Window, p = Lower Anchor Level)
- center = (upper_baseline + lower_baseline) / 2
- range = |upper_baseline − lower_baseline|; halfband = range / 2
2) Confidence tightening (narrow when signals are confident)
- stdev_core = StdDev(core_line, 50)
- tighten_adjust = stdev_core × Confidence Tightening × (signal_confidence / 100)
3) Compression adjustment (narrow more during quiet states)
- envelope_width_avg = SMA(envelope_width, 50); compression = max(0, 1 − envelope_width / max(envelope_width_avg, 0.0001))
- compression_adjust = stdev_core × Compression Reactivity × compression × Regime Reactivity
4) Trend bias (asymmetric push by prevailing trend)
- bias_ema = EMA(core_line, Bias Memory Window)
- bias = tanh(bias_ema / 100); bias_shift = bias × Trend Bias Strength
5) Effective distance and candidate levels
- distance = max(5.0, halfband − tighten_adjust − compression_adjust) // minimum gap guard
- upper_candidate = center + distance + bias_shift × halfband
- lower_candidate = center − distance − bias_shift × halfband
6) Final clamp and enable
- upper_action = clamp(upper_candidate, −100, 100)
- lower_action = clamp(lower_candidate, −100, 100)
- If adaptive disabled, use fixed base levels instead.

C) Why the bands sometimes CROSS (and what it means)
- Effective spread between bands = (upper − lower) = 2 × distance + 2 × bias_shift × halfband.
- If strong negative bias (bias_shift ≪ 0) and large halfband combine with tightening (small distance), the spread can compress and flip sign (rare), causing temporary inversion.
- Interpretation: “Dominant trend override.” The engine signals an extreme asymmetric regime where trend force overwhelms symmetric mean‑reversion guardrails.
- Practical takeaway: Treat it as a trend regime warning. Do not fade blindly; prefer continuation tactics or wait for re‑normalization.

D) Reading the patterns around Action Bands
- Approach without breach: Build‑up toward a boundary; look for fill color (green diverging supports continuation, red converging favors mean‑revert).
- Breach outside + green fill: Strong trend state; continuation entries on pullbacks are favored; mean‑reversion is lower probability.
- Re‑entry from outside + red fill: Expansion cooling; mean‑reversion window opens; look for moves back toward center/basis.
- Temporary inversion (crossing): Extreme bias; treat as trend override; either wait for bands to normalize or align trades with trend only.

E) Tuning knobs and how they affect behavior
- Trend Bias Strength (default 1.5):
- Higher = more asymmetric push; increases inversion risk in extremes
- Lower = more symmetric bands; reduces inversion likelihood
- Confidence Tightening (default 0.8):
- Higher = narrows thresholds with confidence; can reduce distance and contribute to inversions in strong bias
- Lower = more stable distances; fewer near‑collapses
- Compression Reactivity (default 0.8) and Regime Reactivity (default 2.0):
- Higher = stronger compression during quiet states; can make distance small
- Lower = gentler compression; more robust separation
- Distribution Window (default 15), Upper Anchor Level (85), Lower Anchor Level (15):
- Longer window = slower moving baselines; can soften extreme bias effects
- Wider anchor spread (e.g., 90/10) increases halfband; may widen bands but also amplifies bias term; balance with Trend Bias Strength

F) Optional guards to prevent inversions
- Cap bias impact: bias_shift = clamp(bias × Trend Bias Strength, −S, S) with S ∈ [2, 4]
- Enforce non‑cross gap: if (upper_candidate ≤ lower_candidate) then set
- gap = max(min_gap, lower_candidate − upper_candidate)
- distance := distance + (min_gap − gap/2)
- Or simply recompute upper/lower using distance := max(distance, min_gap)
- Minimum gap suggestion: min_gap ∈ [8, 15] depending on timeframe/noise.

G) Scenario examples (what to do)
1) Expansion trend day: green fill, basis rising, line above basis; bands widen and tilt upward; candles mostly bull_strong with low transparency
- Action: Buy pullbacks toward basis/inner layer; avoid countertrend fades; scale out into band re‑touches
2) Post‑compression breakout: yellow → green, line clears basis, bands tilt and widen; a brief inversion may appear during explosive move
- Action: Align with trend; wait for normalization before adding mean‑reversion plays
3) Range reversion afternoon: red fill, line oscillates about center; bands normalize and narrow
- Action: Fade edges back to center; reduce size if green fill returns

H) Troubleshooting band behavior
- “Bands cross often” → Reduce Trend Bias Strength; lower Confidence Tightening and/or Compression Reactivity; add a min_gap
- “Bands too tight” → Lower Confidence Tightening; reduce Regime Reactivity; lengthen Distribution Window
- “Bands too wide” → Increase Confidence Tightening slightly; narrow anchor spread (e.g., 80/20)
- “Bands feel laggy” → Shorten Distribution Window moderately; beware of over‑reactivity

Use these principles to keep Action Bands informative without visual confusion.