mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-03 03:47:42 +00:00
Miha Kralj
86fe32a682
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: aider (openrouter/anthropic/claude-sonnet-4) <aider@aider.chat> Co-authored-by: Warp <agent@warp.dev>
130 lines
4.4 KiB
Markdown
130 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```csharp
|
|
// 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](../mape/Mape.md) - Mean Absolute Percentage Error (uses mean)
|
|
* [MdAE](../mdae/Mdae.md) - Median Absolute Error (non-percentage)
|
|
* [SMAPE](../smape/Smape.md) - Symmetric MAPE (different normalization)
|