README.md (6795B)
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 # incrpcorrdistmat 22 23 > Compute a [sample Pearson product-moment correlation distance matrix][pearson-correlation] incrementally. 24 25 <section class="intro"> 26 27 A [sample Pearson product-moment correlation distance matrix][pearson-correlation] is an M-by-M matrix whose elements specified by indices `j` and `k` are the [sample Pearson product-moment correlation distances][pearson-correlation] between the jth and kth data variables. 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/pcorrdistmat/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 incrpcorrdistmat = require( '@stdlib/stats/incr/pcorrdistmat' ); 50 ``` 51 52 #### incrpcorrdistmat( out\[, means] ) 53 54 Returns an accumulator `function` which incrementally computes a [sample Pearson product-moment correlation distance matrix][pearson-correlation]. 55 56 ```javascript 57 // Create an accumulator for computing a 2-dimensional correlation distance matrix: 58 var accumulator = incrpcorrdistmat( 2 ); 59 ``` 60 61 The `out` argument may be either the order of the [correlation distance matrix][pearson-correlation] or a square 2-dimensional [`ndarray`][@stdlib/ndarray/ctor] for storing the [correlation distance matrix][pearson-correlation]. 62 63 ```javascript 64 var Float64Array = require( '@stdlib/array/float64' ); 65 var ndarray = require( '@stdlib/ndarray/ctor' ); 66 67 var buffer = new Float64Array( 4 ); 68 var shape = [ 2, 2 ]; 69 var strides = [ 2, 1 ]; 70 71 // Create a 2-dimensional output correlation distance matrix: 72 var dist = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 73 74 var accumulator = incrpcorrdistmat( dist ); 75 ``` 76 77 When means are known, the function supports providing a 1-dimensional [`ndarray`][@stdlib/ndarray/ctor] containing mean values. 78 79 ```javascript 80 var Float64Array = require( '@stdlib/array/float64' ); 81 var ndarray = require( '@stdlib/ndarray/ctor' ); 82 83 var buffer = new Float64Array( 2 ); 84 var shape = [ 2 ]; 85 var strides = [ 1 ]; 86 87 var means = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 88 89 means.set( 0, 3.0 ); 90 means.set( 1, -5.5 ); 91 92 var accumulator = incrpcorrdistmat( 2, means ); 93 ``` 94 95 #### accumulator( \[vector] ) 96 97 If provided a data vector, the accumulator function returns an updated [sample Pearson product-moment distance correlation matrix][pearson-correlation]. If not provided a data vector, the accumulator function returns the current [sample Pearson product-moment correlation distance matrix][pearson-correlation]. 98 99 ```javascript 100 var Float64Array = require( '@stdlib/array/float64' ); 101 var ndarray = require( '@stdlib/ndarray/ctor' ); 102 103 var buffer = new Float64Array( 4 ); 104 var shape = [ 2, 2 ]; 105 var strides = [ 2, 1 ]; 106 var dist = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 107 108 buffer = new Float64Array( 2 ); 109 shape = [ 2 ]; 110 strides = [ 1 ]; 111 var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 112 113 var accumulator = incrpcorrdistmat( dist ); 114 115 vec.set( 0, 2.0 ); 116 vec.set( 1, 1.0 ); 117 118 var out = accumulator( vec ); 119 // returns <ndarray> 120 121 var bool = ( out === dist ); 122 // returns true 123 124 vec.set( 0, 1.0 ); 125 vec.set( 1, -5.0 ); 126 127 out = accumulator( vec ); 128 // returns <ndarray> 129 130 vec.set( 0, 3.0 ); 131 vec.set( 1, 3.14 ); 132 133 out = accumulator( vec ); 134 // returns <ndarray> 135 136 out = accumulator(); 137 // returns <ndarray> 138 ``` 139 140 </section> 141 142 <!-- /.usage --> 143 144 <section class="notes"> 145 146 ## Notes 147 148 - Due to limitations inherent in representing numeric values using floating-point format (i.e., the inability to represent numeric values with infinite precision), the [correlation distance][pearson-correlation] between perfectly correlated random variables may **not** be `0` or `2`. In fact, the [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. 149 150 </section> 151 152 <!-- /.notes --> 153 154 <section class="examples"> 155 156 ## Examples 157 158 <!-- eslint no-undef: "error" --> 159 160 ```javascript 161 var randu = require( '@stdlib/random/base/randu' ); 162 var ndarray = require( '@stdlib/ndarray/ctor' ); 163 var Float64Array = require( '@stdlib/array/float64' ); 164 var incrpcorrdistmat = require( '@stdlib/stats/incr/pcorrdistmat' ); 165 166 var dist; 167 var dxy; 168 var dyx; 169 var dx; 170 var dy; 171 var i; 172 173 // Initialize an accumulator for a 2-dimensional correlation distance matrix: 174 var accumulator = incrpcorrdistmat( 2 ); 175 176 // Create a 1-dimensional data vector: 177 var buffer = new Float64Array( 2 ); 178 var shape = [ 2 ]; 179 var strides = [ 1 ]; 180 181 var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 182 183 // For each simulated data vector, update the sample correlation distance matrix... 184 for ( i = 0; i < 100; i++ ) { 185 vec.set( 0, randu()*100.0 ); 186 vec.set( 1, randu()*100.0 ); 187 dist = accumulator( vec ); 188 189 dx = dist.get( 0, 0 ).toFixed( 4 ); 190 dy = dist.get( 1, 1 ).toFixed( 4 ); 191 dxy = dist.get( 0, 1 ).toFixed( 4 ); 192 dyx = dist.get( 1, 0 ).toFixed( 4 ); 193 194 console.log( '[ %d, %d\n %d, %d ]', dx, dxy, dyx, dy ); 195 } 196 ``` 197 198 </section> 199 200 <!-- /.examples --> 201 202 <section class="links"> 203 204 [pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient 205 206 [@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor 207 208 </section> 209 210 <!-- /.links -->