SmartMA

(EN)

## **SmartMA v1.2: Technical Specification & Integration Guide**

### 1\. Overview & Philosophy

**SmartMA v1.2** is a professional-grade Pine Script library designed to replace static, lagging indicators (like EMA, SMA, ATR) with dynamic, context-aware engines.

The core philosophy is that a trading system's "baseline" (its sense of value) and "sigma" (its sense of risk) should not be fixed. They should adapt in real-time to changes in market structure, volume, flow, and regime.

This library is a **pure logic engine**. It provides no plots or inputs. It is intended to be imported into a sophisticated "super-indicator" (like your `X Ω` system) to serve as its core processor for value and risk.

### 2\. Core Concepts

Before using the main functions, understand these foundational components:

* **`robust_price()`:** This is the recommended price source for all calculations. It replaces `close` or `hlc3`. It is a 70/30 blend of `hlc3` (for smoothness) and a "body-weighted close" (which prioritizes the candle's body and discounts noisy wicks/dojis). **Use this as the `src` for all MAs.**
* **Rate-Limiting:** All adaptive sigmas (`avs`, `qvs`) and advanced MAs (`ava_plus`, `wva`) are "rate-limited." This means they cannot jump more than a small fraction of the ATR in a single bar, ensuring an extremely smooth and stable output, free of jerky movements.
* **Context-Awareness:** The "plus" (`+`) and advanced functions (`wva`, `aria`) are designed to be "slaved" to your main system. They accept signals like `hazard01`, `fit01`, and `squeeze01` as inputs to dynamically alter their own behavior.

-----

### 3\. ⚙️ Module Analysis & How-To Guide

This library is best understood in four parts: Baselines (MAs), Volatility (Sigmas), Regime (Context), and VWAP (Utilities).

#### \#\# 3.1. Adaptive Baselines (MA Replacements)

These functions replace `ta.ema` or `ta.sma` to provide a dynamic, intelligent "moving average" that acts as your core value baseline.

##### \#\#\# `ava()` / `ava_plus()` (Adaptive Volume Average)

* **Purpose:** The primary replacement for `EMA` or `VWMA`.
* **Logic:** Intelligently blends `EMA` (price-driven) and `VWMA` (volume-driven). It gives more weight to `VWMA` during high "conviction" (strong candle bodies, high volume) and reverts to `EMA` in low-volume, uncertain markets.
* **How to Use `ava_plus` (Recommended):** This is the context-aware version. It accepts `hazard01` and `squeeze01` (from your `X Ω` EWS and Compression blocks).
* `float base = SmartMA.ava_plus(20, EWS_envHazard01, CP_squeeze01, "rob")`
* **Result:** When hazard or squeeze is high, `ava_plus` *reduces* its adaptive logic and defaults toward a simple, "safe" `EMA`, preventing erratic signals in high-risk environments.

##### \#\#\# `aria()` (Adaptive Regime & Intent Average)

* **Purpose:** A "top-down" regime-aware baseline. It is a lighter, more elegant alternative to `WVA`.
* **Logic:** `aria` blends three MAs based on the market's "big picture":
1. `ZLEMA` (Fast): Prioritized when `fit01` (trend quality) is high.
2. `EMA` (Slow): Prioritized when `hazard01` (risk) is high.
3. `AVA` (Core): Used as the default.
* **How to Use:** This is an *ideal* baseline for `X Ω`. Feed it the final outputs from your Analyst and EWS blocks.
* `float baseline = SmartMA.aria(20, ANL_fit01_out, EWS_envHazard01, ANL_biasPM1_out)`
* **Result:** The baseline automatically becomes faster in good trends, slower in risky markets, and even "tilts" slightly in the direction of your system's `bias` (intent).

##### \#\#\# `wva()` / `wva_plus()` (Whale-flow Adaptive Average)

* **Purpose:** The "ultimate" baseline. This is the most comprehensive, data-driven MA in the suite.
* **Logic:** `wva_plus` is a multi-scale MA that synthesizes 12 context signals (whale flow, absorption, imbalance, hazard, etc.) AND is anchored to **two distinct, user-defined events**. It uses "consensus" (max of up/down pressure) to drive its adaptive speed.
* **How to Use:** This function is *perfectly* designed to be the "central brain" for `X Ω`'s "senses." You connect your `X Ω` blocks directly to its parameters.
> **Example: Creating a Master Baseline**
> `// 1. Define your two anchors (e.g., 2022 Low and 2023 Q4 Low)`
> `bool anchor_L_2022 = (year == 2022 and month == 11 and dayofmonth == 16)`
> `bool anchor_L_2023 = (year == 2023 and month == 11 and dayofmonth == 1)`
> `// 2. Feed X Ω signals directly into wva_plus`
> `float master_baseline = SmartMA.wva_plus(20,`
> `    whale01       = WH2_score01,       // from Block 11`
> `    absorbTop01   = FE_absorbTop01,   // from Block 6`
> `    absorbBot01   = FE_absorbBot01,   // from Block 6`
> `    imbUp01        = IMB_imbalanceUp01, // from Block 8`
> `    imbDn01        = IMB_imbalanceDn01, // from Block 8`
> `    easeUp01       = LM_easeUp01_out,   // from Block 9`
> `    easeDn01       = LM_easeDn01_out,   // from Block 9`
> `    hazard01       = EWS_envHazard01,   // from Block 13`
> `    breadth01      = FE_miScore01,      // from Block 4`
> `    squeeze01      = CP_squeeze01,      // from Block 10`
> `    anchor1        = anchor_L_2022,`
> `    slot1          = 1,`
> `    anchor2        = anchor_L_2023,`
> `    slot2          = 2`
> `)`
* **Result:** You get a single baseline that reflects multi-scale price, volume, flow, imbalance, *and* is anchored to two critical historical events.

-----

#### \#\# 3.2. Adaptive Volatility (Sigma Replacements)

These functions replace `ta.atr` to provide a dynamic, smoother, and more robust measure of risk (sigma).

##### \#\#\# `avs()` / `avs_plus()` (Adaptive Volatility Sigma)

* **Purpose:** The primary replacement for `ta.atr`.
* **Logic:** Blends `ATR` (which is good at capturing overnight gaps) with statistical OHLC estimators (Garman-Klass by default) for a more accurate measure of intra-bar volatility. It is heavily smoothed and rate-limited.
* **How to Use `avs_plus`:** This is the context-aware version. Feed it the `hazard01` signal from your `X Ω` EWS block.
* `float risk_sigma = SmartMA.avs_plus(14, hazard01=EWS_envHazard01)`
* **Result:** Your risk bands (`VZA`) will *automatically* widen during high-hazard periods.

##### \#\#\# `qvs()` (Quantile Volatility Sigma)

* **Purpose:** A **more robust** alternative to `AVS`. Highly recommended.
* **Logic:** `AVS` and `ATR` are based on an *average*, which is highly sensitive to one-off, extreme outlier wicks (e.g., a "flash crash" wick). `QVS` is based on **quantiles** (percentiles). It measures the volatility level that (e.g.) 90% of recent bars fall *below*.
* **How to Use:** Use this for your "must-hold" stop-loss bands.
* `float robust_sigma = SmartMA.qvs(20, 0.90, "mix")`
* **Result:** A "real-world" sigma that is immune to outliers and provides a much more stable band for risk management.

##### \#\#\# `avs_asym_ex()` (Extended Asymmetric Sigma)

* **Purpose:** Creates dynamic, asymmetric risk bands (channels).
* **Logic:** This is a brilliant integration point. It takes the `avs` (or `qvs`) sigma and creates two different bands (`[up, dn]`) that are "tilted" by:
1. `biasPM1`: Your system's directional intent (from `X Ω`'s Analyst block).
2. `easeUp01` / `easeDn01`: The "Line of Least Resistance" (from `X Ω`'s S/R block).
* **How to Use:**
* `[sigmaUp, sigmaDn] = SmartMA.avs_asym_ex(14, ANL_biasPM1_out, LM_easeUp01_out, LM_easeDn01_out, "qvs")`
* `[bandTop, bandBot] = SmartMA.vza_asym(master_baseline, sigmaUp, sigmaDn, 1.5, 1.5)`
* **Result:** A channel that *automatically widens* in the direction of the trend, and widens *even more* if it's moving into an area of low S/R (high "ease"). It gives a strong trend "room to run."

-----

#### \#\# 3.3. Regime & Drift (Context Engines)

These functions are not MAs themselves, but rather engines to *drive* other MAs.

##### \#\#\# `fia()` (Fit Integrator)

* **Purpose:** Provides a single "regime" score (0-1) answering, "How good is this trend quality?"
* **Logic:** Blends `R²` (linearity), `ADX` (strength), and the **Hurst Exponent** (persistence/memory). A high score means the trend is strong, linear, and *likely to continue* (H \> 0.5).
* **How to Use:** This is the *primary input* for `dfa()` and `aria()`.
* `float fit_score = SmartMA.fia(14, 20)`

##### \#\#\# `dfa()` (Drift & Fit Average)

* **Purpose:** The replacement for `ta.linreg_slope`. It calculates the "fit-aware" velocity of price.
* **Logic:** It blends the slope of `ZLEMA` (fast, low-lag) with the slope of `ta.linreg` (smooth, stable). It uses the `fit_score` from `fia()` to decide the blend.
* **How to Use:** Use this to power your `X Ω` "Forecast Core" (Block 21).
* `float forecast_drift = SmartMA.dfa(robust_price(), 20, fit_score)`
* **Result:** Your forecast will automatically accelerate in high-quality trends and slow down/stabilize in choppy, low-fit markets.

-----

### 4\. Quick API Reference (Key Exports)

* `robust_price()`: Use as your `src`.
* `ava(len, profile)`: Simple adaptive volume MA.
* `ava_plus(len, hazard01, squeeze01, profile)`: `ava` gated by risk.
* `avs(len, method, wATR)`: `ATR` replacement (smooth, blended).
* `avs_plus(len, ..., hazard01)`: `avs` gated by risk.
* `qvs(len, quantile, mode)`: Robust, quantile-based `ATR` replacement (Recommended).
* `avs_asym_ex(len, biasPM1, easeUp01, easeDn01, base, ...)`: Asymmetric bands driven by bias and S/R.
* `fia(lenS, lenL)`: Regime/Fit score 0-1 (R², ADX, Hurst).
* `dfa(src, len, fit01)`: "Fit-aware" slope/drift.
* `aria(len, fit01, hazard01, biasPM1, profile)`: Top-down, regime-aware baseline.
* `wva_plus(len, [12 context signals], anchor1, slot1, anchor2, slot2, profile)`: The "ultimate" dual-anchor, context-aware baseline.

-----