README.md (7141B)
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 # incrpcorrmat 22 23 > Compute a [sample Pearson product-moment correlation matrix][pearson-correlation] incrementally. 24 25 <section class="intro"> 26 27 A [Pearson product-moment correlation matrix][pearson-correlation] is an M-by-M matrix whose elements specified by indices `j` and `k` are the [Pearson product-moment correlation coefficients][pearson-correlation] between the jth and kth data variables. The [Pearson product-moment correlation coefficient][pearson-correlation] between random variables `X` and `Y` is defined as 28 29 <!-- <equation class="equation" label="eq:pearson_correlation_coefficient" align="center" raw="\rho_{X,Y} = \frac{\operatorname{cov}(X,Y)}{\sigma_X \sigma_Y}" alt="Equation for the Pearson product-moment correlation coefficient."> --> 30 31 <div class="equation" align="center" data-raw-text="\rho_{X,Y} = \frac{\operatorname{cov}(X,Y)}{\sigma_X \sigma_Y}" data-equation="eq:pearson_correlation_coefficient"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@49d8cabda84033d55d7b8069f19ee3dd8b8d1496/lib/node_modules/@stdlib/stats/incr/pcorrmat/docs/img/equation_pearson_correlation_coefficient.svg" alt="Equation for the Pearson product-moment correlation coefficient."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where the numerator is the [covariance][covariance] and the denominator is the product of the respective standard deviations. 39 40 For a sample of size `n`, the [sample Pearson product-moment correlation coefficient][pearson-correlation] is defined as 41 42 <!-- <equation class="equation" label="eq:sample_pearson_correlation_coefficient" align="center" raw="r = \frac{\sum_{i=0}^{n-1} (x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=0}^{n-1} (x_i - \bar{x})^2} \sqrt{\sum_{i=0}^{n-1} (y_i - \bar{y})^2}}" alt="Equation for the sample Pearson product-moment correlation coefficient."> --> 43 44 <div class="equation" align="center" data-raw-text="r = \frac{\sum_{i=0}^{n-1} (x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=0}^{n-1} (x_i - \bar{x})^2} \sqrt{\sum_{i=0}^{n-1} (y_i - \bar{y})^2}}" data-equation="eq:sample_pearson_correlation_coefficient"> 45 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@49d8cabda84033d55d7b8069f19ee3dd8b8d1496/lib/node_modules/@stdlib/stats/incr/pcorrmat/docs/img/equation_sample_pearson_correlation_coefficient.svg" alt="Equation for the sample Pearson product-moment correlation coefficient."> 46 <br> 47 </div> 48 49 <!-- </equation> --> 50 51 </section> 52 53 <!-- /.intro --> 54 55 <section class="usage"> 56 57 ## Usage 58 59 ```javascript 60 var incrpcorrmat = require( '@stdlib/stats/incr/pcorrmat' ); 61 ``` 62 63 #### incrpcorrmat( out\[, means] ) 64 65 Returns an accumulator `function` which incrementally computes a [sample Pearson product-moment correlation matrix][pearson-correlation]. 66 67 ```javascript 68 // Create an accumulator for computing a 2-dimensional correlation matrix: 69 var accumulator = incrpcorrmat( 2 ); 70 ``` 71 72 The `out` argument may be either the order of the [correlation matrix][pearson-correlation] or a square 2-dimensional [`ndarray`][@stdlib/ndarray/ctor] for storing the [correlation matrix][pearson-correlation]. 73 74 ```javascript 75 var Float64Array = require( '@stdlib/array/float64' ); 76 var ndarray = require( '@stdlib/ndarray/ctor' ); 77 78 var buffer = new Float64Array( 4 ); 79 var shape = [ 2, 2 ]; 80 var strides = [ 2, 1 ]; 81 82 // Create a 2-dimensional output correlation matrix: 83 var corr = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 84 85 var accumulator = incrpcorrmat( corr ); 86 ``` 87 88 When means are known, the function supports providing a 1-dimensional [`ndarray`][@stdlib/ndarray/ctor] containing mean values. 89 90 ```javascript 91 var Float64Array = require( '@stdlib/array/float64' ); 92 var ndarray = require( '@stdlib/ndarray/ctor' ); 93 94 var buffer = new Float64Array( 2 ); 95 var shape = [ 2 ]; 96 var strides = [ 1 ]; 97 98 var means = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 99 100 means.set( 0, 3.0 ); 101 means.set( 1, -5.5 ); 102 103 var accumulator = incrpcorrmat( 2, means ); 104 ``` 105 106 #### accumulator( \[vector] ) 107 108 If provided a data vector, the accumulator function returns an updated [sample Pearson product-moment correlation matrix][pearson-correlation]. If not provided a data vector, the accumulator function returns the current [sample Pearson product-moment correlation matrix][pearson-correlation]. 109 110 ```javascript 111 var Float64Array = require( '@stdlib/array/float64' ); 112 var ndarray = require( '@stdlib/ndarray/ctor' ); 113 114 var buffer = new Float64Array( 4 ); 115 var shape = [ 2, 2 ]; 116 var strides = [ 2, 1 ]; 117 var corr = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 118 119 buffer = new Float64Array( 2 ); 120 shape = [ 2 ]; 121 strides = [ 1 ]; 122 var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 123 124 var accumulator = incrpcorrmat( corr ); 125 126 vec.set( 0, 2.0 ); 127 vec.set( 1, 1.0 ); 128 129 var out = accumulator( vec ); 130 // returns <ndarray> 131 132 var bool = ( out === corr ); 133 // returns true 134 135 vec.set( 0, 1.0 ); 136 vec.set( 1, -5.0 ); 137 138 out = accumulator( vec ); 139 // returns <ndarray> 140 141 vec.set( 0, 3.0 ); 142 vec.set( 1, 3.14 ); 143 144 out = accumulator( vec ); 145 // returns <ndarray> 146 147 out = accumulator(); 148 // returns <ndarray> 149 ``` 150 151 </section> 152 153 <!-- /.usage --> 154 155 <section class="notes"> 156 157 </section> 158 159 <!-- /.notes --> 160 161 <section class="examples"> 162 163 ## Examples 164 165 <!-- eslint no-undef: "error" --> 166 167 ```javascript 168 var randu = require( '@stdlib/random/base/randu' ); 169 var ndarray = require( '@stdlib/ndarray/ctor' ); 170 var Float64Array = require( '@stdlib/array/float64' ); 171 var incrpcorrmat = require( '@stdlib/stats/incr/pcorrmat' ); 172 173 var corr; 174 var rxy; 175 var ryx; 176 var rx; 177 var ry; 178 var i; 179 180 // Initialize an accumulator for a 2-dimensional correlation matrix: 181 var accumulator = incrpcorrmat( 2 ); 182 183 // Create a 1-dimensional data vector: 184 var buffer = new Float64Array( 2 ); 185 var shape = [ 2 ]; 186 var strides = [ 1 ]; 187 188 var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' ); 189 190 // For each simulated data vector, update the sample correlation matrix... 191 for ( i = 0; i < 100; i++ ) { 192 vec.set( 0, randu()*100.0 ); 193 vec.set( 1, randu()*100.0 ); 194 corr = accumulator( vec ); 195 196 rx = corr.get( 0, 0 ).toFixed( 4 ); 197 ry = corr.get( 1, 1 ).toFixed( 4 ); 198 rxy = corr.get( 0, 1 ).toFixed( 4 ); 199 ryx = corr.get( 1, 0 ).toFixed( 4 ); 200 201 console.log( '[ %d, %d\n %d, %d ]', rx, rxy, ryx, ry ); 202 } 203 ``` 204 205 </section> 206 207 <!-- /.examples --> 208 209 <section class="links"> 210 211 [pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient 212 213 [covariance]: https://en.wikipedia.org/wiki/Covariance 214 215 [@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor 216 217 </section> 218 219 <!-- /.links -->