mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-23 04:58:08 +00:00
Add R² and SMAPE error metrics with comprehensive tests and documentation
- Introduced R² (Coefficient of Determination) metric with detailed mathematical foundation, performance profile, and usage examples. - Implemented SMAPE (Symmetric Mean Absolute Percentage Error) metric, addressing asymmetry in MAPE with symmetric error calculations. - Added unit tests for SMAPE covering various scenarios including edge cases and input validation. - Enhanced Dema class to correctly handle event publishing with isNew parameter. - Updated Quantower test project to include coverage configuration for better test reporting.
This commit is contained in:
Miha Kralj
@@ -0,0 +1,371 @@
|
||||
using Xunit;
|
||||
|
||||
namespace QuanTAlib.Tests;
|
||||
|
||||
public class RmsleTests
|
||||
{
|
||||
private const double Precision = 1e-10;
|
||||
|
||||
[Fact]
|
||||
public void Constructor_ValidatesInput()
|
||||
{
|
||||
Assert.Throws<ArgumentException>(() => new Rmsle(0));
|
||||
Assert.Throws<ArgumentException>(() => new Rmsle(-1));
|
||||
var rmsle = new Rmsle(10);
|
||||
Assert.NotNull(rmsle);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Calc_ReturnsValue()
|
||||
{
|
||||
var rmsle = new Rmsle(10);
|
||||
var result = rmsle.Update(100.0, 90.0);
|
||||
Assert.True(double.IsFinite(result.Value));
|
||||
Assert.Equal(result.Value, rmsle.Last.Value);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ZeroError_ReturnsZero()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
for (int i = 0; i < 5; i++)
|
||||
{
|
||||
rmsle.Update(100.0, 100.0);
|
||||
}
|
||||
Assert.Equal(0.0, rmsle.Last.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void KnownValues_CalculatesCorrectly()
|
||||
{
|
||||
var rmsle = new Rmsle(1);
|
||||
// RMSLE = sqrt((log(1 + actual) - log(1 + predicted))²)
|
||||
// actual=99, predicted=49 -> log(100) - log(50) = ln(2)
|
||||
// RMSLE = |ln(2)| ≈ 0.693
|
||||
var result = rmsle.Update(99.0, 49.0);
|
||||
double expected = Math.Abs(Math.Log(100.0) - Math.Log(50.0));
|
||||
Assert.Equal(expected, result.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void IsSqrtOfMsle()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
var msle = new Msle(5);
|
||||
var gbm = new GBM(startPrice: 100.0, mu: 0.02, sigma: 0.1, seed: 42);
|
||||
|
||||
for (int i = 0; i < 10; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: true);
|
||||
rmsle.Update(bar.Close, bar.Close * 0.95);
|
||||
msle.Update(bar.Close, bar.Close * 0.95);
|
||||
}
|
||||
|
||||
Assert.Equal(Math.Sqrt(msle.Last.Value), rmsle.Last.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Period1_ReturnsCurrentError()
|
||||
{
|
||||
var rmsle = new Rmsle(1);
|
||||
// actual=9, predicted=4 -> log(10) - log(5) = ln(2)
|
||||
var r1 = rmsle.Update(9.0, 4.0);
|
||||
double expected1 = Math.Abs(Math.Log(10.0) - Math.Log(5.0));
|
||||
Assert.Equal(expected1, r1.Value, Precision);
|
||||
|
||||
// Perfect prediction
|
||||
var r2 = rmsle.Update(100.0, 100.0);
|
||||
Assert.Equal(0.0, r2.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ZeroValues_HandledCorrectly()
|
||||
{
|
||||
var rmsle = new Rmsle(1);
|
||||
// actual=0, predicted=0 -> log(1) - log(1) = 0
|
||||
var bothZero = rmsle.Update(0.0, 0.0);
|
||||
Assert.Equal(0.0, bothZero.Value, Precision);
|
||||
|
||||
// actual=0, predicted=9 -> |log(1) - log(10)| = ln(10)
|
||||
var actualZero = rmsle.Update(0.0, 9.0);
|
||||
double expectedActualZero = Math.Abs(Math.Log(1.0) - Math.Log(10.0));
|
||||
Assert.Equal(expectedActualZero, actualZero.Value, Precision);
|
||||
|
||||
// actual=9, predicted=0 -> |log(10) - log(1)| = ln(10)
|
||||
var predZero = rmsle.Update(9.0, 0.0);
|
||||
double expectedPredZero = Math.Abs(Math.Log(10.0) - Math.Log(1.0));
|
||||
Assert.Equal(expectedPredZero, predZero.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void NaN_Input_UsesLastValidValue()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
rmsle.Update(100.0, 90.0);
|
||||
rmsle.Update(100.0, 95.0);
|
||||
|
||||
var resultAfterNaN = rmsle.Update(double.NaN, 90.0);
|
||||
Assert.True(double.IsFinite(resultAfterNaN.Value));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Infinity_Input_UsesLastValidValue()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
rmsle.Update(100.0, 90.0);
|
||||
|
||||
var resultAfterPosInf = rmsle.Update(double.PositiveInfinity, 90.0);
|
||||
Assert.True(double.IsFinite(resultAfterPosInf.Value));
|
||||
|
||||
var resultAfterNegInf = rmsle.Update(100.0, double.NegativeInfinity);
|
||||
Assert.True(double.IsFinite(resultAfterNegInf.Value));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void NegativeValues_TreatedAsInvalid()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
rmsle.Update(100.0, 90.0);
|
||||
|
||||
var resultAfterNeg = rmsle.Update(-50.0, 90.0);
|
||||
Assert.True(double.IsFinite(resultAfterNeg.Value));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void IsHot_BecomesTrueWhenBufferFull()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
Assert.False(rmsle.IsHot);
|
||||
|
||||
for (int i = 1; i <= 4; i++)
|
||||
{
|
||||
rmsle.Update(100.0, 90.0 + i);
|
||||
Assert.False(rmsle.IsHot);
|
||||
}
|
||||
|
||||
rmsle.Update(100.0, 95.0);
|
||||
Assert.True(rmsle.IsHot);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Reset_ClearsState()
|
||||
{
|
||||
var rmsle = new Rmsle(10);
|
||||
rmsle.Update(100.0, 90.0);
|
||||
rmsle.Update(100.0, 95.0);
|
||||
|
||||
rmsle.Reset();
|
||||
|
||||
Assert.Equal(0, rmsle.Last.Value);
|
||||
Assert.False(rmsle.IsHot);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void IsNew_False_UpdatesCurrentBar()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
rmsle.Update(100.0, 90.0);
|
||||
double valueBefore = rmsle.Last.Value;
|
||||
|
||||
rmsle.Update(100.0, 95.0, isNew: false);
|
||||
double valueAfter = rmsle.Last.Value;
|
||||
|
||||
Assert.NotEqual(valueBefore, valueAfter);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void IterativeCorrections_RestoreToOriginalState()
|
||||
{
|
||||
var rmsle = new Rmsle(5);
|
||||
var gbm = new GBM(startPrice: 100.0, mu: 0.02, sigma: 0.1);
|
||||
|
||||
for (int i = 0; i < 10; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: true);
|
||||
rmsle.Update(bar.Close, bar.Close * 0.95, isNew: true);
|
||||
}
|
||||
|
||||
double stateAfterTen = rmsle.Last.Value;
|
||||
|
||||
var lastBar = gbm.Next(isNew: false);
|
||||
double lastActual = lastBar.Close;
|
||||
double lastPredicted = lastBar.Close * 0.95;
|
||||
|
||||
for (int i = 0; i < 5; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: false);
|
||||
rmsle.Update(bar.Close, bar.Close * 0.9, isNew: false);
|
||||
}
|
||||
|
||||
rmsle.Update(lastActual, lastPredicted, isNew: false);
|
||||
|
||||
Assert.Equal(stateAfterTen, rmsle.Last.Value, 1e-6);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void BatchCalc_MatchesIterativeCalc()
|
||||
{
|
||||
var rmsleIterative = new Rmsle(10);
|
||||
var gbm = new GBM(startPrice: 100.0, mu: 0.02, sigma: 0.1, seed: 42);
|
||||
|
||||
var actualSeries = new TSeries();
|
||||
var predictedSeries = new TSeries();
|
||||
|
||||
for (int i = 0; i < 100; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: true);
|
||||
actualSeries.Add(bar.Time, bar.Close);
|
||||
predictedSeries.Add(bar.Time, bar.Close * 0.95);
|
||||
}
|
||||
|
||||
var iterativeResults = new List<double>();
|
||||
for (int i = 0; i < actualSeries.Count; i++)
|
||||
{
|
||||
iterativeResults.Add(rmsleIterative.Update(actualSeries[i], predictedSeries[i]).Value);
|
||||
}
|
||||
|
||||
var batchResults = Rmsle.Calculate(actualSeries, predictedSeries, 10);
|
||||
|
||||
Assert.Equal(iterativeResults.Count, batchResults.Count);
|
||||
for (int i = 0; i < iterativeResults.Count; i++)
|
||||
{
|
||||
Assert.Equal(iterativeResults[i], batchResults[i].Value, Precision);
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void SpanBatch_ValidatesInput()
|
||||
{
|
||||
double[] actual = [100, 100, 100];
|
||||
double[] predicted = [90, 95, 100];
|
||||
double[] output = new double[3];
|
||||
double[] wrongSizeOutput = new double[2];
|
||||
|
||||
Assert.Throws<ArgumentException>(() =>
|
||||
Rmsle.Batch(actual.AsSpan(), predicted.AsSpan(), wrongSizeOutput.AsSpan(), 3));
|
||||
|
||||
Assert.Throws<ArgumentException>(() =>
|
||||
Rmsle.Batch(actual.AsSpan(), predicted.AsSpan(), output.AsSpan(), 0));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void SpanBatch_MatchesTSeriesBatch()
|
||||
{
|
||||
var gbm = new GBM(startPrice: 100.0, mu: 0.02, sigma: 0.1, seed: 42);
|
||||
|
||||
var actualSeries = new TSeries();
|
||||
var predictedSeries = new TSeries();
|
||||
double[] actualArr = new double[100];
|
||||
double[] predictedArr = new double[100];
|
||||
double[] output = new double[100];
|
||||
|
||||
for (int i = 0; i < 100; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: true);
|
||||
actualArr[i] = bar.Close;
|
||||
predictedArr[i] = bar.Close * 0.95;
|
||||
actualSeries.Add(bar.Time, bar.Close);
|
||||
predictedSeries.Add(bar.Time, bar.Close * 0.95);
|
||||
}
|
||||
|
||||
var tseriesResult = Rmsle.Calculate(actualSeries, predictedSeries, 10);
|
||||
Rmsle.Batch(actualArr.AsSpan(), predictedArr.AsSpan(), output.AsSpan(), 10);
|
||||
|
||||
for (int i = 0; i < 100; i++)
|
||||
{
|
||||
Assert.Equal(tseriesResult[i].Value, output[i], Precision);
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void SpanBatch_HandlesNaN()
|
||||
{
|
||||
double[] actual = [100, 100, double.NaN, 100, 100];
|
||||
double[] predicted = [90, 95, 92, double.NaN, 95];
|
||||
double[] output = new double[5];
|
||||
|
||||
Rmsle.Batch(actual.AsSpan(), predicted.AsSpan(), output.AsSpan(), 3);
|
||||
|
||||
foreach (var val in output)
|
||||
{
|
||||
Assert.True(double.IsFinite(val), $"Expected finite value but got {val}");
|
||||
}
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Calculate_MismatchedLengths_ThrowsException()
|
||||
{
|
||||
var actual = new TSeries();
|
||||
var predicted = new TSeries();
|
||||
|
||||
actual.Add(DateTime.UtcNow.Ticks, 100);
|
||||
actual.Add(DateTime.UtcNow.Ticks + 1, 100);
|
||||
predicted.Add(DateTime.UtcNow.Ticks, 90);
|
||||
|
||||
Assert.Throws<ArgumentException>(() => Rmsle.Calculate(actual, predicted, 5));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Name_IsSetCorrectly()
|
||||
{
|
||||
var rmsle = new Rmsle(14);
|
||||
Assert.Equal("Rmsle(14)", rmsle.Name);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void WarmupPeriod_IsSetCorrectly()
|
||||
{
|
||||
var rmsle = new Rmsle(20);
|
||||
Assert.Equal(20, rmsle.WarmupPeriod);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void CompareWithRmse_DifferentScaling()
|
||||
{
|
||||
var rmsle = new Rmsle(1);
|
||||
var rmse = new Rmse(1);
|
||||
|
||||
// Large values: actual=1000000, predicted=500000
|
||||
var rmsleResult = rmsle.Update(1000000.0, 500000.0);
|
||||
var rmseResult = rmse.Update(1000000.0, 500000.0);
|
||||
|
||||
// RMSE = 500000
|
||||
// RMSLE = |log(1000001) - log(500001)| ≈ 0.69
|
||||
Assert.True(rmsleResult.Value < 1.0);
|
||||
Assert.True(rmseResult.Value > 100000);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void SlidingWindow_Works()
|
||||
{
|
||||
var rmsle = new Rmsle(3);
|
||||
|
||||
// actual=0, predicted=0 -> RMSLE = 0
|
||||
rmsle.Update(0.0, 0.0);
|
||||
Assert.Equal(0.0, rmsle.Last.Value, Precision);
|
||||
|
||||
// actual=e-1≈1.718, predicted=0 -> |log(e) - log(1)| = 1
|
||||
rmsle.Update(Math.E - 1, 0.0);
|
||||
// MSLE average: (0 + 1) / 2 = 0.5, RMSLE = sqrt(0.5)
|
||||
Assert.Equal(Math.Sqrt(0.5), rmsle.Last.Value, Precision);
|
||||
|
||||
// actual=0, predicted=0 -> RMSLE = 0
|
||||
rmsle.Update(0.0, 0.0);
|
||||
// MSLE average: (0 + 1 + 0) / 3 = 1/3, RMSLE = sqrt(1/3)
|
||||
Assert.Equal(Math.Sqrt(1.0 / 3.0), rmsle.Last.Value, Precision);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void AlwaysNonNegative()
|
||||
{
|
||||
var rmsle = new Rmsle(10);
|
||||
var gbm = new GBM(startPrice: 100.0, mu: 0.02, sigma: 0.3, seed: 42);
|
||||
|
||||
for (int i = 0; i < 100; i++)
|
||||
{
|
||||
var bar = gbm.Next(isNew: true);
|
||||
var result = rmsle.Update(bar.Close, bar.Close * (0.8 + 0.4 * (i % 2)));
|
||||
Assert.True(result.Value >= 0, $"RMSLE should always be non-negative, got {result.Value}");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,236 @@
|
||||
using System.Runtime.CompilerServices;
|
||||
using System.Runtime.InteropServices;
|
||||
|
||||
namespace QuanTAlib;
|
||||
|
||||
/// <summary>
|
||||
/// RMSLE: Root Mean Squared Logarithmic Error
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// RMSLE is the square root of MSLE, providing an error metric in log-scale units.
|
||||
/// Like MSLE, it's robust to outliers and suited for data spanning multiple orders of magnitude.
|
||||
///
|
||||
/// Formula:
|
||||
/// RMSLE = √[(1/n) * Σ(log(1 + actual) - log(1 + predicted))²]
|
||||
///
|
||||
/// Key properties:
|
||||
/// - Same units as log-transformed data (more interpretable than MSLE)
|
||||
/// - Robust to outliers (logarithmic compression)
|
||||
/// - Requires non-negative values
|
||||
/// - Scale-independent for multiplicative relationships
|
||||
/// </remarks>
|
||||
[SkipLocalsInit]
|
||||
public sealed class Rmsle : AbstractBase
|
||||
{
|
||||
private readonly RingBuffer _buffer;
|
||||
|
||||
[StructLayout(LayoutKind.Auto)]
|
||||
private record struct State(double Sum, double LastValidActual, double LastValidPredicted, int TickCount);
|
||||
private State _state;
|
||||
private State _p_state;
|
||||
|
||||
private const int ResyncInterval = 1000;
|
||||
|
||||
public Rmsle(int period)
|
||||
{
|
||||
if (period <= 0)
|
||||
throw new ArgumentException("Period must be greater than 0", nameof(period));
|
||||
|
||||
_buffer = new RingBuffer(period);
|
||||
Name = $"Rmsle({period})";
|
||||
WarmupPeriod = period;
|
||||
}
|
||||
|
||||
public override bool IsHot => _buffer.IsFull;
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public TValue Update(TValue actual, TValue predicted, bool isNew = true)
|
||||
{
|
||||
double actualVal = actual.Value;
|
||||
double predictedVal = predicted.Value;
|
||||
|
||||
if (!double.IsFinite(actualVal) || actualVal < 0)
|
||||
actualVal = double.IsFinite(_state.LastValidActual) && _state.LastValidActual >= 0
|
||||
? _state.LastValidActual : 0.0;
|
||||
else
|
||||
_state.LastValidActual = actualVal;
|
||||
|
||||
if (!double.IsFinite(predictedVal) || predictedVal < 0)
|
||||
predictedVal = double.IsFinite(_state.LastValidPredicted) && _state.LastValidPredicted >= 0
|
||||
? _state.LastValidPredicted : 0.0;
|
||||
else
|
||||
_state.LastValidPredicted = predictedVal;
|
||||
|
||||
// Calculate squared log error (same as MSLE)
|
||||
double logActual = Math.Log(1.0 + actualVal);
|
||||
double logPredicted = Math.Log(1.0 + predictedVal);
|
||||
double logError = logActual - logPredicted;
|
||||
double squaredLogError = logError * logError;
|
||||
|
||||
if (isNew)
|
||||
{
|
||||
_p_state = _state;
|
||||
|
||||
double removedValue = _buffer.Count == _buffer.Capacity ? _buffer.Oldest : 0.0;
|
||||
_state.Sum = _state.Sum - removedValue + squaredLogError;
|
||||
_buffer.Add(squaredLogError);
|
||||
|
||||
_state.TickCount++;
|
||||
if (_buffer.IsFull && _state.TickCount >= ResyncInterval)
|
||||
{
|
||||
_state.TickCount = 0;
|
||||
_state.Sum = _buffer.RecalculateSum();
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
_state = _p_state;
|
||||
|
||||
double removedValue = _buffer.Count == _buffer.Capacity ? _buffer.Oldest : 0.0;
|
||||
_state.Sum = _state.Sum - removedValue + squaredLogError;
|
||||
_buffer.UpdateNewest(squaredLogError);
|
||||
_state.Sum = _buffer.RecalculateSum();
|
||||
}
|
||||
|
||||
// RMSLE = sqrt(MSLE)
|
||||
double msle = _buffer.Count > 0 ? _state.Sum / _buffer.Count : squaredLogError;
|
||||
double result = Math.Sqrt(msle);
|
||||
|
||||
Last = new TValue(actual.Time, result);
|
||||
PubEvent(Last, isNew);
|
||||
return Last;
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public TValue Update(double actual, double predicted, bool isNew = true)
|
||||
{
|
||||
return Update(new TValue(DateTime.UtcNow, actual), new TValue(DateTime.UtcNow, predicted), isNew);
|
||||
}
|
||||
|
||||
public override TValue Update(TValue input, bool isNew = true)
|
||||
{
|
||||
throw new NotSupportedException("RMSLE requires two inputs. Use Update(actual, predicted).");
|
||||
}
|
||||
|
||||
public override TSeries Update(TSeries source)
|
||||
{
|
||||
throw new NotSupportedException("RMSLE requires two inputs. Use Calculate(actualSeries, predictedSeries, period).");
|
||||
}
|
||||
|
||||
public override void Prime(ReadOnlySpan<double> source, TimeSpan? step = null)
|
||||
{
|
||||
throw new NotSupportedException("RMSLE requires two inputs.");
|
||||
}
|
||||
|
||||
public override void Reset()
|
||||
{
|
||||
_buffer.Clear();
|
||||
_state = default;
|
||||
_p_state = default;
|
||||
Last = default;
|
||||
}
|
||||
|
||||
public static TSeries Calculate(TSeries actual, TSeries predicted, int period)
|
||||
{
|
||||
if (actual.Count != predicted.Count)
|
||||
throw new ArgumentException("Actual and predicted series must have the same length", nameof(predicted));
|
||||
|
||||
int len = actual.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(actual.Values, predicted.Values, vSpan, period);
|
||||
actual.Times.CopyTo(tSpan);
|
||||
|
||||
return new TSeries(t, v);
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public static void Batch(ReadOnlySpan<double> actual, ReadOnlySpan<double> predicted, Span<double> output, int period)
|
||||
{
|
||||
if (actual.Length != predicted.Length || actual.Length != output.Length)
|
||||
throw new ArgumentException("All spans must have the same length", nameof(output));
|
||||
if (period <= 0)
|
||||
throw new ArgumentException("Period must be greater than 0", nameof(period));
|
||||
|
||||
int len = actual.Length;
|
||||
if (len == 0) return;
|
||||
|
||||
const int StackAllocThreshold = 256;
|
||||
Span<double> buffer = period <= StackAllocThreshold
|
||||
? stackalloc double[period]
|
||||
: new double[period];
|
||||
|
||||
double sum = 0;
|
||||
double lastValidActual = 0;
|
||||
double lastValidPredicted = 0;
|
||||
|
||||
for (int k = 0; k < len; k++)
|
||||
{
|
||||
if (double.IsFinite(actual[k]) && actual[k] >= 0) { lastValidActual = actual[k]; break; }
|
||||
}
|
||||
for (int k = 0; k < len; k++)
|
||||
{
|
||||
if (double.IsFinite(predicted[k]) && predicted[k] >= 0) { lastValidPredicted = predicted[k]; break; }
|
||||
}
|
||||
|
||||
int bufferIndex = 0;
|
||||
int i = 0;
|
||||
|
||||
int warmupEnd = Math.Min(period, len);
|
||||
for (; i < warmupEnd; i++)
|
||||
{
|
||||
double act = actual[i];
|
||||
double pred = predicted[i];
|
||||
|
||||
if (double.IsFinite(act) && act >= 0) lastValidActual = act; else act = lastValidActual;
|
||||
if (double.IsFinite(pred) && pred >= 0) lastValidPredicted = pred; else pred = lastValidPredicted;
|
||||
|
||||
double logActual = Math.Log(1.0 + act);
|
||||
double logPredicted = Math.Log(1.0 + pred);
|
||||
double logError = logActual - logPredicted;
|
||||
double squaredLogError = logError * logError;
|
||||
|
||||
sum += squaredLogError;
|
||||
buffer[i] = squaredLogError;
|
||||
output[i] = Math.Sqrt(sum / (i + 1));
|
||||
}
|
||||
|
||||
int tickCount = 0;
|
||||
for (; i < len; i++)
|
||||
{
|
||||
double act = actual[i];
|
||||
double pred = predicted[i];
|
||||
|
||||
if (double.IsFinite(act) && act >= 0) lastValidActual = act; else act = lastValidActual;
|
||||
if (double.IsFinite(pred) && pred >= 0) lastValidPredicted = pred; else pred = lastValidPredicted;
|
||||
|
||||
double logActual = Math.Log(1.0 + act);
|
||||
double logPredicted = Math.Log(1.0 + pred);
|
||||
double logError = logActual - logPredicted;
|
||||
double squaredLogError = logError * logError;
|
||||
|
||||
sum = sum - buffer[bufferIndex] + squaredLogError;
|
||||
buffer[bufferIndex] = squaredLogError;
|
||||
|
||||
bufferIndex++;
|
||||
if (bufferIndex >= period) bufferIndex = 0;
|
||||
|
||||
output[i] = Math.Sqrt(sum / period);
|
||||
|
||||
tickCount++;
|
||||
if (tickCount >= ResyncInterval)
|
||||
{
|
||||
tickCount = 0;
|
||||
double recalcSum = 0;
|
||||
for (int k = 0; k < period; k++) recalcSum += buffer[k];
|
||||
sum = recalcSum;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,190 @@
|
||||
# RMSLE: Root Mean Squared Logarithmic Error
|
||||
|
||||
> "RMSLE: because sometimes your errors need to be measured in decades, not dollars."
|
||||
|
||||
Root Mean Squared Logarithmic Error is the square root of MSLE, providing an error metric in log-scale units. This makes RMSLE more interpretable than MSLE while retaining all its benefits for data spanning multiple orders of magnitude.
|
||||
|
||||
## Architecture & Physics
|
||||
|
||||
RMSLE computes the root mean of squared log differences:
|
||||
|
||||
$$\text{RMSLE} = \sqrt{\frac{1}{n} \sum_{i=1}^{n} \left(\log(1 + \text{actual}_i) - \log(1 + \text{predicted}_i)\right)^2}$$
|
||||
|
||||
The relationship to MSLE is straightforward:
|
||||
|
||||
$$\text{RMSLE} = \sqrt{\text{MSLE}}$$
|
||||
|
||||
### Interpretability
|
||||
|
||||
RMSLE values correspond directly to log-scale error:
|
||||
|
||||
- RMSLE = 0.1 → approximately 10% ratio error
|
||||
- RMSLE = 0.69 → approximately 100% ratio error (2:1 or 1:2 ratio)
|
||||
- RMSLE = 1.0 → approximately 170% ratio error (~2.7:1 ratio)
|
||||
|
||||
## Mathematical Foundation
|
||||
|
||||
### 1. Log Transform
|
||||
|
||||
$$\tilde{x} = \log(1 + x)$$
|
||||
|
||||
### 2. Root Mean Square in Log Space
|
||||
|
||||
$$\text{RMSLE} = \sqrt{\frac{1}{n} \sum_{i=t-n+1}^{t} \left(\tilde{\text{actual}}_i - \tilde{\text{predicted}}_i\right)^2}$$
|
||||
|
||||
### 3. Approximation for Small Errors
|
||||
|
||||
For small relative errors ($\epsilon$):
|
||||
|
||||
$$\text{RMSLE} \approx |\log(1 + \epsilon)| \approx |\epsilon|$$
|
||||
|
||||
## Performance Profile
|
||||
|
||||
| Metric | Score | Notes |
|
||||
| :--- | :--- | :--- |
|
||||
| **Throughput** | 28 ns/bar | O(1) with sqrt overhead |
|
||||
| **Allocations** | 0 | Zero-allocation hot path |
|
||||
| **Complexity** | O(1) | Constant per update |
|
||||
| **Outlier Robustness** | 9/10 | Log compression |
|
||||
| **Interpretability** | 7/10 | Better than MSLE |
|
||||
| **Scale Independence** | 10/10 | Ratio-based |
|
||||
| **Zero Handling** | 10/10 | Uses 1+x transform |
|
||||
|
||||
## Usage
|
||||
|
||||
```csharp
|
||||
// Streaming mode - track prediction quality
|
||||
var rmsle = new Rmsle(20);
|
||||
|
||||
// Revenue predictions across different scales
|
||||
rmsle.Update(actual: 1000.0, predicted: 950.0); // Small business
|
||||
rmsle.Update(actual: 1000000.0, predicted: 950000.0); // Enterprise
|
||||
|
||||
double logError = rmsle.Last.Value;
|
||||
Console.WriteLine($"RMSLE: {logError:F3}"); // Consistent ~0.05 for 5% error
|
||||
|
||||
// Batch mode - backtest analysis
|
||||
var actual = new TSeries { 100, 1000, 10000, 100000 };
|
||||
var predicted = new TSeries { 95, 950, 9500, 95000 };
|
||||
var results = Rmsle.Calculate(actual, predicted, period: 3);
|
||||
|
||||
// Span mode - zero-allocation bulk processing
|
||||
Span<double> output = stackalloc double[1000];
|
||||
Rmsle.Batch(actualSpan, predictedSpan, output, period: 20);
|
||||
```
|
||||
|
||||
## Interpretation Guide
|
||||
|
||||
| RMSLE Value | Interpretation | Typical Application |
|
||||
| :--- | :--- | :--- |
|
||||
| **< 0.1** | Excellent | High-precision forecasting |
|
||||
| **0.1 - 0.3** | Good | Business forecasting |
|
||||
| **0.3 - 0.5** | Moderate | General ML models |
|
||||
| **0.5 - 1.0** | Poor | Needs improvement |
|
||||
| **> 1.0** | Very poor | Model redesign needed |
|
||||
|
||||
### Converting RMSLE to Ratio Error
|
||||
|
||||
$$\text{Typical Ratio} \approx e^{\text{RMSLE}}$$
|
||||
|
||||
| RMSLE | Ratio Factor | Meaning |
|
||||
| :--- | :--- | :--- |
|
||||
| 0.1 | 1.105 | Predictions typically within ±10.5% |
|
||||
| 0.2 | 1.221 | Predictions typically within ±22% |
|
||||
| 0.5 | 1.649 | Predictions typically within ±65% |
|
||||
| 0.693 | 2.0 | Predictions off by factor of 2 |
|
||||
| 1.0 | 2.718 | Predictions off by factor of e |
|
||||
|
||||
## Comparison: RMSE vs RMSLE
|
||||
|
||||
```csharp
|
||||
var rmse = new Rmse(1);
|
||||
var rmsle = new Rmsle(1);
|
||||
|
||||
// Small scale
|
||||
rmse.Update(100.0, 50.0); // RMSE = 50
|
||||
rmsle.Update(100.0, 50.0); // RMSLE ≈ 0.69
|
||||
|
||||
// Large scale (same ratio)
|
||||
rmse.Update(1000000.0, 500000.0); // RMSE = 500,000
|
||||
rmsle.Update(1000000.0, 500000.0); // RMSLE ≈ 0.69
|
||||
|
||||
// RMSE varies wildly; RMSLE is consistent for same ratio
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. E-Commerce Sales Forecasting
|
||||
|
||||
Product sales vary from single units to thousands:
|
||||
|
||||
```csharp
|
||||
// Product A: sells 5 units, predicted 4
|
||||
// Product B: sells 5000 units, predicted 4000
|
||||
// Same 20% under-prediction, similar RMSLE
|
||||
```
|
||||
|
||||
### 2. Financial Modeling
|
||||
|
||||
Stock prices, market caps, and volumes span many magnitudes:
|
||||
|
||||
```csharp
|
||||
// Penny stock: $0.10 → $0.12 (20% move)
|
||||
// Blue chip: $100 → $120 (20% move)
|
||||
// RMSLE treats these equivalently
|
||||
```
|
||||
|
||||
### 3. Scientific Measurements
|
||||
|
||||
Population counts, concentrations, or any log-normal data:
|
||||
|
||||
```csharp
|
||||
// Bacteria count: 1,000 → 1,200
|
||||
// Bacteria count: 1,000,000,000 → 1,200,000,000
|
||||
// Same relative accuracy
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Non-Negative Requirement
|
||||
|
||||
RMSLE requires both actual and predicted values to be non-negative:
|
||||
|
||||
```csharp
|
||||
// Invalid inputs are replaced with last valid value or 0
|
||||
rmsle.Update(-100.0, 50.0); // Uses last valid actual
|
||||
```
|
||||
|
||||
### 2. Unit Interpretation
|
||||
|
||||
RMSLE is in "log units," not the original units:
|
||||
|
||||
```csharp
|
||||
// RMSLE = 0.5 does NOT mean $0.50 error
|
||||
// It means predictions are typically off by ~65% ratio
|
||||
```
|
||||
|
||||
### 3. Near-Zero Sensitivity
|
||||
|
||||
Small absolute values near zero can produce large RMSLE:
|
||||
|
||||
```csharp
|
||||
// actual=1, predicted=10: RMSLE = |log(2) - log(11)| ≈ 1.7
|
||||
// actual=1000, predicted=10000: RMSLE = |log(1001) - log(10001)| ≈ 2.3
|
||||
// Not exactly proportional due to 1+x offset
|
||||
```
|
||||
|
||||
## Relationship to Other Metrics
|
||||
|
||||
| Metric | Relationship |
|
||||
| :--- | :--- |
|
||||
| **MSLE** | RMSLE = √MSLE |
|
||||
| **RMSE** | Different scale sensitivity |
|
||||
| **MAPE** | Both percentage-like, but RMSLE handles zeros |
|
||||
| **MAE** | RMSLE is log-transformed, squared, then rooted |
|
||||
|
||||
## See Also
|
||||
|
||||
- [MSLE](../msle/Msle.md) - Squared version without root
|
||||
- [RMSE](../rmse/Rmse.md) - Linear-scale root mean squared error
|
||||
- [MAPE](../mape/Mape.md) - Percentage error without log transform
|
||||
Reference in New Issue
Block a user