# 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.
