refactor: add oscillators

Indicators/MyIndicators/CCI.md

@@ -4,7 +4,9 @@
 
 The Commodity Channel Index (CCI) is a versatile momentum oscillator developed by Donald Lambert, first introduced in "Commodities" magazine in 1980. Despite its name, it is used effectively in any market, including stocks, forex, and futures.
 
-The CCI measures the current price level relative to an average price level over a specified period. It is designed to identify cyclical turns in commodities but is widely used to detect overbought and oversold conditions. High values indicate that the price is unusually high compared to its average, and low values indicate it is unusually low.
+The CCI measures the current price level relative to an average price level over a specified period. It is designed to identify cyclical turns but is widely used to detect overbought and oversold conditions. High values indicate that the price is unusually high compared to its average, and low values indicate it is unusually low.
+
+The **CCI Oscillator** is a supplementary indicator that displays the difference between the main CCI line and its signal line as a histogram, providing a clearer visual of accelerating and decelerating momentum.
 
 ## 2. Mathematical Foundations and Calculation Logic
 
@@ -14,7 +16,7 @@ The CCI is based on the relationship between the price, its moving average, and
 
 - **Period (N):** The lookback period for all calculations (e.g., 20).
 - **Source Price (P):** The price series used for the calculation. The classic definition uses the **Typical Price** `(High + Low + Close) / 3`.
-- **Constant:** A statistical constant of `0.015` used to scale the result so that approximately 70% to 80% of values fall between the -100 and +100 levels.
+- **Constant:** A statistical constant of `0.015` used to scale the result.
 
 ### Calculation Steps (Algorithm)
 
@@ -30,27 +32,32 @@ The CCI is based on the relationship between the price, its moving average, and
 4. **Calculate the CCI Value:** Apply the final formula.
    $\text{CCI}_i = \frac{P_i - \text{SMA}_i}{0.015 \times \text{MAD}_i}$
 
+5. **Calculate the Signal Line & Oscillator:** The signal line is a moving average of the CCI line, and the oscillator is the difference between the two.
+
 ## 3. MQL5 Implementation Details
 
-Our MQL5 toolkit includes two distinct standard implementations of the CCI, along with their Heikin Ashi counterparts, to offer a choice between performance and perfect mathematical accuracy.
+Our MQL5 toolkit includes two distinct standard implementations of the CCI, along with their Heikin Ashi counterparts and oscillator versions, to offer a choice between performance and perfect mathematical accuracy.
 
 - **Stability via Full Recalculation:** All versions employ a "brute-force" full recalculation within the `OnCalculate` function to ensure maximum stability.
-- **Self-Contained Logic:** All versions are completely self-contained, with fully manual calculations for all components, making them independent of external handles or libraries.
-- **Optional Signal Line:** All versions have been enhanced with an optional, user-configurable moving average signal line, complete with our robust, manual calculation logic for all MA types.
+- **Self-Contained Logic:** All versions are completely self-contained, with fully manual calculations for all components.
+- **Optional Signal Line:** All line-based versions have been enhanced with an optional, user-configurable moving average signal line.
 
-### Our Two Standard Versions
+### Our Two Calculation Methodologies
 
 1. **Efficient Version (`CCI.mq5`):**
 
-   - **Concept:** A high-performance implementation suitable for most applications, including Expert Advisors.
+   - **Concept:** A high-performance implementation suitable for most applications.
    - **Logic:** This version uses an efficient **sliding window sum** technique to calculate both the SMA and the Mean Absolute Deviation (MAD). This is a very close approximation of the precise formula but avoids nested loops, making it significantly faster.
 
 2. **Precise Version (`CCI_Precise.mq5`):**
    - **Concept:** A version that adheres strictly to the mathematical definition for maximum accuracy.
-   - **Logic:** This implementation uses nested `for` loops. For every single bar, it recalculates the precise SMA and then the precise MAD based on that SMA. While slightly slower, it guarantees a result that is 100% faithful to the textbook formula.
+   - **Logic:** This implementation uses nested `for` loops. For every single bar, it recalculates the precise SMA and then the precise MAD based on that SMA.
 
-- **Heikin Ashi Variants:**
-  - Both the efficient (`CCI_HeikinAshi.mq5`) and precise (`CCI_Precise_HeikinAshi.mq5`) versions have a "pure" Heikin Ashi counterpart. The calculation logic in each is identical to its standard parent, but they use the smoothed Heikin Ashi price data as their input. This results in a smoother oscillator that reflects the momentum of the underlying Heikin Ashi trend.
+### Indicator Family
+
+- **Line Versions:** `CCI.mq5` and `CCI_Precise.mq5` plot the CCI line and its signal line.
+- **Oscillator Versions:** `CCI_Oscillator.mq5` and `CCI_Precise_Oscillator.mq5` plot the difference between the CCI and its signal line as a histogram.
+- **Heikin Ashi Variants:** All four indicators have "pure" Heikin Ashi counterparts, which use smoothed Heikin Ashi price data as their input.
 
 ## 4. Parameters
 
@@ -63,9 +70,8 @@ Our MQL5 toolkit includes two distinct standard implementations of the CCI, alon
 ## 5. Usage and Interpretation
 
 - **Overbought/Oversold Levels:** The primary use of the CCI is to identify extreme conditions.
-  - **Overbought:** Readings above **+100** are considered overbought, suggesting the price has moved too far, too fast and may be due for a correction.
-  - **Oversold:** Readings below **-100** are considered oversold, suggesting a potential bounce.
-- **Zero Line Crossovers:** A crossover of the CCI line above the zero line is a bullish signal, indicating that momentum has shifted to the upside. A crossover below zero is a bearish signal.
-- **Divergence:** This is a powerful signal. A bearish divergence (higher price highs, lower CCI highs) can signal a potential top. A bullish divergence (lower price lows, higher CCI lows) can signal a potential bottom.
-- **Trend Confirmation:** In an uptrend, the CCI tends to stay above the zero line. In a downtrend, it tends to stay below it.
-- **Caution:** CCI is an unbound oscillator, meaning it has no theoretical upper or lower limit. This makes divergence signals particularly potent. It can produce many signals in choppy markets.
+  - **Overbought:** Readings above **+100**.
+  - **Oversold:** Readings below **-100**.
+- **Zero Line Crossovers:** A crossover of the CCI line above the zero line is a bullish signal; a crossover below zero is a bearish signal.
+- **Divergence:** A powerful signal where price and the CCI move in opposite directions, often foreshadowing a reversal.
+- **Oscillator (Histogram):** The histogram provides a clear visual of the relationship between the CCI and its signal line, highlighting the acceleration and deceleration of momentum.