diff --git a/Indicators/MyIndicators/Bollinger_Bands.md b/Indicators/MyIndicators/Bollinger_Bands.md new file mode 100644 index 0000000..830685b --- /dev/null +++ b/Indicators/MyIndicators/Bollinger_Bands.md @@ -0,0 +1,95 @@ +# Bollinger Bands Indicator Family (Pro, %B, Width) + +## 1. Summary (Introduction) + +The Bollinger Bands®, developed by John Bollinger, are one of the most widely used and versatile technical analysis tools. They consist of a moving average (centerline) and two trading bands set at a certain number of standard deviations above and below the centerline. Because standard deviation is a measure of volatility, the bands automatically widen when volatility increases and narrow when volatility decreases. + +This document covers our comprehensive, professionally coded MQL5 implementation of the Bollinger Bands family. Our suite goes beyond the standard indicator, offering a **`Bollinger_Bands_Pro`** version with full Heikin Ashi support, and two powerful derivative oscillators: **`Bollinger_Bands_PercentB`** and the **`Bollinger_Band_Width_Pro`**. Together, these tools provide a complete framework for analyzing price volatility and its relationship to the trend. + +**Additionally, this document briefly covers two related, hybrid indicators in our collection: the `Bollinger_Bands_Fibonacci` and the `Bollinger_ATR_Oscillator`.** + +## 2. Mathematical Foundations and Calculation Logic + +All indicators in this family are derived from the same core statistical concepts: the moving average and the standard deviation. + +### Required Components + +- **Period (N):** The lookback period for the moving average and standard deviation calculation. +- **Deviation (D):** The number of standard deviations to set the bands away from the centerline. +- **MA Method:** The type of moving average to use for the centerline. +- **Source Price:** The price series used for calculation (e.g., `PRICE_CLOSE`). + +### Calculation Steps (Algorithm) + +1. **Calculate the Centerline:** First, a moving average (typically an SMA) of the `Source Price` is calculated over the period `N`. + - $\text{Centerline}_t = \text{MA}(\text{Price}, N)_t$ + +2. **Calculate the Standard Deviation:** The standard deviation of the `Source Price` over the same period `N` is calculated. + - $\text{StdDev}_t = \text{StandardDeviation}(\text{Price}, N)_t$ + +3. **Calculate the Main Bands:** The upper and lower bands are calculated by adding and subtracting the multiplied standard deviation from the centerline. + - $\text{Upper Band}_t = \text{Centerline}_t + (D \times \text{StdDev}_t)$ + - $\text{Lower Band}_t = \text{Centerline}_t - (D \times \text{StdDev}_t)$ + +4. **Calculate Derivative Indicators:** + - **Percent B (%B):** Normalizes the price's position relative to the bands. + $\%B_t = \frac{\text{Price}_t - \text{Lower Band}_t}{\text{Upper Band}_t - \text{Lower Band}_t}$ + - **Band Width:** Measures the normalized width of the bands. + $\text{BandWidth}_t = \frac{\text{Upper Band}_t - \text{Lower Band}_t}{\text{Centerline}_t}$ + +## 3. MQL5 Implementation Details + +Our MQL5 suite is built on a shared, modular, and robust calculation engine to ensure consistency and maintainability across the entire indicator family. + +- **Modular, Reusable Calculation Engine (`Bollinger_Bands_Calculator.mqh`):** The entire calculation logic for both standard and Heikin Ashi versions is encapsulated within a single, powerful include file. This object-oriented, polymorphic design allows all indicators in the family to dynamically choose the correct calculation engine at runtime based on user input. + +- **Unified "Pro" Indicators:** Instead of creating numerous separate files, we have consolidated functionality into powerful "Pro" versions. + - **`Bollinger_Bands_Pro.mq5`**: The main indicator. A custom `enum` allows the user to select the source price, including a full range of **Heikin Ashi price types**. + - **`Bollinger_Band_Width_Pro.mq5`**: This advanced oscillator not only displays the Band Width but also includes two additional, selectable analysis modes: **Bands on BandWidth** (for dynamic Squeeze detection) and **Extremes Channel** (for historical Squeeze/Bulge levels). + +- **Stability via Full Recalculation:** All indicators in the family employ a "brute-force" **full recalculation** on every tick. This is our core principle to ensure perfect accuracy and prevent any risk of calculation errors or visual glitches. + +## 4. Parameters + +- **Period (`InpPeriod`):** The lookback period for the MA and standard deviation. Default is `20`. +- **Deviation (`InpDeviation`):** The standard deviation multiplier. Default is `2.0`. +- **MA Method (`InpMethodMA`):** The type of moving average for the centerline. Default is `MODE_SMA`. +- **Source Price (`InpSourcePrice`):** A comprehensive list of price sources, including all standard prices and a full range of Heikin Ashi prices. Default is `PRICE_CLOSE_STD`. +- **Analysis Mode (`InpDisplayMode`):** (Only for `Bollinger_Band_Width_Pro`) Allows the user to switch between the three display modes. + +## 5. Usage and Interpretation + +- **`Bollinger_Bands_Pro` (The Main Channel):** + - **Volatility:** The width of the bands is the primary indicator of volatility. Narrow bands (**Squeeze**) often precede significant price moves. Wide bands indicate high volatility. + - **Mean Reversion:** In ranging markets, prices tend to revert to the mean (the centerline). + - **Trend Following:** In a strong trend, the price can "walk the bands," consistently running along the upper or lower band. + +- **`Bollinger_Bands_PercentB` (The Oscillator):** + - **Overbought/Oversold:** Values above 1.0 or below 0.0 indicate that the price has closed outside the bands. + - **Divergence:** Divergence between price and %B can signal potential reversals. + +- **`Bollinger_Band_Width_Pro` (The Volatility Meter):** + - **Identifying the Squeeze:** This is the indicator's primary strength. When the Band Width line reaches a historical low (in "Extremes Channel" mode) or drops below its own lower Bollinger Band (in "Bands on BandWidth" mode), it signals a Squeeze is in effect, and traders should prepare for a potential breakout. + - **Identifying Trend Exhaustion:** When the Band Width reaches a historical high (a "Bulge"), it often signals that the trend is mature and may be nearing exhaustion. + +--- + +## **6. Related Hybrid Indicators** + +**Our collection also includes two hybrid indicators that, while related, are based on distinct mathematical concepts.** + +### **6.1 Bollinger Bands Fibonacci Ratios** + +- **Concept:** This indicator uses the standard **Bollinger Bands calculation method** (MA + Standard Deviation) but replaces the single deviation multiplier with **three, separate Fibonacci ratios** (1.618, 2.618, 4.236). +- **Calculation:** + - $\text{Upper Band 1}_t = \text{Centerline}_t + (1.618 \times \text{StdDev}_t)$ + - $\text{Upper Band 2}_t = \text{Centerline}_t + (2.618 \times \text{StdDev}_t)$ + - ...and so on for all 6 bands. +- **Interpretation:** It creates a multi-level volatility channel where each band represents a different statistical probability of price containment. It is a pure Bollinger-style indicator for advanced mean-reversion and volatility analysis. + +### **6.2 Bollinger ATR Oscillator** + +- **Concept:** This is a unique oscillator, described by Jon Anderson, that measures the **ratio between two different types of volatility**: the Average True Range (ATR) and the Bollinger Bandwidth. +- **Calculation:** + - $\text{Oscillator Value}_t = \frac{\text{ATR}_t}{\text{Bollinger Bandwidth}_t} = \frac{\text{ATR}_t}{(\text{Upper Band}_t - \text{Lower Band}_t)}$ +- **Interpretation:** It is a **volatility ratio oscillator**. A high value suggests that the short-term, absolute volatility (ATR) is large relative to the longer-term, mean-reverting volatility (Bandwidth), which can be characteristic of a strong, trending market. A low value may indicate a choppy, ranging market. It is a tool for analyzing the **character** of the market's volatility.