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.
2026-08-23 04:58:08 +00:00 · 2025-12-29 20:58:21 -08:00
parent 4dbb093892
commit bf611d319f
50 changed files with 11327 additions and 21 deletions
@@ -0,0 +1,359 @@
+namespace QuanTAlib.Tests;
+
+public class MaeTests
+{
+    [Fact]
+    public void Constructor_ValidatesInput()
+    {
+        Assert.Throws<ArgumentException>(() => new Mae(0));
+        Assert.Throws<ArgumentException>(() => new Mae(-1));
+
+        var mae = new Mae(10);
+        Assert.NotNull(mae);
+    }
+
+    [Fact]
+    public void Properties_Accessible()
+    {
+        var mae = new Mae(10);
+
+        Assert.Equal(0, mae.Last.Value);
+        Assert.False(mae.IsHot);
+        Assert.Contains("Mae", mae.Name, StringComparison.Ordinal);
+
+        mae.Update(100, 105);
+        Assert.NotEqual(0, mae.Last.Time);
+    }
+
+    [Fact]
+    public void IsHot_BecomesTrueWhenBufferFull()
+    {
+        int period = 5;
+        var mae = new Mae(period);
+
+        for (int i = 0; i < period - 1; i++)
+        {
+            Assert.False(mae.IsHot, $"IsHot should be false at index {i}");
+            mae.Update(i * 10, i * 10 + 5);
+        }
+
+        mae.Update((period - 1) * 10, (period - 1) * 10 + 5);
+        Assert.True(mae.IsHot, "IsHot should be true after period updates");
+    }
+
+    [Fact]
+    public void Mae_CalculatesCorrectly()
+    {
+        var mae = new Mae(3);
+
+        // |10 - 15| = 5
+        var res1 = mae.Update(10, 15);
+        Assert.Equal(5.0, res1.Value, 10);
+
+        // |20 - 30| = 10, Mean = (5 + 10) / 2 = 7.5
+        var res2 = mae.Update(20, 30);
+        Assert.Equal(7.5, res2.Value, 10);
+
+        // |30 - 25| = 5, Mean = (5 + 10 + 5) / 3 = 6.666...
+        var res3 = mae.Update(30, 25);
+        Assert.Equal(20.0 / 3.0, res3.Value, 10);
+
+        // |40 - 35| = 5, Window slides: (10 + 5 + 5) / 3 = 6.666...
+        var res4 = mae.Update(40, 35);
+        Assert.Equal(20.0 / 3.0, res4.Value, 10);
+    }
+
+    [Fact]
+    public void Mae_PerfectPrediction_ReturnsZero()
+    {
+        var mae = new Mae(5);
+
+        for (int i = 0; i < 10; i++)
+        {
+            mae.Update(i * 10, i * 10); // Perfect prediction
+        }
+
+        Assert.Equal(0.0, mae.Last.Value, 10);
+    }
+
+    [Fact]
+    public void Mae_ConstantError_ReturnsConstant()
+    {
+        var mae = new Mae(5);
+
+        for (int i = 0; i < 10; i++)
+        {
+            mae.Update(100, 110); // Constant error of 10
+        }
+
+        Assert.Equal(10.0, mae.Last.Value, 10);
+    }
+
+    [Fact]
+    public void Mae_NegativeError_TakesAbsoluteValue()
+    {
+        var mae = new Mae(3);
+
+        // Error = |15 - 10| = 5 (predicted > actual)
+        mae.Update(10, 15);
+        // Error = |20 - 30| = 10 (predicted > actual)
+        mae.Update(20, 30);
+        // Error = |50 - 25| = 25 (predicted < actual)
+        mae.Update(50, 25);
+
+        // Mean = (5 + 10 + 25) / 3 = 40 / 3
+        Assert.Equal(40.0 / 3.0, mae.Last.Value, 10);
+    }
+
+    [Fact]
+    public void Calc_IsNew_AcceptsParameter()
+    {
+        var mae = new Mae(10);
+
+        mae.Update(100, 110, isNew: true);
+        double value1 = mae.Last.Value;
+
+        mae.Update(100, 120, isNew: true);
+        double value2 = mae.Last.Value;
+
+        Assert.NotEqual(value1, value2);
+    }
+
+    [Fact]
+    public void Calc_IsNew_False_UpdatesValue()
+    {
+        var mae = new Mae(10);
+
+        mae.Update(100, 110);
+        mae.Update(100, 120, isNew: true);
+        double beforeUpdate = mae.Last.Value;
+
+        mae.Update(100, 130, isNew: false);
+        double afterUpdate = mae.Last.Value;
+
+        Assert.NotEqual(beforeUpdate, afterUpdate);
+    }
+
+    [Fact]
+    public void IterativeCorrections_RestoreToOriginalState()
+    {
+        var mae = new Mae(5);
+
+        double tenthActual = 0;
+        double tenthPredicted = 0;
+
+        // Feed 10 updates
+        for (int i = 0; i < 10; i++)
+        {
+            tenthActual = i * 10;
+            tenthPredicted = i * 10 + 5;
+            mae.Update(tenthActual, tenthPredicted);
+        }
+
+        double stateAfterTen = mae.Last.Value;
+
+        // Apply 5 corrections with isNew=false
+        for (int i = 0; i < 5; i++)
+        {
+            mae.Update(100 + i, 200 + i, isNew: false);
+        }
+
+        // Restore to original values
+        mae.Update(tenthActual, tenthPredicted, isNew: false);
+
+        Assert.Equal(stateAfterTen, mae.Last.Value, 10);
+    }
+
+    [Fact]
+    public void Reset_ClearsState()
+    {
+        var mae = new Mae(5);
+
+        for (int i = 0; i < 10; i++)
+        {
+            mae.Update(i * 10, i * 10 + 5);
+        }
+
+        Assert.True(mae.IsHot);
+
+        mae.Reset();
+
+        Assert.False(mae.IsHot);
+        Assert.Equal(0, mae.Last.Value);
+    }
+
+    [Fact]
+    public void NaN_Input_UsesLastValidValue()
+    {
+        var mae = new Mae(5);
+
+        mae.Update(100, 110);
+        mae.Update(110, 120);
+        mae.Update(120, 130);
+
+        var result = mae.Update(double.NaN, double.NaN);
+
+        Assert.True(double.IsFinite(result.Value));
+    }
+
+    [Fact]
+    public void Infinity_Input_UsesLastValidValue()
+    {
+        var mae = new Mae(5);
+
+        mae.Update(100, 110);
+        mae.Update(110, 120);
+
+        var result = mae.Update(double.PositiveInfinity, double.NegativeInfinity);
+
+        Assert.True(double.IsFinite(result.Value));
+    }
+
+    [Fact]
+    public void MultipleNaN_ContinuesWithLastValid()
+    {
+        var mae = new Mae(5);
+
+        mae.Update(100, 110);
+        mae.Update(110, 120);
+        mae.Update(120, 130);
+
+        var r1 = mae.Update(double.NaN, double.NaN);
+        var r2 = mae.Update(double.NaN, double.NaN);
+        var r3 = mae.Update(double.NaN, double.NaN);
+
+        Assert.True(double.IsFinite(r1.Value));
+        Assert.True(double.IsFinite(r2.Value));
+        Assert.True(double.IsFinite(r3.Value));
+    }
+
+    [Fact]
+    public void Mae_Throws_On_Single_Input()
+    {
+        var mae = new Mae(10);
+        Assert.Throws<NotSupportedException>(() => mae.Update(new TValue(DateTime.UtcNow, 1)));
+        Assert.Throws<NotSupportedException>(() => mae.Update(new TSeries()));
+        Assert.Throws<NotSupportedException>(() => mae.Prime(new double[] { 1, 2, 3 }));
+    }
+
+    [Fact]
+    public void BatchSpan_MatchesStreaming()
+    {
+        int period = 5;
+        int count = 100;
+        var gbm = new GBM(startPrice: 100, mu: 0.05, sigma: 0.2, seed: 123);
+
+        double[] actual = new double[count];
+        double[] predicted = new double[count];
+        for (int i = 0; i < count; i++)
+        {
+            var bar = gbm.Next();
+            actual[i] = bar.Close;
+            predicted[i] = bar.Close * 1.05 + 2; // Offset prediction
+        }
+
+        // Streaming
+        var mae = new Mae(period);
+        var streamingResults = new double[count];
+        for (int i = 0; i < count; i++)
+        {
+            streamingResults[i] = mae.Update(actual[i], predicted[i]).Value;
+        }
+
+        // Batch
+        double[] batchResults = new double[count];
+        Mae.Batch(actual, predicted, batchResults, period);
+
+        // Compare
+        for (int i = 0; i < count; i++)
+        {
+            Assert.Equal(streamingResults[i], batchResults[i], 9);
+        }
+    }
+
+    [Fact]
+    public void BatchSpan_ValidatesInput()
+    {
+        double[] actual = [1, 2, 3, 4, 5];
+        double[] predicted = [1, 2, 3, 4, 5];
+        double[] output = new double[5];
+        double[] wrongSizeOutput = new double[3];
+        double[] wrongSizePredicted = new double[3];
+
+        // Period must be > 0
+        Assert.Throws<ArgumentException>(() =>
+            Mae.Batch(actual.AsSpan(), predicted.AsSpan(), output.AsSpan(), 0));
+        Assert.Throws<ArgumentException>(() =>
+            Mae.Batch(actual.AsSpan(), predicted.AsSpan(), output.AsSpan(), -1));
+
+        // Output must be same length as source
+        Assert.Throws<ArgumentException>(() =>
+            Mae.Batch(actual.AsSpan(), predicted.AsSpan(), wrongSizeOutput.AsSpan(), 3));
+
+        // Predicted must be same length as actual
+        Assert.Throws<ArgumentException>(() =>
+            Mae.Batch(actual.AsSpan(), wrongSizePredicted.AsSpan(), output.AsSpan(), 3));
+    }
+
+    [Fact]
+    public void Calculate_Works()
+    {
+        var actual = new TSeries();
+        var predicted = new TSeries();
+        var now = DateTime.UtcNow;
+
+        for (int i = 0; i < 10; i++)
+        {
+            actual.Add(now.AddMinutes(i), i * 10);
+            predicted.Add(now.AddMinutes(i), i * 10 + 5);
+        }
+
+        var results = Mae.Calculate(actual, predicted, 3);
+
+        Assert.Equal(10, results.Count);
+        // All errors are 5, so MAE should be 5
+        Assert.Equal(5.0, results.Last.Value, 10);
+    }
+
+    [Fact]
+    public void Calculate_ValidatesMismatchedLengths()
+    {
+        var actual = new TSeries();
+        var predicted = new TSeries();
+
+        for (int i = 0; i < 10; i++) actual.Add(DateTime.UtcNow, i);
+        for (int i = 0; i < 5; i++) predicted.Add(DateTime.UtcNow, i);
+
+        Assert.Throws<ArgumentException>(() => Mae.Calculate(actual, predicted, 3));
+    }
+
+    [Fact]
+    public void BatchSpan_HandlesNaN()
+    {
+        double[] actual = [100, 110, double.NaN, 130, 140];
+        double[] predicted = [105, 115, 125, double.NaN, 145];
+        double[] output = new double[5];
+
+        Mae.Batch(actual, predicted, output, 3);
+
+        foreach (var val in output)
+        {
+            Assert.True(double.IsFinite(val), $"Expected finite value but got {val}");
+        }
+    }
+
+    [Fact]
+    public void Mae_Resync_Works()
+    {
+        var mae = new Mae(5);
+
+        // Force many updates to trigger resync (ResyncInterval = 1000)
+        for (int i = 0; i < 1100; i++)
+        {
+            mae.Update(i, i + 10); // Constant error of 10
+        }
+
+        // After resync, result should still be correct
+        Assert.Equal(10.0, mae.Last.Value, 10);
+    }
+}
@@ -0,0 +1,287 @@
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+namespace QuanTAlib;
+
+/// <summary>
+/// MAE: Mean Absolute Error
+/// </summary>
+/// <remarks>
+/// MAE measures the average magnitude of errors between paired observations,
+/// without considering their direction. It is the mean of the absolute differences
+/// between actual and predicted values.
+///
+/// Formula:
+/// MAE = (1/n) * Σ|actual - predicted|
+///
+/// Uses a RingBuffer for O(1) streaming updates with running sum.
+///
+/// Key properties:
+/// - Always non-negative (MAE ≥ 0)
+/// - Same units as the original data
+/// - Less sensitive to outliers than MSE/RMSE
+/// - MAE = 0 indicates perfect prediction
+/// </remarks>
+[SkipLocalsInit]
+public sealed class Mae : 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;
+
+    /// <summary>
+    /// Creates MAE with specified period.
+    /// </summary>
+    /// <param name="period">Number of values to average (must be > 0)</param>
+    public Mae(int period)
+    {
+        if (period <= 0)
+            throw new ArgumentException("Period must be greater than 0", nameof(period));
+
+        _buffer = new RingBuffer(period);
+        Name = $"Mae({period})";
+        WarmupPeriod = period;
+    }
+
+    /// <summary>
+    /// True if the MAE has enough data to produce valid results.
+    /// </summary>
+    public override bool IsHot => _buffer.IsFull;
+
+    /// <summary>
+    /// Updates the MAE with new actual and predicted values.
+    /// </summary>
+    /// <param name="actual">Actual value (source1)</param>
+    /// <param name="predicted">Predicted value (source2)</param>
+    /// <param name="isNew">Whether this is a new bar.</param>
+    /// <returns>The calculated MAE value.</returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public TValue Update(TValue actual, TValue predicted, bool isNew = true)
+    {
+        double actualVal = actual.Value;
+        double predictedVal = predicted.Value;
+
+        // Handle NaN/Infinity with last-valid-value substitution
+        if (!double.IsFinite(actualVal))
+            actualVal = double.IsFinite(_state.LastValidActual) ? _state.LastValidActual : 0.0;
+        else
+            _state.LastValidActual = actualVal;
+
+        if (!double.IsFinite(predictedVal))
+            predictedVal = double.IsFinite(_state.LastValidPredicted) ? _state.LastValidPredicted : 0.0;
+        else
+            _state.LastValidPredicted = predictedVal;
+
+        double error = Math.Abs(actualVal - predictedVal);
+
+        if (isNew)
+        {
+            _p_state = _state;
+
+            double removedValue = _buffer.Count == _buffer.Capacity ? _buffer.Oldest : 0.0;
+            _state.Sum = _state.Sum - removedValue + error;
+            _buffer.Add(error);
+
+            _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 + error;
+            _buffer.UpdateNewest(error);
+            _state.Sum = _buffer.RecalculateSum();
+        }
+
+        double result = _buffer.Count > 0 ? _state.Sum / _buffer.Count : error;
+        Last = new TValue(actual.Time, result);
+        PubEvent(Last, isNew);
+        return Last;
+    }
+
+    /// <summary>
+    /// Updates the MAE with raw double values.
+    /// </summary>
+    [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);
+    }
+
+
+    /// <summary>
+    /// Single-input Update is not supported. Use Update(actual, predicted).
+    /// </summary>
+    public override TValue Update(TValue input, bool isNew = true)
+    {
+        throw new NotSupportedException("MAE requires two inputs. Use Update(actual, predicted).");
+    }
+
+    /// <summary>
+    /// Single-series Update is not supported. Use Calculate(actual, predicted, period).
+    /// </summary>
+    public override TSeries Update(TSeries source)
+    {
+        throw new NotSupportedException("MAE requires two inputs. Use Calculate(actualSeries, predictedSeries, period).");
+    }
+
+    /// <summary>
+    /// Single-series Prime is not supported.
+    /// </summary>
+    public override void Prime(ReadOnlySpan<double> source, TimeSpan? step = null)
+    {
+        throw new NotSupportedException("MAE requires two inputs.");
+    }
+
+    /// <summary>
+    /// Resets the MAE state.
+    /// </summary>
+    public override void Reset()
+    {
+        _buffer.Clear();
+        _state = default;
+        _p_state = default;
+        Last = default;
+    }
+
+    /// <summary>
+    /// Calculates MAE for the entire series pair.
+    /// </summary>
+    /// <param name="actual">Actual values series</param>
+    /// <param name="predicted">Predicted values series</param>
+    /// <param name="period">MAE period</param>
+    /// <returns>MAE series</returns>
+    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);
+    }
+
+    /// <summary>
+    /// Calculates MAE in-place using pre-allocated spans.
+    /// </summary>
+    /// <param name="actual">Actual values</param>
+    /// <param name="predicted">Predicted values</param>
+    /// <param name="output">Output span (must be same length as inputs)</param>
+    /// <param name="period">MAE period (must be > 0)</param>
+    [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;
+
+        CalculateScalarCore(actual, predicted, output, period);
+    }
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    private static void CalculateScalarCore(ReadOnlySpan<double> actual, ReadOnlySpan<double> predicted, Span<double> output, int period)
+    {
+        int len = actual.Length;
+
+        const int StackAllocThreshold = 256;
+        Span<double> buffer = period <= StackAllocThreshold
+            ? stackalloc double[period]
+            : new double[period];
+
+        double sum = 0;
+        double lastValidActual = 0;
+        double lastValidPredicted = 0;
+
+        // Find first valid values
+        for (int k = 0; k < len; k++)
+        {
+            if (double.IsFinite(actual[k]))
+            {
+                lastValidActual = actual[k];
+                break;
+            }
+        }
+        for (int k = 0; k < len; k++)
+        {
+            if (double.IsFinite(predicted[k]))
+            {
+                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)) lastValidActual = act; else act = lastValidActual;
+            if (double.IsFinite(pred)) lastValidPredicted = pred; else pred = lastValidPredicted;
+
+            double error = Math.Abs(act - pred);
+            sum += error;
+            buffer[i] = error;
+            output[i] = sum / (i + 1);
+        }
+
+        int tickCount = 0;
+        for (; i < len; i++)
+        {
+            double act = actual[i];
+            double pred = predicted[i];
+
+            if (double.IsFinite(act)) lastValidActual = act; else act = lastValidActual;
+            if (double.IsFinite(pred)) lastValidPredicted = pred; else pred = lastValidPredicted;
+
+            double error = Math.Abs(act - pred);
+            sum = sum - buffer[bufferIndex] + error;
+            buffer[bufferIndex] = error;
+
+            bufferIndex++;
+            if (bufferIndex >= period) bufferIndex = 0;
+
+            output[i] = 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,125 @@
+# MAE: Mean Absolute Error
+
+> "When you need to know how wrong you are on average, without the drama of squared errors."
+
+Mean Absolute Error (MAE) measures the average magnitude of errors in a set of predictions, without considering their direction. It represents the average of the absolute differences between actual and predicted values.
+
+## Historical Context
+
+MAE is one of the oldest and most intuitive error metrics in statistics. Its simplicity and interpretability have made it a staple in regression analysis, forecasting, and model evaluation since the early days of statistical analysis.
+
+## Architecture & Physics
+
+MAE treats all errors equally, making it more robust to outliers compared to squared-error metrics like MSE. The absolute value operation removes directionality, focusing purely on error magnitude.
+
+### Properties
+
+- **Non-negative**: MAE ≥ 0, with 0 indicating perfect prediction
+- **Same units**: Unlike MSE, MAE is in the same units as the original data
+- **Linear sensitivity**: Each unit of error contributes equally to the final metric
+- **Robust**: Less sensitive to outliers than squared-error metrics
+
+## Mathematical Foundation
+
+### 1. Absolute Error
+
+For each observation, calculate the absolute difference between actual and predicted values:
+
+$$e_i = |y_i - \hat{y}_i|$$
+
+Where:
+- $y_i$ = actual value
+- $\hat{y}_i$ = predicted value
+
+### 2. Mean Calculation
+
+Average the absolute errors over the period:
+
+$$MAE = \frac{1}{n} \sum_{i=1}^{n} |y_i - \hat{y}_i|$$
+
+### 3. Running Update (O(1))
+
+QuanTAlib uses a ring buffer with running sum for O(1) updates:
+
+$$S_{new} = S_{old} - e_{oldest} + e_{newest}$$
+
+$$MAE = \frac{S_{new}}{n}$$
+
+## Implementation Details
+
+### Usage Patterns
+
+```csharp
+// Streaming mode - update with each new observation
+var mae = new Mae(period: 20);
+var result = mae.Update(actualValue, predictedValue);
+
+// Batch mode - calculate for entire series
+var results = Mae.Calculate(actualSeries, predictedSeries, period: 20);
+
+// Span mode - zero-allocation for high performance
+Mae.Batch(actualSpan, predictedSpan, outputSpan, period: 20);
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| **period** | int | Lookback window for averaging (must be > 0) |
+
+### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| **Last** | TValue | Most recent MAE value |
+| **IsHot** | bool | True when buffer is full |
+| **Name** | string | Indicator name (e.g., "Mae(20)") |
+| **WarmupPeriod** | int | Number of periods before valid output |
+
+## Performance Profile
+
+| Metric | Score | Notes |
+| :--- | :--- | :--- |
+| **Throughput** | ~10 ns/bar | O(1) update complexity |
+| **Allocations** | 0 | Uses pre-allocated ring buffer |
+| **Complexity** | O(1) | Constant time per update |
+| **Accuracy** | 10/10 | Exact calculation |
+| **Timeliness** | 9/10 | No lag beyond the period |
+| **Smoothness** | 7/10 | Moderate smoothing |
+
+## Interpretation
+
+| MAE Range | Interpretation |
+| :--- | :--- |
+| **0** | Perfect prediction |
+| **Low** | Predictions are close to actual values |
+| **High** | Large average prediction error |
+
+## Comparison with Other Metrics
+
+| Metric | Outlier Sensitivity | Units | Interpretation |
+| :--- | :--- | :--- | :--- |
+| **MAE** | Low | Same as data | Average absolute error |
+| **MSE** | High | Squared units | Penalizes large errors more |
+| **RMSE** | High | Same as data | MSE in original units |
+| **MAPE** | Varies | Percentage | Relative error |
+
+## Common Use Cases
+
+1. **Forecast Evaluation**: Measure prediction accuracy over time
+2. **Model Comparison**: Compare different prediction models
+3. **Trading Strategy**: Track signal accuracy
+4. **Risk Assessment**: Monitor prediction reliability
+
+## Edge Cases
+
+- **Identical Values**: Returns 0 when actual equals predicted
+- **NaN Handling**: Uses last valid value substitution
+- **Single Input**: Not supported (requires two series)
+- **Period = 1**: Returns current absolute error
+
+## Related Indicators
+
+- [MSE](../mse/Mse.md) - Mean Squared Error
+- [RMSE](../rmse/Rmse.md) - Root Mean Squared Error
+- [MAPE](../mape/Mape.md) - Mean Absolute Percentage Error