Volume Weighted Z Score

This indicator calculates the Volume Weighted Z-Score (VWZS), a
statistical oscillator that measures the number of standard deviations
the price is removed from its mean. It combines robust volatility
decomposition with advanced divergence detection.

Key Features:

1. **Volatility Decomposition:** The indicator separates volatility
based on the 'Estimate Bar Statistics' option.
- **Standard Mode (`Estimate Bar Statistics` = OFF):** Calculates
a simple (Volume-Weighted) Standard Deviation using the
selected `Source` for both the baseline and the signal.
- **Decomposition Mode (`Estimate Bar Statistics` = ON):**
Uses a hybrid statistical approach:
a) **The Model (Baseline):** Uses an estimator to calculate
the 'within-bar' mean and volatility. This creates a
stable, mathematically idealized expectation value (mu).
b) **The Signal (Observation):** Compares the actual `Source`
(e.g., Close) against this statistical baseline.
(Result: A Z-Score that combines a noise-filtered trend
baseline with a highly reactive price signal).

2. **Visual Decomposition Logic:** Total Standard Deviation is the
primary metric displayed. Since Standard Deviations are not
linearly additive (sqrt(a+b) != sqrt(a)+sqrt(b)), this indicator
plots the *exact* Total StdDev and partitions the area underneath
based on the Variance Ratio. This ensures the displayed total
volatility remains mathematically accurate while showing relative
composition.

3. **Normalization (Geometric Average):** Includes an optional
'Normalize' mode. When enabled, the indicator uses a
Geometric Moving Average (GMA) as its baseline and applies a
statistical correction for the log-normal distribution
ensuring symmetry between upside and downside movements.

4. **Full Divergence Suite (Class A, B, C):** The indicator's
primary feature is its integrated divergence engine. It
automatically detects and plots all three major divergence
classes between price and the Z-Score:
- Regular (A): Signals potential trend exhaustion and reversals.
- Hidden (B): Signals potential trend continuations during pullbacks.
- Exaggerated (C): Signals weakness at double tops/bottoms.

5. **Divergence Filtering and Visualization:**
- **Price Tolerance Filter:** Divergence detection is enhanced
with a percentage-based price tolerance (`pivPrcTol`) to
filter out insignificant market noise, leading to more
robust signals.
- **Persistent Visualization:** Divergence markers are plotted
for the entire duration of the signal and are visually
anchored to the oscillator level of the confirming pivot.
- **Flexible Pivot Algorithms:** Supports various underlying
mathematical models for pivot detection provided by the
core library

6. **Note on Confirmation (Lag):** Divergence signals rely on a
pivot confirmation method to ensure they do not repaint.
- The **Start** of a divergence is only detected *after* the
confirming pivot is fully formed (a delay based on
`Pivot Right Bars`).
- The **End** of a divergence is detected either instantly
(if the signal is invalidated by price action) or with
a delay (when a new, non-divergent pivot is confirmed).

7. **Multi-Timeframe (MTF) Capability:**
- **MTF Calculation:** The Z-Score line *itself* can be calculated on a
higher timeframe, with standard options to handle gaps
(`Fill Gaps`) and prevent repainting (`Wait for...`).
- **Limitation:** The Divergence detection engine (`pivDiv`)
is designed for the active timeframe. Using it in MTF mode
is not recommended as step-data can lead to inaccurate
pivot detection.

8. **Integrated Alerts:** Includes a comprehensive set of built-in
alerts for the Z-Score crossing the neutral line, the configured
Threshold levels, and the start/end of all divergence types.

---

**DISCLAIMER**

1. **For Informational/Educational Use Only:** This indicator is
provided for informational and educational purposes only. It does
not constitute financial, investment, or trading advice, nor is
it a recommendation to buy or sell any asset.

2. **Use at Your Own Risk:** All trading decisions you make based on
the information or signals generated by this indicator are made
solely at your own risk.

3. **No Guarantee of Performance:** Past performance is not an
indicator of future results. The author makes no guarantee
regarding the accuracy of the signals or future profitability.

4. **No Liability:** The author shall not be held liable for any
financial losses or damages incurred directly or indirectly from
the use of this indicator.

5. **Signals Are Not Recommendations:** The alerts and visual signals
(e.g., crossovers) generated by this tool are not direct
recommendations to buy or sell. They are technical observations
for your own analysis and consideration.