QuanTAlib/lib/errors/mdape/Mdape.md

MdAPE: Median Absolute Percentage Error

"When you need relative errors but can't trust the outliers."

Median Absolute Percentage Error (MdAPE) combines the scale-independence of percentage errors with the robustness of median statistics. It provides a measure of typical relative prediction accuracy that remains stable even when some predictions are dramatically wrong.

Historical Context

MdAPE arose as a natural combination of two statistical improvements: using percentages for scale-independence (like MAPE) and using medians for robustness (like MdAE). This hybrid approach addresses both the scale problem of MAE and the outlier sensitivity of MAPE.

Architecture & Physics

MdAPE first normalizes each error as a percentage of the actual value, then finds the median of these percentages. This two-stage approach provides both relative context and outlier resistance.

Properties

• Scale-independent: Comparable across different data magnitudes
• Outlier-robust: Extreme errors don't skew results
• Percentage-based: Results are interpretable as "typical % error"
• Non-negative: MdAPE ≥ 0, with 0 indicating perfect prediction

Mathematical Foundation

1. Absolute Percentage Error

For each observation, calculate the percentage error:

e_i = \frac{|y_i - \hat{y}_i|}{|y_i|} \times 100

Where:

• y_i = actual value
• \hat{y}_i = predicted value

2. Median Calculation

Find the middle value of the sorted percentage errors:

MdAPE = \text{median}(e_1, e_2, ..., e_n)

3. Running Update (O(1))

QuanTAlib uses a sorted ring buffer for efficient median retrieval:

$$MdAPE = \begin{cases} e_{(n+1)/2} & \text{if } n \text{ is odd} \ \frac{e_{n/2} + e_{n/2+1}}{2} & \text{if } n \text{ is even} \end{cases}$$

Implementation Details

Usage Patterns

// Streaming mode - update with each new observation
var mdape = new Mdape(period: 20);
var result = mdape.Update(actualValue, predictedValue);

// Batch mode - calculate for entire series
var results = Mdape.Calculate(actualSeries, predictedSeries, period: 20);

// Span mode - zero-allocation for high performance
Mdape.Batch(actualSpan, predictedSpan, outputSpan, period: 20);

Parameters

Parameter	Type	Description
period	int	Lookback window for median calculation (must be > 0)

Properties

Property	Type	Description
Last	TValue	Most recent MdAPE value (in percentage)
IsHot	bool	True when buffer is full
Name	string	Indicator name (e.g., "Mdape(20)")
WarmupPeriod	int	Number of periods before valid output

Performance Profile

Metric	Score	Notes
Throughput	~25 ns/bar	O(1) with sorted buffer
Allocations	0	Uses pre-allocated buffers
Complexity	O(1)	Constant time per update
Accuracy	10/10	Exact calculation
Timeliness	9/10	No lag beyond the period
Robustness	10/10	Immune to outliers

Interpretation

MdAPE Range	Interpretation
0%	Perfect prediction
0-5%	Excellent accuracy
5-10%	Good accuracy
10-20%	Acceptable accuracy
> 20%	Poor accuracy

Comparison with MAPE

Scenario	MAPE	MdAPE
Normal distribution	Similar values	Similar values
Single 1000% error	Heavily inflated	Unchanged
Asymmetric errors	Biased	Representative
Zero actual values	Undefined	Undefined (uses substitution)

Common Use Cases

1. Retail Forecasting: Track typical accuracy across SKUs with varying prices
2. Financial Analysis: Evaluate prediction quality ignoring market crashes
3. Model Selection: Choose models based on typical rather than average performance
4. Operations Research: Measure forecast reliability for planning

Edge Cases

• Zero Actual Values: Substitutes with small epsilon to avoid division by zero
• NaN Handling: Uses last valid value substitution
• Single Input: Not supported (requires two series)
• Period = 1: Returns current absolute percentage error
• All Perfect: Returns 0%

Related Indicators

• MAPE - Mean Absolute Percentage Error (uses mean)
• MdAE - Median Absolute Error (non-percentage)
• SMAPE - Symmetric MAPE (different normalization)