README.md (5136B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # incrmmaape 22 23 > Compute a moving [mean arctangent absolute percentage error][@kim:2016a] (MAAPE) incrementally. 24 25 <section class="intro"> 26 27 For a window of size `W`, the [mean arctangent absolute percentage error][@kim:2016a] is defined as 28 29 <!-- <equation class="equation" label="eq:mean_arctangent_absolute_percentage_error" align="center" raw="\operatorname{MAAPE} = \frac{1}{W} \sum_{i=0}^{W-1} \operatorname{arctan}\biggl( \biggl| \frac{a_i - f_i}{a_i} \biggr| \biggr)" alt="Equation for the mean arctangent absolute percentage error."> --> 30 31 <div class="equation" align="center" data-raw-text="\operatorname{MAAPE} = \frac{1}{W} \sum_{i=0}^{W-1} \operatorname{arctan} \biggl( \biggl| \frac{a_i - f_i}{a_i} \biggr| \biggr)" data-equation="eq:mean_arctangent_absolute_percentage_error"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@677f6828831c61cabc84859897a5ee7e079d6ddf/lib/node_modules/@stdlib/stats/incr/mmaape/docs/img/equation_mean_arctangent_absolute_percentage_error.svg" alt="Equation for the mean arctangent absolute percentage error."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `f_i` is the forecast value and `a_i` is the actual value. 39 40 </section> 41 42 <!-- /.intro --> 43 44 <section class="usage"> 45 46 ## Usage 47 48 ```javascript 49 var incrmmaape = require( '@stdlib/stats/incr/mmaape' ); 50 ``` 51 52 #### incrmmaape( window ) 53 54 Returns an accumulator `function` which incrementally computes a moving [mean arctangent absolute percentage error][@kim:2016a]. The `window` parameter defines the number of values over which to compute the moving [mean arctangent absolute percentage error][@kim:2016a]. 55 56 ```javascript 57 var accumulator = incrmmaape( 3 ); 58 ``` 59 60 #### accumulator( \[f, a] ) 61 62 If provided input values `f` and `a`, the accumulator function returns an updated [mean arctangent absolute percentage error][@kim:2016a]. If not provided input values `f` and `a`, the accumulator function returns the current [mean arctangent absolute percentage error][@kim:2016a]. 63 64 ```javascript 65 var accumulator = incrmmaape( 3 ); 66 67 var m = accumulator(); 68 // returns null 69 70 // Fill the window... 71 m = accumulator( 2.0, 3.0 ); // [(2.0,3.0)] 72 // returns ~0.32 73 74 m = accumulator( 1.0, 4.0 ); // [(2.0,3.0), (1.0,4.0)] 75 // returns ~0.48 76 77 m = accumulator( 3.0, 9.0 ); // [(2.0,3.0), (1.0,4.0), (3.0,9.0)] 78 // returns ~0.52 79 80 // Window begins sliding... 81 m = accumulator( 7.0, 3.0 ); // [(1.0,4.0), (3.0,9.0), (7.0,3.0)] 82 // returns ~0.72 83 84 m = accumulator( 5.0, 3.0 ); // [(3.0,9.0), (7.0,3.0), (5.0,3.0)] 85 // returns ~0.70 86 87 m = accumulator(); 88 // returns ~0.70 89 ``` 90 91 </section> 92 93 <!-- /.usage --> 94 95 <section class="notes"> 96 97 ## Notes 98 99 - Input values are **not** type checked. If provided `NaN` or a value which, when used in computations, results in `NaN`, the accumulated value is `NaN` for **at least** `W-1` future invocations. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function. 100 - As `W` (f,a) pairs are needed to fill the window buffer, the first `W-1` returned values are calculated from smaller sample sizes. Until the window is full, each returned value is calculated from all provided values. 101 - Note that, unlike the [mean absolute percentage error][@stdlib/stats/incr/mape] (MAPE), the [mean arctangent absolute percentage error][@kim:2016a] is expressed in radians on the interval \[0,π/2]. 102 103 </section> 104 105 <!-- /.notes --> 106 107 <section class="examples"> 108 109 ## Examples 110 111 <!-- eslint no-undef: "error" --> 112 113 ```javascript 114 var randu = require( '@stdlib/random/base/randu' ); 115 var incrmmaape = require( '@stdlib/stats/incr/mmaape' ); 116 117 var accumulator; 118 var v1; 119 var v2; 120 var i; 121 122 // Initialize an accumulator: 123 accumulator = incrmmaape( 5 ); 124 125 // For each simulated datum, update the moving mean arctangent absolute percentage error... 126 for ( i = 0; i < 100; i++ ) { 127 v1 = ( randu()*100.0 ) + 50.0; 128 v2 = ( randu()*100.0 ) + 50.0; 129 accumulator( v1, v2 ); 130 } 131 console.log( accumulator() ); 132 ``` 133 134 </section> 135 136 <!-- /.examples --> 137 138 <section class="references"> 139 140 ## References 141 142 - Kim, Sungil, and Heeyoung Kim. 2016. "A new metric of absolute percentage error for intermittent demand forecasts." _International Journal of Forecasting_ 32 (3): 669–79. doi:[10.1016/j.ijforecast.2015.12.003][@kim:2016a]. 143 144 </section> 145 146 <!-- /.references --> 147 148 <section class="links"> 149 150 [@kim:2016a]: https://www.sciencedirect.com/science/article/pii/S0169207016000121 151 152 [@stdlib/stats/incr/mape]: https://www.npmjs.com/package/@stdlib/stats/tree/main/incr/mape 153 154 </section> 155 156 <!-- /.links -->