mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-01 03:07:43 +00:00
Miha Kralj
281 lines
8.3 KiB
C#
281 lines
8.3 KiB
C#
// STANDARDIZE: Z-Score Normalization
|
||
// Calculates the z-score (standard score) of values over a lookback period
|
||
// Formula: z = (x - μ) / σ where σ uses sample standard deviation (N-1)
|
||
|
||
using System.Runtime.CompilerServices;
|
||
using System.Runtime.InteropServices;
|
||
|
||
namespace QuanTAlib;
|
||
|
||
/// <summary>
|
||
/// STANDARDIZE: Z-Score Normalization
|
||
/// Calculates the z-score of values over a lookback period using sample standard deviation.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// Key properties:
|
||
/// - Output is unbounded (can be any real number, typically -3 to +3 for normal data)
|
||
/// - Uses sample standard deviation (Bessel's correction, N-1 denominator)
|
||
/// - Requires period >= 2 for meaningful standard deviation calculation
|
||
/// - When stdev is zero (flat data), returns 0 if value equals mean, NaN otherwise
|
||
/// - Commonly used for anomaly detection and inter-series comparison
|
||
///
|
||
/// Formula: z = (x - mean) / sample_stdev
|
||
/// where sample_stdev = sqrt(sum((x_i - mean)^2) / (N - 1))
|
||
/// </remarks>
|
||
[SkipLocalsInit]
|
||
public sealed class Standardize : AbstractBase
|
||
{
|
||
private readonly int _period;
|
||
private readonly RingBuffer _buffer;
|
||
|
||
// Welford's online algorithm state for numerical stability
|
||
[StructLayout(LayoutKind.Auto)]
|
||
private record struct State(double LastValidZScore, double Sum, double SumSq, int ValidCount);
|
||
private State _state, _p_state;
|
||
|
||
public override bool IsHot => _buffer.Count >= _period;
|
||
|
||
/// <summary>
|
||
/// Initializes a new Standardize indicator with specified lookback period.
|
||
/// </summary>
|
||
/// <param name="period">Lookback period for z-score calculation (default 20, must be >= 2)</param>
|
||
public Standardize(int period = 20)
|
||
{
|
||
if (period < 2)
|
||
{
|
||
throw new ArgumentException("Period must be >= 2 for sample standard deviation", nameof(period));
|
||
}
|
||
|
||
_period = period;
|
||
_buffer = new RingBuffer(period);
|
||
Name = $"Standardize({period})";
|
||
WarmupPeriod = period;
|
||
_state = new State(0.0, 0.0, 0.0, 0);
|
||
_p_state = _state;
|
||
}
|
||
|
||
/// <summary>
|
||
/// Initializes a new Standardize indicator with source for event-based chaining.
|
||
/// </summary>
|
||
/// <param name="source">Source indicator for chaining</param>
|
||
/// <param name="period">Lookback period (default 20)</param>
|
||
public Standardize(ITValuePublisher source, int period = 20) : this(period)
|
||
{
|
||
source.Pub += HandleUpdate;
|
||
}
|
||
|
||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||
private void HandleUpdate(object? sender, in TValueEventArgs e) => Update(e.Value, e.IsNew);
|
||
|
||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||
public override TValue Update(TValue input, bool isNew = true)
|
||
{
|
||
if (isNew)
|
||
{
|
||
_p_state = _state;
|
||
}
|
||
else
|
||
{
|
||
_state = _p_state;
|
||
}
|
||
|
||
double value = input.Value;
|
||
double result;
|
||
|
||
if (double.IsFinite(value))
|
||
{
|
||
_buffer.Add(value, isNew);
|
||
|
||
// Compute mean and sample variance from buffer
|
||
ReadOnlySpan<double> data = _buffer.GetSpan();
|
||
int n = data.Length;
|
||
|
||
if (n < 2)
|
||
{
|
||
// Not enough data for sample stdev
|
||
result = 0.0;
|
||
_state = new State(result, value, value * value, 1);
|
||
}
|
||
else
|
||
{
|
||
// Calculate sum and sum of squares
|
||
double sum = 0.0;
|
||
double sumSq = 0.0;
|
||
|
||
for (int i = 0; i < n; i++)
|
||
{
|
||
double v = data[i];
|
||
sum += v;
|
||
sumSq += v * v;
|
||
}
|
||
|
||
double mean = sum / n;
|
||
|
||
// Population variance: (sumSq / n) - mean^2
|
||
// Sample variance: (sumSq - n * mean^2) / (n - 1) = n / (n-1) * popVar
|
||
double popVariance = (sumSq / n) - (mean * mean);
|
||
|
||
// Numerical stability: clamp tiny negative values to zero
|
||
if (popVariance < 1e-10)
|
||
{
|
||
popVariance = 0.0;
|
||
}
|
||
|
||
double sampleVariance = popVariance * n / (n - 1);
|
||
double stdev = Math.Sqrt(sampleVariance);
|
||
|
||
if (stdev > 1e-10)
|
||
{
|
||
result = (value - mean) / stdev;
|
||
}
|
||
else
|
||
{
|
||
// Stdev is essentially zero - all values are the same
|
||
// Return 0 as neutral z-score
|
||
result = 0.0;
|
||
}
|
||
|
||
_state = new State(result, sum, sumSq, n);
|
||
}
|
||
}
|
||
else
|
||
{
|
||
// Invalid input - return last valid z-score
|
||
result = _state.LastValidZScore;
|
||
}
|
||
|
||
Last = new TValue(input.Time, result);
|
||
PubEvent(Last, isNew);
|
||
return Last;
|
||
}
|
||
|
||
public override TSeries Update(TSeries source)
|
||
{
|
||
var result = new TSeries(source.Count);
|
||
ReadOnlySpan<double> values = source.Values;
|
||
ReadOnlySpan<long> times = source.Times;
|
||
|
||
for (int i = 0; i < source.Count; i++)
|
||
{
|
||
var tv = Update(new TValue(new DateTime(times[i], DateTimeKind.Utc), values[i]), true);
|
||
result.Add(tv, true);
|
||
}
|
||
return result;
|
||
}
|
||
|
||
public override void Prime(ReadOnlySpan<double> source, TimeSpan? step = null)
|
||
{
|
||
TimeSpan interval = step ?? TimeSpan.FromSeconds(1);
|
||
DateTime time = DateTime.UtcNow - (interval * source.Length);
|
||
|
||
for (int i = 0; i < source.Length; i++)
|
||
{
|
||
Update(new TValue(time, source[i]), true);
|
||
time += interval;
|
||
}
|
||
}
|
||
|
||
public static TSeries Batch(TSeries source, int period = 20)
|
||
{
|
||
var indicator = new Standardize(period);
|
||
return indicator.Update(source);
|
||
}
|
||
|
||
/// <summary>
|
||
/// Calculates Z-score normalization over a span of values.
|
||
/// </summary>
|
||
public static void Batch(ReadOnlySpan<double> source, Span<double> output, int period = 20)
|
||
{
|
||
if (source.Length == 0)
|
||
{
|
||
throw new ArgumentException("Source cannot be empty", nameof(source));
|
||
}
|
||
|
||
if (output.Length < source.Length)
|
||
{
|
||
throw new ArgumentException("Output length must be >= source length", nameof(output));
|
||
}
|
||
|
||
if (period < 2)
|
||
{
|
||
throw new ArgumentException("Period must be >= 2", nameof(period));
|
||
}
|
||
|
||
double lastValid = 0.0;
|
||
|
||
for (int i = 0; i < source.Length; i++)
|
||
{
|
||
double val = source[i];
|
||
|
||
if (!double.IsFinite(val))
|
||
{
|
||
output[i] = lastValid;
|
||
continue;
|
||
}
|
||
|
||
// Determine window bounds
|
||
int start = Math.Max(0, i - period + 1);
|
||
int n = 0;
|
||
double sum = 0.0;
|
||
double sumSq = 0.0;
|
||
|
||
// Calculate sum and count of finite values in window
|
||
for (int j = start; j <= i; j++)
|
||
{
|
||
double v = source[j];
|
||
if (double.IsFinite(v))
|
||
{
|
||
sum += v;
|
||
sumSq += v * v;
|
||
n++;
|
||
}
|
||
}
|
||
|
||
if (n < 2)
|
||
{
|
||
output[i] = 0.0;
|
||
lastValid = 0.0;
|
||
continue;
|
||
}
|
||
|
||
double mean = sum / n;
|
||
double popVariance = (sumSq / n) - (mean * mean);
|
||
|
||
if (popVariance < 1e-10)
|
||
{
|
||
popVariance = 0.0;
|
||
}
|
||
|
||
double sampleVariance = popVariance * n / (n - 1);
|
||
double stdev = Math.Sqrt(sampleVariance);
|
||
|
||
double result;
|
||
if (stdev > 1e-10)
|
||
{
|
||
result = (val - mean) / stdev;
|
||
}
|
||
else
|
||
{
|
||
result = 0.0;
|
||
}
|
||
|
||
lastValid = result;
|
||
output[i] = result;
|
||
}
|
||
}
|
||
|
||
public static (TSeries Results, Standardize Indicator) Calculate(TSeries source, int period = 20)
|
||
{
|
||
var indicator = new Standardize(period);
|
||
TSeries results = indicator.Update(source);
|
||
return (results, indicator);
|
||
}
|
||
|
||
public override void Reset()
|
||
{
|
||
_buffer.Clear();
|
||
_state = new State(0.0, 0.0, 0.0, 0);
|
||
_p_state = _state;
|
||
Last = default;
|
||
}
|
||
} |