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