README.md (5315B)
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 # incrmpcorrdist 22 23 > Compute a moving [sample Pearson product-moment correlation distance][pearson-correlation] incrementally. 24 25 <section class="intro"> 26 27 The [sample Pearson product-moment correlation distance][pearson-correlation] is defined as 28 29 <!-- <equation class="equation" label="eq:pearson_distance" align="center" raw="d_{x,y} = 1 - r_{x,y} = 1 - \frac{\operatorname{cov_n(x,y)}}{\sigma_x \sigma_y}" alt="Equation for the Pearson product-moment correlation distance."> --> 30 31 <div class="equation" align="center" data-raw-text="d_{x,y} = 1 - r_{x,y} = 1 - \frac{\operatorname{cov_n(x,y)}}{\sigma_x \sigma_y}" data-equation="eq:pearson_distance"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@49d8cabda84033d55d7b8069f19ee3dd8b8d1496/lib/node_modules/@stdlib/stats/incr/mpcorrdist/docs/img/equation_pearson_distance.svg" alt="Equation for the Pearson product-moment correlation distance."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `r` is the [sample Pearson product-moment correlation coefficient][pearson-correlation], `cov(x,y)` is the sample covariance, and `σ` corresponds to the sample standard deviation. As `r` resides on the interval `[-1,1]`, `d` resides on the interval `[0,2]`. 39 40 </section> 41 42 <!-- /.intro --> 43 44 <section class="usage"> 45 46 ## Usage 47 48 ```javascript 49 var incrmpcorrdist = require( '@stdlib/stats/incr/mpcorrdist' ); 50 ``` 51 52 #### incrmpcorrdist( window\[, mx, my] ) 53 54 Returns an accumulator `function` which incrementally computes a moving [sample Pearson product-moment correlation distance][pearson-correlation]. The `window` parameter defines the number of values over which to compute the moving [sample Pearson product-moment correlation distance][pearson-correlation]. 55 56 ```javascript 57 var accumulator = incrmpcorrdist( 3 ); 58 ``` 59 60 If means are already known, provide `mx` and `my` arguments. 61 62 ```javascript 63 var accumulator = incrmpcorrdist( 3, 5.0, -3.14 ); 64 ``` 65 66 #### accumulator( \[x, y] ) 67 68 If provided input values `x` and `y`, the accumulator function returns an updated [sample Pearson product-moment correlation distance][pearson-correlation]. If not provided input values `x` and `y`, the accumulator function returns the current [sample Pearson product-moment correlation distance][pearson-correlation]. 69 70 ```javascript 71 var accumulator = incrmpcorrdist( 3 ); 72 73 var r = accumulator(); 74 // returns null 75 76 // Fill the window... 77 r = accumulator( 2.0, 1.0 ); // [(2.0, 1.0)] 78 // returns 1.0 79 80 r = accumulator( -5.0, 3.14 ); // [(2.0, 1.0), (-5.0, 3.14)] 81 // returns ~2.0 82 83 r = accumulator( 3.0, -1.0 ); // [(2.0, 1.0), (-5.0, 3.14), (3.0, -1.0)] 84 // returns ~1.925 85 86 // Window begins sliding... 87 r = accumulator( 5.0, -9.5 ); // [(-5.0, 3.14), (3.0, -1.0), (5.0, -9.5)] 88 // returns ~1.863 89 90 r = accumulator( -5.0, 1.5 ); // [(3.0, -1.0), (5.0, -9.5), (-5.0, 1.5)] 91 // returns ~1.803 92 93 r = accumulator(); 94 // returns ~1.803 95 ``` 96 97 </section> 98 99 <!-- /.usage --> 100 101 <section class="notes"> 102 103 ## Notes 104 105 - 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. 106 - As `W` (x,y) 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. 107 - Due to limitations inherent in representing numeric values using floating-point format (i.e., the inability to represent numeric values with infinite precision), the [sample correlation distance][pearson-correlation] between perfectly correlated random variables may **not** be `0` or `2`. In fact, the [sample correlation distance][pearson-correlation] is **not** guaranteed to be strictly on the interval `[0,2]`. Any computed distance should, however, be within floating-point roundoff error. 108 109 </section> 110 111 <!-- /.notes --> 112 113 <section class="examples"> 114 115 ## Examples 116 117 <!-- eslint no-undef: "error" --> 118 119 ```javascript 120 var randu = require( '@stdlib/random/base/randu' ); 121 var incrmpcorrdist = require( '@stdlib/stats/incr/mpcorrdist' ); 122 123 var accumulator; 124 var x; 125 var y; 126 var i; 127 128 // Initialize an accumulator: 129 accumulator = incrmpcorrdist( 5 ); 130 131 // For each simulated datum, update the moving sample correlation distance... 132 for ( i = 0; i < 100; i++ ) { 133 x = randu() * 100.0; 134 y = randu() * 100.0; 135 accumulator( x, y ); 136 } 137 console.log( accumulator() ); 138 ``` 139 140 </section> 141 142 <!-- /.examples --> 143 144 <section class="links"> 145 146 [pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient 147 148 </section> 149 150 <!-- /.links -->