mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-03 19:57:44 +00:00
Miha Kralj
7253f61299
- Implemented the TRAMA (Trend Regularity Adaptive Moving Average) class with adaptive EMA logic. - Added unit tests for TRAMA functionality, including constructor validation, basic calculations, state management, and robustness checks. - Created validation tests to ensure consistency across different modes of operation (streaming, batch, and static calculations). - Enhanced documentation for TRAMA, including performance profiles and quality metrics. - Updated workspace configuration by removing unnecessary folder references.
419 lines
12 KiB
C#
419 lines
12 KiB
C#
using System.Buffers;
|
|
using System.Runtime.CompilerServices;
|
|
using System.Runtime.InteropServices;
|
|
|
|
namespace QuanTAlib;
|
|
|
|
/// <summary>
|
|
/// KAISER: Kaiser Window Moving Average
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Symmetric FIR filter using the Kaiser-Bessel window function for optimal
|
|
/// sidelobe attenuation. The beta parameter continuously controls the trade-off
|
|
/// between main lobe width (transition band sharpness) and sidelobe attenuation.
|
|
///
|
|
/// Calculation: Precomputed weights via modified Bessel function I0, applied as
|
|
/// FIR convolution over sliding window. Beta=0 gives SMA, beta≈5.65 Blackman,
|
|
/// beta≈8.6 Hamming.
|
|
/// </remarks>
|
|
/// <seealso href="Kaiser.md">Detailed documentation</seealso>
|
|
[SkipLocalsInit]
|
|
public sealed class Kaiser : AbstractBase
|
|
{
|
|
private readonly int _period;
|
|
private readonly double _beta;
|
|
private readonly double[] _weights;
|
|
private readonly RingBuffer _buffer;
|
|
private readonly ITValuePublisher? _source;
|
|
private readonly TValuePublishedHandler? _pubHandler;
|
|
private bool _isNew = true;
|
|
private bool _disposed;
|
|
private double _lastValidValue = double.NaN;
|
|
private double _p_lastValidValue = double.NaN;
|
|
|
|
public bool IsNew => _isNew;
|
|
public override bool IsHot => _buffer.IsFull;
|
|
|
|
/// <summary>
|
|
/// Creates KAISER with specified period and beta.
|
|
/// </summary>
|
|
/// <param name="period">Lookback period (>= 2)</param>
|
|
/// <param name="beta">Shape parameter controlling sidelobe attenuation (0..20, default 3.0)</param>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public Kaiser(int period = 14, double beta = 3.0)
|
|
{
|
|
if (period < 2)
|
|
{
|
|
throw new ArgumentException("Period must be at least 2", nameof(period));
|
|
}
|
|
if (beta < 0)
|
|
{
|
|
throw new ArgumentException("Beta must be non-negative", nameof(beta));
|
|
}
|
|
|
|
_period = period;
|
|
_beta = beta;
|
|
Name = $"Kaiser({_period},{_beta:F1})";
|
|
WarmupPeriod = _period;
|
|
|
|
_buffer = new RingBuffer(_period);
|
|
_weights = new double[_period];
|
|
|
|
ComputeKaiserWeights(_weights, _period, _beta);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Creates KAISER connected to a data source for event-based updates.
|
|
/// </summary>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public Kaiser(ITValuePublisher source, int period = 14, double beta = 3.0) : this(period, beta)
|
|
{
|
|
_source = source;
|
|
_pubHandler = Handle;
|
|
_source.Pub += _pubHandler;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Modified Bessel function of the first kind, order 0.
|
|
/// 25-term power series: I0(x) = sum_{m=0}^{25} [(x/2)^m / m!]^2
|
|
/// </summary>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private static double BesselI0(double x)
|
|
{
|
|
double sum = 1.0;
|
|
double term = 1.0;
|
|
double halfX = x * 0.5;
|
|
for (int m = 1; m <= 25; m++)
|
|
{
|
|
term *= halfX / m;
|
|
sum += term * term;
|
|
}
|
|
return sum;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Computes Kaiser window weights and normalizes to sum=1.
|
|
/// w(k) = I0(beta * sqrt(1 - t^2)) / I0(beta), where t = 2k/(N-1) - 1.
|
|
/// </summary>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private static void ComputeKaiserWeights(Span<double> weights, int period, double beta)
|
|
{
|
|
double i0Beta = BesselI0(beta);
|
|
double nm1 = period - 1;
|
|
|
|
double wsum = 0.0;
|
|
for (int k = 0; k < period; k++)
|
|
{
|
|
double t = nm1 > 0 ? (2.0 * k / nm1) - 1.0 : 0.0;
|
|
double argSq = 1.0 - t * t;
|
|
double arg = argSq > 0 ? Math.Sqrt(argSq) : 0.0;
|
|
double w = i0Beta > 0 ? BesselI0(beta * arg) / i0Beta : 1.0;
|
|
weights[k] = w;
|
|
wsum += w;
|
|
}
|
|
|
|
if (Math.Abs(wsum) > double.Epsilon)
|
|
{
|
|
double inv = 1.0 / wsum;
|
|
for (int k = 0; k < period; k++)
|
|
{
|
|
weights[k] *= inv;
|
|
}
|
|
}
|
|
}
|
|
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public override TValue Update(TValue input, bool isNew = true)
|
|
{
|
|
_isNew = isNew;
|
|
return Update(input, isNew, publish: true);
|
|
}
|
|
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private TValue Update(TValue input, bool isNew, bool publish)
|
|
{
|
|
if (isNew)
|
|
{
|
|
_p_lastValidValue = _lastValidValue;
|
|
}
|
|
else
|
|
{
|
|
_lastValidValue = _p_lastValidValue;
|
|
}
|
|
|
|
double val = GetValidValue(input.Value);
|
|
|
|
if (!double.IsFinite(val))
|
|
{
|
|
Last = new TValue(input.Time, double.NaN);
|
|
if (publish) { PubEvent(Last, isNew); }
|
|
return Last;
|
|
}
|
|
|
|
if (isNew)
|
|
{
|
|
_lastValidValue = val;
|
|
_buffer.Add(val);
|
|
|
|
int count = _buffer.Count;
|
|
double result;
|
|
|
|
if (count < _period)
|
|
{
|
|
result = val;
|
|
}
|
|
else
|
|
{
|
|
result = ConvolveFull(_buffer, _weights);
|
|
}
|
|
|
|
Last = new TValue(input.Time, result);
|
|
if (publish) { PubEvent(Last, isNew); }
|
|
return Last;
|
|
}
|
|
else
|
|
{
|
|
_buffer.Snapshot();
|
|
double prevLast = _lastValidValue;
|
|
double prevPLast = _p_lastValidValue;
|
|
|
|
_lastValidValue = val;
|
|
_buffer.UpdateNewest(val);
|
|
|
|
int count = _buffer.Count;
|
|
double result;
|
|
|
|
if (count < _period)
|
|
{
|
|
result = val;
|
|
}
|
|
else
|
|
{
|
|
result = ConvolveFull(_buffer, _weights);
|
|
}
|
|
|
|
Last = new TValue(input.Time, result);
|
|
|
|
_buffer.Restore();
|
|
_lastValidValue = prevLast;
|
|
_p_lastValidValue = prevPLast;
|
|
|
|
if (publish) { PubEvent(Last, isNew); }
|
|
return Last;
|
|
}
|
|
}
|
|
|
|
public override TSeries Update(TSeries source)
|
|
{
|
|
if (source.Count == 0)
|
|
{
|
|
return new TSeries([], []);
|
|
}
|
|
|
|
int len = source.Count;
|
|
var t = new List<long>(len);
|
|
var v = new List<double>(len);
|
|
CollectionsMarshal.SetCount(t, len);
|
|
CollectionsMarshal.SetCount(v, len);
|
|
|
|
var tSpan = CollectionsMarshal.AsSpan(t);
|
|
var vSpan = CollectionsMarshal.AsSpan(v);
|
|
|
|
Batch(source.Values, vSpan, _period, _beta);
|
|
source.Times.CopyTo(tSpan);
|
|
|
|
Reset();
|
|
int startIndex = Math.Max(0, len - _period);
|
|
for (int i = startIndex; i < len; i++)
|
|
{
|
|
Update(source[i], isNew: true, publish: false);
|
|
}
|
|
|
|
return new TSeries(t, v);
|
|
}
|
|
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private void Handle(object? sender, in TValueEventArgs e) => Update(e.Value, e.IsNew);
|
|
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private double GetValidValue(double input)
|
|
{
|
|
if (double.IsFinite(input))
|
|
{
|
|
return input;
|
|
}
|
|
return double.IsFinite(_lastValidValue) ? _lastValidValue : double.NaN;
|
|
}
|
|
|
|
/// <summary>
|
|
/// FIR convolution using SIMD DotProduct over circular buffer.
|
|
/// Weight[0] corresponds to oldest bar, Weight[period-1] to newest.
|
|
/// </summary>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
private static double ConvolveFull(RingBuffer buffer, double[] weights)
|
|
{
|
|
ReadOnlySpan<double> internalBuf = buffer.InternalBuffer;
|
|
int head = buffer.StartIndex;
|
|
int period = buffer.Capacity;
|
|
|
|
int part1Len = period - head;
|
|
double sum1 = internalBuf.Slice(head, part1Len).DotProduct(weights.AsSpan(0, part1Len));
|
|
double sum2 = internalBuf[..head].DotProduct(weights.AsSpan(part1Len));
|
|
|
|
return sum1 + sum2;
|
|
}
|
|
|
|
public override void Prime(ReadOnlySpan<double> source, TimeSpan? step = null)
|
|
{
|
|
foreach (var value in source)
|
|
{
|
|
Update(new TValue(DateTime.MinValue, value));
|
|
}
|
|
}
|
|
|
|
public static TSeries Batch(TSeries source, int period = 14, double beta = 3.0)
|
|
{
|
|
var kaiser = new Kaiser(period, beta);
|
|
return kaiser.Update(source);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Calculates Kaiser Window MA over a span of values.
|
|
/// </summary>
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public static void Batch(ReadOnlySpan<double> source, Span<double> output, int period = 14, double beta = 3.0, double nanValue = double.NaN)
|
|
{
|
|
if (period < 2)
|
|
{
|
|
throw new ArgumentException("Period must be at least 2", nameof(period));
|
|
}
|
|
if (source.Length != output.Length)
|
|
{
|
|
throw new ArgumentException("Source and output must have the same length", nameof(output));
|
|
}
|
|
if (source.Length == 0)
|
|
{
|
|
return;
|
|
}
|
|
|
|
int len = source.Length;
|
|
const int StackallocThreshold = 256;
|
|
|
|
double[]? weightsRented = period > StackallocThreshold ? ArrayPool<double>.Shared.Rent(period) : null;
|
|
Span<double> weights = period <= StackallocThreshold
|
|
? stackalloc double[period]
|
|
: weightsRented!.AsSpan(0, period);
|
|
|
|
double[]? ringRented = period > StackallocThreshold ? ArrayPool<double>.Shared.Rent(period) : null;
|
|
Span<double> ring = period <= StackallocThreshold
|
|
? stackalloc double[period]
|
|
: ringRented!.AsSpan(0, period);
|
|
|
|
double[]? cleanRented = len > StackallocThreshold ? ArrayPool<double>.Shared.Rent(len) : null;
|
|
Span<double> clean = len <= StackallocThreshold
|
|
? stackalloc double[len]
|
|
: cleanRented!.AsSpan(0, len);
|
|
|
|
ComputeKaiserWeights(weights, period, beta);
|
|
|
|
try
|
|
{
|
|
double lastValid = nanValue;
|
|
for (int i = 0; i < len; i++)
|
|
{
|
|
double val = source[i];
|
|
if (double.IsFinite(val))
|
|
{
|
|
lastValid = val;
|
|
clean[i] = val;
|
|
}
|
|
else if (double.IsFinite(lastValid))
|
|
{
|
|
clean[i] = lastValid;
|
|
}
|
|
else
|
|
{
|
|
clean[i] = double.NaN;
|
|
}
|
|
}
|
|
|
|
int ringIdx = 0;
|
|
int count = 0;
|
|
|
|
for (int i = 0; i < len; i++)
|
|
{
|
|
double val = clean[i];
|
|
|
|
ring[ringIdx] = val;
|
|
ringIdx++;
|
|
if (ringIdx >= period)
|
|
{
|
|
ringIdx = 0;
|
|
}
|
|
|
|
if (count < period)
|
|
{
|
|
count++;
|
|
}
|
|
|
|
if (count < period)
|
|
{
|
|
output[i] = val;
|
|
continue;
|
|
}
|
|
|
|
int part1Len = period - ringIdx;
|
|
|
|
ReadOnlySpan<double> ringRo = ring;
|
|
double sum = ringRo.Slice(ringIdx, part1Len).DotProduct(weights.Slice(0, part1Len))
|
|
+ ringRo[..ringIdx].DotProduct(weights.Slice(part1Len));
|
|
|
|
output[i] = sum;
|
|
}
|
|
}
|
|
finally
|
|
{
|
|
if (weightsRented != null)
|
|
{
|
|
ArrayPool<double>.Shared.Return(weightsRented);
|
|
}
|
|
if (ringRented != null)
|
|
{
|
|
ArrayPool<double>.Shared.Return(ringRented);
|
|
}
|
|
if (cleanRented != null)
|
|
{
|
|
ArrayPool<double>.Shared.Return(cleanRented);
|
|
}
|
|
}
|
|
}
|
|
|
|
public static (TSeries Results, Kaiser Indicator) Calculate(TSeries source, int period = 14, double beta = 3.0)
|
|
{
|
|
var indicator = new Kaiser(period, beta);
|
|
TSeries results = indicator.Update(source);
|
|
return (results, indicator);
|
|
}
|
|
|
|
public override void Reset()
|
|
{
|
|
_buffer.Clear();
|
|
_lastValidValue = double.NaN;
|
|
_p_lastValidValue = double.NaN;
|
|
Last = default;
|
|
}
|
|
|
|
protected override void Dispose(bool disposing)
|
|
{
|
|
if (!_disposed)
|
|
{
|
|
if (disposing && _source != null && _pubHandler != null)
|
|
{
|
|
_source.Pub -= _pubHandler;
|
|
}
|
|
_disposed = true;
|
|
}
|
|
base.Dispose(disposing);
|
|
}
|
|
}
|