refactor: add oscillators

Indicators/MyIndicators/RSIMa.md

@@ -1,63 +1,63 @@
-# Moving Average of RSI (RSIMA)
+# Moving Average of RSI (RSI with Signal Line)
 
 ## 1. Summary (Introduction)
 
-The Moving Average of RSI, often referred to as RSIMA, is a technical indicator that smooths the standard Relative Strength Index (RSI) with a moving average. While the RSI is a powerful momentum oscillator, it can often be volatile, producing sharp movements and "noisy" signals.
+This indicator plots the standard Relative Strength Index (RSI) and overlays a moving average of the RSI, which acts as a **signal line**. While the RSI is a powerful momentum oscillator, it can often be volatile. Applying a moving average filters out short-term noise, providing a smoother line that can make the underlying momentum trend easier to identify.
 
-By applying a moving average to the RSI line, the RSIMA filters out this short-term noise, providing a smoother line that can make the underlying momentum trend easier to identify. It essentially acts as a signal line for the RSI, similar to how the %D line acts as a signal line for the Stochastic Oscillator.
+The **RSI Oscillator** is a supplementary indicator that displays the difference between the main RSI line and its signal line as a histogram. It provides a clearer visual representation of accelerating and decelerating momentum, similar to the MACD histogram.
 
 ## 2. Mathematical Foundations and Calculation Logic
 
-The RSIMA is a two-stage indicator. It first calculates the standard RSI and then applies a moving average to the resulting RSI values.
+The indicator is a two-stage process. It first calculates the standard RSI and then applies a moving average to the resulting RSI values.
 
 ### Required Components
 
 - **RSI (Relative Strength Index):** The underlying momentum oscillator.
-- **Moving Average (MA):** The smoothing mechanism applied to the RSI line. This can be a Simple (SMA), Exponential (EMA), Smoothed (SMMA), or Linear Weighted (LWMA) moving average.
+- **Moving Average (MA):** The smoothing mechanism applied to the RSI line.
 
 ### Calculation Steps (Algorithm)
 
-1. **Calculate the RSI:** First, calculate the standard RSI for a given period (e.g., 14) on the source price (e.g., Close). The RSI formula is based on Wilder's smoothing of average gains and average losses.
+1. **Calculate the RSI:** First, calculate the standard RSI for a given period (e.g., 14) on the source price. The RSI formula is based on Wilder's smoothing of average gains and average losses.
    $\text{RS}_i = \frac{\text{Wilder's MA}(\text{Up Moves}, \text{RSI Period})_i}{\text{Wilder's MA}(\text{Down Moves}, \text{RSI Period})_i}$
    $\text{RSI}_i = 100 - \frac{100}{1 + \text{RS}_i}$
 
-2. **Calculate the Moving Average of RSI:** Apply the selected moving average type with its specified period to the RSI data series calculated in the first step.
-   $\text{RSIMA}_i = \text{MA}(\text{RSI}, \text{MA Period})_i$
+2. **Calculate the Moving Average of RSI (Signal Line):** Apply the selected moving average type with its specified period to the RSI data series calculated in the first step.
+   $\text{Signal Line}_i = \text{MA}(\text{RSI}, \text{MA Period})_i$
+
+3. **Calculate the RSI Oscillator:** The oscillator is the difference between the RSI line and its Signal Line.
+   $\text{Oscillator}_i = \text{RSI}_i - \text{Signal Line}_i$
 
 ## 3. MQL5 Implementation Details
 
-Our MQL5 implementation is designed for stability, clarity, and consistency with our existing indicator toolkit.
+Our MQL5 implementations are designed for stability, clarity, and consistency.
 
-- **Stability via Full Recalculation:** We employ a "brute-force" full recalculation within the `OnCalculate` function. This is our standard practice for indicators involving recursive calculations (like EMA or SMMA) to ensure maximum stability and prevent errors during timeframe changes or history loading.
+- **Stability via Full Recalculation:** All versions employ a "brute-force" full recalculation within the `OnCalculate` function for maximum stability.
 
-- **Leveraging Standard Indicators:** For the initial RSI calculation, we use a handle to MQL5's built-in `iRSI` indicator. This is a robust and efficient method for obtaining the underlying RSI data series. The handle's resources are properly managed and released in the `OnDeinit` function.
+- **Self-Contained Logic:** All versions are completely self-contained. The standard version uses a handle to MQL5's built-in `iRSI` for efficiency, while the Heikin Ashi version uses our custom `CHeikinAshi_RSI_Calculator`.
 
-- **Robust EMA/SMMA Initialization:** This is the most critical part of the implementation. Standard library functions for recursive MAs can be unstable in a full recalculation model. To guarantee stability, we take control of the initialization process:
+- **Fully Manual MA Calculations:** To guarantee 100% accuracy and consistency, all moving average calculations for the signal line (**SMA, EMA, SMMA, LWMA**) are performed **manually**. This makes the indicators independent of the `<MovingAverages.mqh>` library and ensures robust behavior on `non-timeseries` arrays.
 
-  - For EMA and SMMA calculations, the **first value** of the moving average is calculated using a **manual Simple Moving Average (SMA)** on the preceding RSI data.
-  - This provides a stable, valid starting point for all subsequent recursive calculations, completely eliminating the risk of floating-point overflows that can occur with uninitialized data.
+- **Indicator Family:**
 
-- **Clear, Staged Calculation:** The `OnCalculate` function is structured into two clear, sequential steps:
-
-  1. **Step 1:** The complete RSI data series is retrieved into the `BufferRawRSI` calculation buffer using `CopyBuffer`.
-  2. **Step 2:** A single `for` loop calculates the moving average on the `BufferRawRSI` data, utilizing our robust `switch` block to handle the different MA types and their specific initialization needs.
+  - **Line Versions:** `RSIMA.mq5` and `RSI_HeikinAshi.mq5` plot the RSI line and its signal line.
+  - **Oscillator Versions:** `RSI_Oscillator.mq5` and `RSI_Oscillator_HeikinAshi.mq5` plot the difference between the two lines as a histogram.
 
 - **Heikin Ashi Variant (`RSI_HeikinAshi.mq5`):**
-  - Our toolkit also includes a Heikin Ashi version of this indicator. The calculation logic is identical, but it uses the smoothed Heikin Ashi `ha_close` values as the input for the initial RSI calculation.
-  - This results in a doubly-smoothed oscillator, ideal for traders who want to focus only on the most significant, sustained momentum shifts.
+  - Our toolkit also includes a Heikin Ashi version. The calculation logic is identical, but it uses the smoothed Heikin Ashi `ha_close` values as the input for the initial RSI calculation. This results in a doubly-smoothed oscillator.
 
 ## 4. Parameters
 
 - **RSI Period (`InpPeriodRSI`):** The lookback period for the underlying RSI calculation. Default is `14`.
-- **Applied Price (`InpAppliedPrice`):** The source price used for the RSI calculation (e.g., `PRICE_CLOSE`).
-- **MA Period (`InpPeriodMA`):** The lookback period for the moving average that smooths the RSI line. Default is `14`.
-- **MA Method (`InpMethod`):** The type of moving average to use for smoothing (SMA, EMA, SMMA, LWMA). Default is `MODE_SMA`.
+- **Applied Price (`InpAppliedPrice`):** The source price used for the RSI calculation (standard version only).
+- **Signal Line Settings:**
+  - `InpPeriodMA`: The lookback period for the moving average that smooths the RSI line.
+  - `InpMethodMA`: The type of moving average to use for smoothing (SMA, EMA, SMMA, LWMA).
 
 ## 5. Usage and Interpretation
 
-- **Trend and Momentum Confirmation:** The primary use of the RSIMA is to provide a clearer view of momentum. When the RSIMA line is rising, it confirms bullish momentum; when it's falling, it confirms bearish momentum.
+- **Trend and Momentum Confirmation:** The primary use is to provide a clearer view of momentum. When the signal line is rising, it confirms bullish momentum; when it's falling, it confirms bearish momentum.
 - **Signal Generation via Crossovers:**
-  - **RSI / RSIMA Crossover:** When the raw RSI line (green) crosses above its moving average (blue), it can be seen as a bullish signal. A cross below is a bearish signal.
-  - **Centerline Crossover:** A crossover of the RSIMA line above the 50 level indicates that bulls are in control. A crossover below 50 indicates bears are in control.
-- **Smoothed Overbought/Oversold Signals:** The RSIMA line entering the overbought (above 70/80) or oversold (below 30/20) zones provides a more filtered, less frequent signal than the raw RSI.
-- **Caution:** The smoothing process introduces lag. The RSIMA will always react slower than the raw RSI. This filtering is its main advantage, but traders should be aware of the delay.
+  - **RSI / Signal Line Crossover:** When the raw RSI line crosses above its moving average, it can be seen as a bullish signal. A cross below is a bearish signal.
+  - **Centerline Crossover:** A crossover of the signal line above the 50 level indicates that bulls are in control. A crossover below 50 indicates bears are in control.
+- **Oscillator (Histogram):** The histogram provides a clear visual of the relationship between the RSI and its signal line, highlighting the acceleration and deceleration of momentum.
+- **Caution:** The smoothing process introduces lag. The signal line will always react slower than the raw RSI. This filtering is its main advantage, but traders should be aware of the delay.