Create EFI - Elder Ray's Force Index - add tests and xml comments

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/mihakralj/QuanTAlib?shareId=XXXX-XXXX-XXXX-XXXX).

Tests/test_updates_oscillators.cs

@@ -321,4 +321,20 @@ public class OscillatorsUpdateTests
 
         Assert.Equal(initialValue, finalValue, precision);
     }
+
+    [Fact]
+    public void Efi_Update()
+    {
+        var indicator = new Efi(period: 13);
+        TBar r = GetRandomBar(true);
+        double initialValue = indicator.Calc(r);
+
+        for (int i = 0; i < RandomUpdates; i++)
+        {
+            indicator.Calc(GetRandomBar(IsNew: false));
+        }
+        double finalValue = indicator.Calc(new TBar(r.Time, r.Open, r.High, r.Low, r.Close, r.Volume, IsNew: false));
+
+        Assert.Equal(initialValue, finalValue, precision);
+    }
 }

docs/indicators/indicators.md

@@ -5,12 +5,12 @@
 | Basic Transforms | 6 of 6 | 100% |
 | Averages & Trends | 33 of 33 | 100% |
 | Momentum | 16 of 16 | 100% |
-| Oscillators | 21 of 29 | 72% |
+| Oscillators | 22 of 29 | 76% |
 | Volatility | 24 of 35 | 69% |
 | Volume | 15 of 19 | 79% |
 | Numerical Analysis | 13 of 19 | 68% |
 | Errors | 16 of 16 | 100% |
-| **Total** | **144 of 173** | **83%** |
+| **Total** | **145 of 173** | **84%** |
 
 |Technical Indicator Name| Class Name|
 |-----------|:----------:|
@@ -85,9 +85,9 @@
 |COPPOCK - Coppock Curve|`Coppock`|
 |CRSI - Connor RSI|`Crsi`|
 |🚧 CTI - Ehler's Correlation Trend Indicator|`Cti`|
-|🚧 EFI - Elder Ray's Force Index|`Efi`|
 |🚧 FISHER - Fisher Transform|`Fisher`|
 |🚧 FOSC - Forecast Oscillator|`Fosc`|
+|EFI - Elder Ray's Force Index|`Efi`|
 |🚧 GATOR* - Williams Alliator Oscillator (Upper Jaw, Lower Jaw, Teeth)|`Gator`|
 |🚧 KDJ* - KDJ Indicator (K, D, J lines)|`Kdj`|
 |🚧 KRI - Kairi Relative Index|`Kri`|

lib/oscillators/Efi.cs

@@ -0,0 +1,104 @@
+using System.Runtime.CompilerServices;
+namespace QuanTAlib;
+
+/// <summary>
+/// EFI: Elder Ray's Force Index
+/// A volume-based oscillator that measures the strength of price movements using volume.
+/// It helps identify potential trend reversals and confirm price movements.
+/// </summary>
+/// <remarks>
+/// The EFI calculation process:
+/// 1. Calculate the difference between the current close and the previous close
+/// 2. Multiply the difference by the current volume
+/// 3. Apply an exponential moving average (EMA) to smooth the result
+///
+/// Key characteristics:
+/// - Oscillates above and below zero
+/// - Positive values indicate buying pressure
+/// - Negative values indicate selling pressure
+/// - Crosses above zero suggest buying opportunities
+/// - Crosses below zero suggest selling opportunities
+///
+/// Formula:
+/// EFI = EMA((Close - Close[1]) * Volume, period)
+///
+/// Sources:
+///     Alexander Elder - "Trading for a Living" (1993)
+///     https://www.investopedia.com/terms/f/force-index.asp
+///
+/// Note: Default period is 13
+/// </remarks>
+[SkipLocalsInit]
+public sealed class Efi : AbstractBase
+{
+    private readonly Ema _ema;
+    private double _prevClose;
+    private double _p_prevClose;
+    private const int DefaultPeriod = 13;
+
+    /// <param name="period">The smoothing period for EMA calculation (default 13).</param>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when period is less than 1.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Efi(int period = DefaultPeriod)
+    {
+        if (period < 1)
+            throw new ArgumentOutOfRangeException(nameof(period));
+
+        _ema = new(period);
+        WarmupPeriod = period + 1;
+        Name = $"EFI({period})";
+    }
+
+    /// <param name="source">The data source object that publishes updates.</param>
+    /// <param name="period">The smoothing period for EMA calculation.</param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Efi(object source, int period = DefaultPeriod) : this(period)
+    {
+        var pubEvent = source.GetType().GetEvent("Pub");
+        pubEvent?.AddEventHandler(source, new BarSignal(Sub));
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public override void Init()
+    {
+        base.Init();
+        _ema.Init();
+        _prevClose = double.NaN;
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    protected override void ManageState(bool isNew)
+    {
+        if (isNew)
+        {
+            _index++;
+            _p_prevClose = _prevClose;
+        }
+        else
+        {
+            _prevClose = _p_prevClose;
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
+    protected override double Calculation()
+    {
+        ManageState(BarInput.IsNew);
+
+        if (_index == 1)
+        {
+            _prevClose = BarInput.Close;
+            return 0;
+        }
+
+        // Calculate raw force index
+        double priceChange = BarInput.Close - _prevClose;
+        double forceIndex = priceChange * BarInput.Volume;
+
+        // Update previous close
+        _prevClose = BarInput.Close;
+
+        // Apply EMA smoothing
+        return _ema.Calc(forceIndex, BarInput.IsNew);
+    }
+}

lib/oscillators/_list.md

@@ -1,5 +1,5 @@
 # Oscillators indicators
-Done: 21, Todo: 8
+Done: 22, Todo: 7
 
 ✔️ AC - Acceleration Oscillator
 ✔️ AO - Awesome Oscillator
@@ -14,7 +14,7 @@ Done: 21, Todo: 8
 ✔️ CRSI - Connor RSI
 CTI - Ehler's Correlation Trend Indicator
 ✔️ DOSC - Derivative Oscillator
-EFI - Elder Ray's Force Index
+✔️ EFI - Elder Ray's Force Index
 FISHER - Fisher Transform
 FOSC - Forecast Oscillator
 *GATOR - Williams Alliator Oscillator (Upper Jaw, Lower Jaw, Teeth)