docs: refactor

This commit is contained in:
Toh4iem9
2026-09-29 14:33:39 +02:00
parent b09990cc1d
commit 06e26c936a
@@ -0,0 +1,408 @@
# Volume-Weighted Z-Score Bands (V-Score Bands) Pro (v3.20)
Dynamic Open-Ended Gaussian Volatility Envelopes Projected Around Anchored VWAP
---
## 1. Summary (Introduction)
**V-Score Bands Pro (v3.20)** is an institutional-grade on-chart volatility envelope that projects dynamic **Volume-Weighted Standard Deviation Bands** directly onto the main price chart.
While conventional volatility envelopes (such as Bollinger Bands or Keltner Channels) rely on unweighted, lagging moving averages that treat every price bar equally, **V-Score Bands Pro anchors its envelopes to the market's true institutional Volume-Weighted Average Price (VWAP)**.
By scaling dynamic boundaries symmetrically around VWAP at discrete standard deviation multiples ($\pm 1.5\sigma, \pm 2.0\sigma, \pm 2.5\sigma$), the indicator translates the statistical readings of the subwindow `V-Score Pro` oscillator directly into actionable, high-conviction support, resistance, and breakout boundaries on the price chart.
```text
┌────────────────────────────────────────────────────────────────────────┐
│ V-SCORE BANDS ON-CHART ENVELOPE HIERARCHY │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ +2.5σ ──▶ Bull Wall Band (clrMidnightBlue) ── Climax Exhaustion │
│ +2.0σ ──▶ Bull Extreme Band (clrDeepSkyBlue) ── Overbought Climax │
│ +1.5σ ──▶ Bull Flow Band (clrLightSkyBlue) ── Institutional Flow │
│ │
│ 0.0σ ──▶ ANCHORED VWAP BASELINE (clrOrange, Width=2) │
│ │
│ -1.5σ ──▶ Bear Flow Band (clrCoral) ── Institutional Flow │
│ -2.0σ ──▶ Bear Extreme Band (clrOrangeRed) ── Oversold Climax │
│ -2.5σ ──▶ Bear Wall Band (clrDarkRed) ── Capitulation Floor │
│ │
│ • 14 Segmented Buffers (Gapped Odd/Even Pairs Across Session Resets) │
│ • Enterprise v3.20: Zero-Lag MTF Fast-Path (0 iBarShift API calls) │
└────────────────────────────────────────────────────────────────────────┘
```
### The Architectural Duality: V-Score vs. V-Score Bands
A frequent architectural inquiry is why `VScore_Bands_Pro` binds directly to `VWAP_Calculator.mqh` rather than `VScore_Calculator.mqh`:
- **`VScore_Calculator` (Dimensionless Oscillator):** Calculates the normalized quotient $\frac{P_t - \mu_t}{\sigma_t}$. It divides by standard deviation to generate a pure dimensionless oscillator ($\sigma \in [-3, +3]$) in a separate window. It does not export raw price bands.
- **`VScore_Bands_Pro` (On-Chart Price Envelopes):** Evaluates price levels on the chart: $\mu_t \pm (k \cdot \sigma_t)$. It requires the raw VWAP price and the raw standard deviation ($\sigma$) in currency units (dollars, points).
- **The Solution:** Binding directly to the state-safe $O(1)$ `VWAP_Calculator.mqh` engine provides the cleanest, fastest, and most modular architecture, eliminating redundant abstraction layers.
```text
┌────────────────────────────────────────────────────────────────────────┐
│ V-SCORE BANDS ARCHITECTURAL EVOLUTION │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ LEGACY ENGINE (v3.10): │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ • 6 separate Copy API calls on every live MTF tick │ │
│ │ • Up to 1,000 iBarShift calls per tick across 14 buffers │ │
│ │ • Truncated history lookback on Weekly / Monthly resets │ │
│ │ • Severe chart stuttering in multi-window setups │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ OPTIMIZED │
│ ENTERPRISE ENGINE (v3.20): │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ • 1 Atomic CopyRates call per live MTF tick (-83.3% API) │ │
│ │ • 0 iBarShift calls on live ticks (ArrayBsearch Fast-Path) │ │
│ │ • Direct 14-buffer vectorized flat assignment on live ticks │ │
│ │ • Multi-week history depth stabilization (1000–2000 bars) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────┘
```
---
## 2. Mathematical Foundations & Dynamic Envelope Projection
```text
Price Expansion Wave
▲
│ ┌─── High: Rejection at +2.5σ Bull Wall
+2.5σ ──────────────────────────┼──┴─────────────────────────── clrMidnightBlue
+2.0σ ──────────────────────────┼────────────────────────────── clrDeepSkyBlue
+1.5σ ──────────────────────────┼────────────────────────────── clrLightSkyBlue
│
0.0σ ══════════════════════════╪══════════════════════════════ ANCHORED VWAP
│
-1.5σ ──────────────────────────┼────────────────────────────── clrCoral
-2.0σ ──────────────────────────┼────────────────────────────── clrOrangeRed
-2.5σ ──────────────────────────┴──┬─────────────────────────── clrDarkRed
└─── Low: Capitulation at -2.5σ Bear Wall
```
### 2.1. Anchored Volume-Weighted Baseline ($\mu_{\text{VWAP}, t}$)
Evaluated via cumulative volume integration anchored to the user-selected cycle:
$$\mu_{\text{VWAP}, t} = \frac{\sum_{k=\text{anchor}(t)}^{t} \left( \text{TP}_k \cdot V_k \right)}{\sum_{k=\text{anchor}(t)}^{t} V_k}$$
*where $\text{TP}_k = \frac{H_k + L_k + C_k}{3}$ (or Heikin Ashi equivalent) and $V_k$ is the applied volume.*
### 2.2. Open-Ended Rolling Standard Deviation ($\sigma_{\text{VWAP}, t}$)
Given volatility lookback period $P = \text{InpPeriod}$:
$$\text{Diff}_k = C_k - \mu_{\text{VWAP}, k}$$
$$\sigma_{\text{VWAP}, t} = \sqrt{\frac{1}{P} \sum_{k=0}^{P - 1} \left( \text{Diff}_{t - k} \right)^2}$$
*Note: The engine uses open-ended sampling across session boundaries, ensuring standard deviation never pinches to zero at market open.*
### 2.3. Dynamic Price Envelope Projections
$$\text{BullWall}_t = \mu_{\text{VWAP}, t} + (2.5 \cdot \sigma_{\text{VWAP}, t})$$
$$\text{BullExtr}_t = \mu_{\text{VWAP}, t} + (2.0 \cdot \sigma_{\text{VWAP}, t})$$
$$\text{BullFlow}_t = \mu_{\text{VWAP}, t} + (1.5 \cdot \sigma_{\text{VWAP}, t})$$
$$\text{Baseline}_t = \mu_{\text{VWAP}, t}$$
$$\text{BearFlow}_t = \mu_{\text{VWAP}, t} - (1.5 \cdot \sigma_{\text{VWAP}, t})$$
$$\text{BearExtr}_t = \mu_{\text{VWAP}, t} - (2.0 \cdot \sigma_{\text{VWAP}, t})$$
$$\text{BearWall}_t = \mu_{\text{VWAP}, t} - (2.5 \cdot \sigma_{\text{VWAP}, t})$$
---
### 2.4. Alternating Odd/Even Buffer Segmentation (14 Buffers)
To eliminate diagonal line artifacts connecting the close of one session to the open of the next, all 7 price levels are mapped into paired **Odd** and **Even** plot streams:
- When $\text{PeriodIndex}$ is odd: Odd buffers (`Buf..._Odd`) display active values; Even buffers are filled with `EMPTY_VALUE`.
- When $\text{PeriodIndex}$ is even: Even buffers (`Buf..._Even`) display active values; Odd buffers are filled with `EMPTY_VALUE`.
---
### 2.5. Institutional Swapped Thermal Band Taxonomy
| Band Identifier | Multiplier | Visual Default | Institutional Role |
| :--- | :---: | :--- | :--- |
| **Bull Wall** | $+2.5\sigma$ | `clrMidnightBlue` | Extreme liquidity exhaustion ceiling; mean-reversion short target. |
| **Bull Extreme** | $+2.0\sigma$ | `clrDeepSkyBlue` | Statistical overbought climax; initial profit-taking boundary. |
| **Bull Flow** | $+1.5\sigma$ | `clrLightSkyBlue` | Point of institutional volume expansion; dynamic support in markup. |
| **Anchored VWAP** | $0.0\sigma$ | `clrOrange` (w=2) | Institutional fair-value equilibrium baseline. |
| **Bear Flow** | $-1.5\sigma$ | `clrCoral` | Point of institutional distribution expansion; dynamic resistance. |
| **Bear Extreme** | $-2.0\sigma$ | `clrOrangeRed` | Statistical oversold climax; short-covering bounce zone. |
| **Bear Wall** | $-2.5\sigma$ | `clrDarkRed` | Panic liquidation capitulation floor; mean-reversion long target. |
---
## 3. MQL5 Architecture & Computational Benchmarking
```text
┌────────────────────────────────────────────────────────┐
│ VWAP_Calculator.mqh │
│ (True O(1) Incremental Engine with State Caching) │
└──────────────────────────┬─────────────────────────────┘
│ Delivers Segmented VWAP Streams
▼
┌────────────────────────────────────────────────────────┐
│ VScore_Bands_Pro.mq5 │
│ (Unified Native & Zero-Lag MTF Fast-Path) │
├──────────────────────────┬─────────────────────────────┤
│ Buffer Layer (14) │ Centralized Framework │
│ • 7 Odd Buffers │ • DataSync_Tools.mqh │
│ • 7 Even Buffers │ • Binary Search Snapping │
│ │ • Atomic CopyRates │
└──────────────────────────┴─────────────────────────────┘
```
### Engineering Benchmark: Legacy (v3.10) vs. Enterprise (v3.20)
| Metric | Legacy Implementation (v3.10) | Enterprise Refactor (v3.20) | Net Optimization |
| :--- | :---: | :---: | :---: |
| **MTF Live-Tick `iBarShift`** | Up to 1,000 calls per tick | **0 calls on live ticks (`ArrayBsearch`)** | **Complete Zero-Lag** |
| **MTF Data Copy Calls** | 6 separate calls per tick | **1 atomic `CopyRates` query** | **-83.3% API Overhead** |
| **Weekly / Monthly Depth** | Inadequate history depth | **1000–2000 bars guaranteed** | **Full Multi-Week Fidelity** |
| **Pointer Safety** | Slow `CheckPointer()` on ticks | **Fast `if(!g_vwap)` Guard** | **Optimized Branching** |
| **Multi-Window Scalability** | Severe UI lag on 14 charts | **Silky-smooth execution on >14 charts** | **Enterprise Certified** |
---
## 4. Parameters Reference
### Timeframe Settings
- `InpTimeframe` (*default: `PERIOD_CURRENT`*): Calculation timeframe. Set to `PERIOD_CURRENT` for zero-lag native mode, or choose a higher timeframe (e.g., `PERIOD_H1`, `PERIOD_D1`) to activate the synchronized MTF engine.
### V-Score Core Settings
- `InpPeriod` (*default: `20`*): Volatility lookback ($P$) for standard deviation variance calculation.
- `InpVWAPReset` (*default: `PERIOD_SESSION`*): Temporal reset anchor mode (`PERIOD_SESSION`, `PERIOD_WEEK`, `PERIOD_MONTH`, `PERIOD_CUSTOM_SESSION`).
- `InpTzShift` (*default: `0`*): Timezone offset in hours relative to broker server time.
- `InpCustomSessionStart` (*default: `"09:30"`*): Session start time (`HH:MM`) when using `PERIOD_CUSTOM_SESSION`.
- `InpCustomSessionEnd` (*default: `"16:00"`*): Session end time (`HH:MM`) when using `PERIOD_CUSTOM_SESSION`.
### Calculation Settings
- `InpVolumeType` (*default: `VOLUME_TICK`*): Applied volume source (`VOLUME_TICK` or `VOLUME_REAL`).
- `InpCandleSource` (*default: `CANDLE_STANDARD`*): Price input series (`CANDLE_STANDARD` or `CANDLE_HEIKIN_ASHI`).
### V-Score Z-Levels (Standard Deviations)
- `InpLevelFlow` (*default: `1.5`*): Sigma multiplier for Flow Bands.
- `InpLevelExtreme` (*default: `2.0`*): Sigma multiplier for Extreme Bands.
- `InpLevelWall` (*default: `2.5`*): Sigma multiplier for Wall Bands.
### Visual Settings
- `InpColorVWAP` / `InpStyleVWAP` / `InpWidthVWAP`: Visual styling for the Centerline (Default: `clrOrange`, `STYLE_SOLID`, `2`).
- `InpColorUpFlow` / `InpColorDnFlow` / `InpStyleFlow` / `InpWidthFlow`: Visual styling for Flow Bands ($\pm 1.5\sigma$).
- `InpColorUpExtr` / `InpColorDnExtr` / `InpStyleExtr` / `InpWidthExtr`: Visual styling for Extreme Bands ($\pm 2.0\sigma$).
- `InpColorUpWall` / `InpColorDnWall` / `InpStyleWall` / `InpWidthWall`: Visual styling for Wall Bands ($\pm 2.5\sigma$).
---
## 5. Quantitative Trading Playbooks
```text
┌────────────────────────────────────────────────────────────────────────┐
│ V-SCORE BANDS INSTITUTIONAL PLAYBOOKS │
├────────────────────────────────────────────────────────────────────────┤
│ 1. Wall Mean Reversion: Fade candle rejections at the ±2.5σ Wall; │
│ target the Centerline (Anchored VWAP). │
│ 2. Volume Flow Expansion: Buy pullbacks to the +1.5σ Flow band during │
│ markup; sell pullbacks to -1.5σ in markdown.│
│ 3. Session Open Gap Fade: Fade opening gap overextension back toward │
│ the developing intraday VWAP line. │
└────────────────────────────────────────────────────────────────────────┘
```
### 5.1. Wall Mean Reversion Fade ($\pm 2.5\sigma$)
- **Premise:** When price expands beyond $2.5$ standard deviations away from the session VWAP, statistical overextension is severe, with a $>98\%$ probability of mean reversion back toward fair value.
- **Long Capitulation Setup:**
1. Price flushes downward into the **Bear Wall ($-2.5\sigma$, `clrDarkRed`)**.
2. A bullish rejection candle (long lower wick or Heikin Ashi color flip) prints.
3. **Enter Long:** Stop loss placed below the wick low. Target 1: Bear Flow ($-1.5\sigma$); Target 2: Central VWAP line ($0.0\sigma$).
- **Short Exhaustion Setup:**
1. Price surges upward into the **Bull Wall ($+2.5\sigma$, `clrMidnightBlue`)**.
2. Bearish rejection prints $\rightarrow$ **Enter Short** targeting the Central VWAP line.
### 5.2. Volume Flow Continuation Ride ($+1.5\sigma \dots +2.0\sigma$)
- **Premise:** During strong institutional trend regimes, price does not return to the centerline ($0.0\sigma$). Instead, the **Flow Band ($\pm 1.5\sigma$)** serves as dynamic institutional support/resistance.
- **Bullish Execution:**
- Price expands above $+2.0\sigma$, pulling the bands upward into an expansion trumpet.
- Price pulls back to test the **Bull Flow Band (`LightSkyBlue`, $+1.5\sigma$)** from above.
- Bullish confirmation prints $\rightarrow$ **Enter Long**, riding the trend higher.
---
## 6. Indicator Buffer Map (For Developers & EA Integration)
### Buffer Allocation
| Buffer Index | Name | Type | Period | Description |
| :---: | :---: | :---: | :---: | :--- |
| **0** | `BufVWAP_Odd` | `INDICATOR_DATA` | Odd | VWAP Centerline for odd sessions. |
| **1** | `BufVWAP_Even` | `INDICATOR_DATA` | Even | VWAP Centerline for even sessions. |
| **2** | `BufUpFlow_Odd` | `INDICATOR_DATA` | Odd | Bull Flow Band ($+1.5\sigma$) for odd sessions. |
| **3** | `BufUpFlow_Even` | `INDICATOR_DATA` | Even | Bull Flow Band ($+1.5\sigma$) for even sessions. |
| **4** | `BufDnFlow_Odd` | `INDICATOR_DATA` | Odd | Bear Flow Band ($-1.5\sigma$) for odd sessions. |
| **5** | `BufDnFlow_Even` | `INDICATOR_DATA` | Even | Bear Flow Band ($-1.5\sigma$) for even sessions. |
| **6** | `BufUpExtr_Odd` | `INDICATOR_DATA` | Odd | Bull Extreme Band ($+2.0\sigma$) for odd sessions. |
| **7** | `BufUpExtr_Even` | `INDICATOR_DATA` | Even | Bull Extreme Band ($+2.0\sigma$) for even sessions. |
| **8** | `BufDnExtr_Odd` | `INDICATOR_DATA` | Odd | Bear Extreme Band ($-2.0\sigma$) for odd sessions. |
| **9** | `BufDnExtr_Even` | `INDICATOR_DATA` | Even | Bear Extreme Band ($-2.0\sigma$) for even sessions. |
| **10** | `BufUpWall_Odd` | `INDICATOR_DATA` | Odd | Bull Wall Band ($+2.5\sigma$) for odd sessions. |
| **11** | `BufUpWall_Even` | `INDICATOR_DATA` | Even | Bull Wall Band ($+2.5\sigma$) for even sessions. |
| **12** | `BufDnWall_Odd` | `INDICATOR_DATA` | Odd | Bear Wall Band ($-2.5\sigma$) for odd sessions. |
| **13** | `BufDnWall_Even` | `INDICATOR_DATA` | Even | Bear Wall Band ($-2.5\sigma$) for even sessions. |
*Note: All buffers maintain chronological indexing (`ArraySetAsSeries = false`). Because sessions alternate to prevent diagonal connectors, only one buffer of each pair holds an active value at any given bar $i$.*
---
### Critical EA Integration Pattern: Merged Active Band Reading
```mql5
//+------------------------------------------------------------------+
//| EA_VScore_Bands_Interface.mq5 |
//| Copyright 2026, xxxxxxxx|
//+------------------------------------------------------------------+
#property copyright "Copyright 2026, xxxxxxxx"
#property version "1.00"
#property strict
//--- Include VWAP Period Definition
#include <MyIncludes\VWAP_Calculator.mqh>
//--- EA Inputs
input group "=== V-Score Bands Filter Parameters ==="
input ENUM_TIMEFRAMES InpBandsTF = PERIOD_CURRENT; // Timeframe
input int InpPeriod = 20; // Volatility Period
input ENUM_VWAP_PERIOD InpReset = PERIOD_SESSION; // Anchor Period
input ENUM_APPLIED_VOLUME InpVolume = VOLUME_TICK; // Volume Source
//--- Global Indicator Handle
int g_bands_handle = INVALID_HANDLE;
//+------------------------------------------------------------------+
//| Expert initialization function |
//+------------------------------------------------------------------+
int OnInit()
{
if(g_bands_handle != INVALID_HANDLE)
IndicatorRelease(g_bands_handle);
// Instantiate handle to VScore_Bands_Pro via iCustom
g_bands_handle = iCustom(_Symbol,
InpBandsTF,
"VScore_Bands_Pro",
InpBandsTF,
InpPeriod,
InpReset,
0, "09:30", "16:00", // Default session settings
InpVolume,
0, // Standard Candle Source
1.5, 2.0, 2.5); // Flow, Extreme, Wall levels
if(g_bands_handle == INVALID_HANDLE)
{
PrintFormat("EA Error: Failed to create handle for VScore_Bands_Pro. Error: %d", GetLastError());
return INIT_FAILED;
}
Print("EA Success: VScore_Bands_Pro handle initialized successfully.");
return INIT_SUCCEEDED;
}
//+------------------------------------------------------------------+
//| Expert deinitialization function |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
{
if(g_bands_handle != INVALID_HANDLE)
{
IndicatorRelease(g_bands_handle);
g_bands_handle = INVALID_HANDLE;
}
}
//+------------------------------------------------------------------+
//| Helper: Extract Merged Active Level from Paired Odd/Even Buffers |
//+------------------------------------------------------------------+
double GetActiveLevel(const int odd_buffer_idx, const int even_buffer_idx, const int shift)
{
double odd_val[1], even_val[1];
if(CopyBuffer(g_bands_handle, odd_buffer_idx, shift, 1, odd_val) < 1 ||
CopyBuffer(g_bands_handle, even_buffer_idx, shift, 1, even_val) < 1)
{
return EMPTY_VALUE;
}
if(odd_val[0] != EMPTY_VALUE && odd_val[0] > 0.0)
return odd_val[0];
else if(even_val[0] != EMPTY_VALUE && even_val[0] > 0.0)
return even_val[0];
return EMPTY_VALUE;
}
//+------------------------------------------------------------------+
//| Expert tick function |
//+------------------------------------------------------------------+
void OnTick()
{
// Query merged active levels for closed bar (Shift = 1)
double vwap = GetActiveLevel(0, 1, 1); // VWAP (Buffers 0 & 1)
double up_flow = GetActiveLevel(2, 3, 1); // Bull Flow (Buffers 2 & 3)
double dn_flow = GetActiveLevel(4, 5, 1); // Bear Flow (Buffers 4 & 5)
double up_wall = GetActiveLevel(10, 11, 1); // Bull Wall (Buffers 10 & 11)
double dn_wall = GetActiveLevel(12, 13, 1); // Bear Wall (Buffers 12 & 13)
if(vwap == EMPTY_VALUE || vwap <= 0.0)
return; // Data synchronizing
// Query corresponding closed prices
double close[1], low[1], high[1];
if(CopyClose(_Symbol, _Period, 1, 1, close) < 1 ||
CopyLow(_Symbol, _Period, 1, 1, low) < 1 ||
CopyHigh(_Symbol, _Period, 1, 1, high) < 1)
{
return;
}
double cur_close = close[0];
double cur_low = low[0];
double cur_high = high[0];
// Quantitative Signals
bool buy_wall_bounce = (cur_low <= dn_wall && cur_close > dn_wall);
bool sell_wall_bounce = (cur_high >= up_wall && cur_close < up_wall);
Comment(StringFormat("V-Score Bands Telemetry:\n"
"Bull Wall (+2.5σ): %.*f\n"
"Bull Flow (+1.5σ): %.*f\n"
"VWAP Baseline: %.*f\n"
"Bear Flow (-1.5σ): %.*f\n"
"Bear Wall (-2.5σ): %.*f\n"
"Wall Bounce Signals -> Buy: %s | Sell: %s",
_Digits, up_wall,
_Digits, up_flow,
_Digits, vwap,
_Digits, dn_flow,
_Digits, dn_wall,
buy_wall_bounce ? "TRIGGERED" : "NO",
sell_wall_bounce ? "TRIGGERED" : "NO"));
}
//+------------------------------------------------------------------+
```