QuanTAlib/lib/averages/Hma.cs

using System;
namespace QuanTAlib;

/// <summary>
/// HMA: Hull Moving Average
/// A moving average designed by Alan Hull to reduce lag while maintaining smoothness.
/// It combines weighted moving averages of different periods to achieve better
/// responsiveness to price changes while minimizing noise.
/// </summary>
/// <remarks>
/// The HMA calculation process:
/// 1. Calculate WMA with period n/2
/// 2. Calculate WMA with period n
/// 3. Calculate difference: 2*WMA(n/2) - WMA(n)
/// 4. Apply final WMA with period sqrt(n) to the difference
///
/// Key characteristics:
/// - Significantly reduced lag compared to traditional moving averages
/// - Maintains smoothness despite the reduced lag
/// - Responds more quickly to price changes
/// - Better at identifying trend changes
/// - Uses weighted moving averages for all calculations
///
/// Sources:
///     Alan Hull - "Better Trading with Hull Moving Average"
///     https://alanhull.com/hull-moving-average
/// </remarks>

public class Hma : AbstractBase
{
    private readonly Convolution _wmaHalf, _wmaFull, _wmaFinal;

    /// <param name="period">The number of data points used in the HMA calculation. Must be at least 2.</param>
    /// <exception cref="ArgumentException">Thrown when period is less than 2.</exception>
    public Hma(int period)
    {
        if (period < 2)
        {
            throw new ArgumentException("Period must be greater than or equal to 2.", nameof(period));
        }
        int _sqrtPeriod = (int)Math.Sqrt(period);
        _wmaHalf = new Convolution(GenerateWmaKernel(period / 2));
        _wmaFull = new Convolution(GenerateWmaKernel(period));
        _wmaFinal = new Convolution(GenerateWmaKernel(_sqrtPeriod));
        Name = "Hma";
        WarmupPeriod = period + _sqrtPeriod - 1;
        Init();
    }

    /// <param name="source">The data source object that publishes updates.</param>
    /// <param name="period">The number of data points used in the HMA calculation.</param>
    public Hma(object source, int period) : this(period)
    {
        var pubEvent = source.GetType().GetEvent("Pub");
        pubEvent?.AddEventHandler(source, new ValueSignal(Sub));
    }

    /// <summary>
    /// Generates the weighted moving average kernel for the HMA calculation.
    /// </summary>
    /// <param name="period">The period for which to generate the kernel.</param>
    /// <returns>An array of linearly weighted values for the convolution operation.</returns>
    private static double[] GenerateWmaKernel(int period)
    {
        double[] kernel = new double[period];
        double weightSum = period * (period + 1) / 2.0;

        for (int i = 0; i < period; i++)
        {
            kernel[i] = (period - i) / weightSum;
        }

        return kernel;
    }

    private new void Init()
    {
        base.Init();
        _wmaHalf.Init();
        _wmaFull.Init();
        _wmaFinal.Init();
    }

    protected override void ManageState(bool isNew)
    {
        if (isNew)
        {
            _lastValidValue = Input.Value;
            _index++;
        }
    }

    protected override double Calculation()
    {
        ManageState(Input.IsNew);

        // Calculate WMA(n/2) and WMA(n)
        double wmaHalfResult = _wmaHalf.Calc(Input).Value;
        double wmaFullResult = _wmaFull.Calc(Input).Value;

        // Calculate 2*WMA(n/2) - WMA(n)
        double intermediateResult = 2 * wmaHalfResult - wmaFullResult;

        // Calculate final WMA
        double result = _wmaFinal.Calc(new TValue(Input.Time, intermediateResult, Input.IsNew)).Value;

        IsHot = _index >= WarmupPeriod;
        return result;
    }
}