README.md (6690B)
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 # Correlation Test 22 23 > Compute a Pearson product-moment correlation test between paired samples. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var pcorrtest = require( '@stdlib/stats/pcorrtest' ); 31 ``` 32 33 #### pcorrtest( x, y\[, opts] ) 34 35 By default, the function performs a t-test for the null hypothesis that the paired data in [arrays][mdn-array] or [typed arrays][mdn-typed-array] `x` and `y` have a [Pearson correlation coefficient][pearson-correlation] of zero. 36 37 ```javascript 38 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 39 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 40 41 var out = pcorrtest( x, y ); 42 /* e.g., returns 43 { 44 'alpha': 0.05, 45 'rejected': true, 46 'pValue': ~0.006, 47 'statistic': ~3.709, 48 'ci': [ ~0.332, ~0.95 ], 49 'nullValue': 0, 50 'pcorr': ~0.795, 51 // ... 52 } 53 */ 54 ``` 55 56 The returned object comes with a `.print()` method which when invoked will print a formatted output of the results of the hypothesis test. `print` accepts a `digits` option that controls the number of decimal digits displayed for the outputs and a `decision` option, which when set to `false` will hide the test decision. 57 58 <!-- run-disable --> 59 60 ```javascript 61 console.log( out.print() ); 62 /* e.g., => 63 t-test for Pearson correlation coefficient 64 65 Alternative hypothesis: True correlation coefficient is not equal to 0 66 67 pValue: 0.006 68 statistic: 3.709 69 95% confidence interval: [0.3315,0.9494] 70 71 Test Decision: Reject null in favor of alternative at 5% significance level 72 */ 73 ``` 74 75 The function accepts the following `options`: 76 77 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 78 - **alternative**: Either `two-sided`, `less` or `greater`. Indicates whether the alternative hypothesis is that `x` has a larger mean than `y` (`greater`), `x` has a smaller mean than `y` (`less`) or the means are the same (`two-sided`). Default: `two-sided`. 79 - **rho**: `number` denoting the correlation between the `x` and `y` variables under the null hypothesis. Default: `0`. 80 81 By default, the hypothesis test is carried out at a significance level of `0.05`. To choose a different significance level, set the `alpha` option. 82 83 ```javascript 84 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 85 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 86 87 var out = pcorrtest( x, y, { 88 'alpha': 0.1 89 }); 90 var table = out.print(); 91 /* e.g., returns 92 t-test for Pearson correlation coefficient 93 94 Alternative hypothesis: True correlation coefficient is not equal to 0 95 96 pValue: 0.006 97 statistic: 3.709 98 90% confidence interval: [0.433,0.9363] 99 100 Test Decision: Reject null in favor of alternative at 10% significance level 101 */ 102 ``` 103 104 By default, a two-sided test is performed. To perform either of the one-sided tests, set the `alternative` option to `less` or `greater`. 105 106 ```javascript 107 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 108 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 109 110 var out = pcorrtest( x, y, { 111 'alternative': 'less' 112 }); 113 var table = out.print(); 114 /* e.g., returns 115 t-test for Pearson correlation coefficient 116 117 Alternative hypothesis: True correlation coefficient is less than 0 118 119 pValue: 0.997 120 statistic: 3.709 121 95% confidence interval: [-1,0.9363] 122 123 Test Decision: Fail to reject null in favor of alternative at 5% significance level 124 */ 125 126 out = pcorrtest( x, y, { 127 'alternative': 'greater' 128 }); 129 table = out.print(); 130 /* e.g., returns 131 t-test for Pearson correlation coefficient 132 133 Alternative hypothesis: True correlation coefficient is greater than 0 134 135 pValue: 0.003 136 statistic: 3.709 137 95% confidence interval: [0.433,1] 138 139 Test Decision: Reject null in favor of alternative at 5% significance level 140 */ 141 ``` 142 143 To test whether the correlation coefficient is equal to some other value than `0`, set the `rho` option. Hypotheses tests for correlation coefficients besides zero are carried out using the [Fisher z-transformation][fisher-transform]. 144 145 ```javascript 146 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 147 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 148 149 var out = pcorrtest( x, y, { 150 'rho': 0.8 151 }); 152 /* e.g., returns 153 { 154 'alpha': 0.05, 155 'rejected': false, 156 'pValue': ~0.972, 157 'statistic': ~-0.035, 158 'ci': [ ~0.332, ~0.949 ], 159 'nullValue': 0.8, 160 'pcorr': ~0.795, 161 // ... 162 } 163 */ 164 165 var table = out.print(); 166 /* e.g., returns 167 Fisher's z transform test for Pearson correlation coefficient 168 169 Alternative hypothesis: True correlation coefficient is not equal to 0.8 170 171 pValue: 0.972 172 statistic: -0.0351 173 95% confidence interval: [0.3315,0.9494] 174 175 Test Decision: Fail to reject null in favor of alternative at 5% significance level 176 */ 177 ``` 178 179 </section> 180 181 <!-- /.usage --> 182 183 <section class="examples"> 184 185 ## Examples 186 187 <!-- eslint no-undef: "error" --> 188 189 ```javascript 190 var rnorm = require( '@stdlib/random/base/normal' ); 191 var sqrt = require( '@stdlib/math/base/special/sqrt' ); 192 var pcorrtest = require( '@stdlib/stats/pcorrtest' ); 193 194 var table; 195 var out; 196 var rho; 197 var x; 198 var y; 199 var i; 200 201 rho = 0.5; 202 x = new Array( 300 ); 203 y = new Array( 300 ); 204 for ( i = 0; i < 300; i++ ) { 205 x[ i ] = rnorm( 0.0, 1.0 ); 206 y[ i ] = ( rho * x[ i ] ) + rnorm( 0.0, sqrt( 1.0 - (rho*rho) ) ); 207 } 208 209 out = pcorrtest( x, y ); 210 table = out.print(); 211 console.log( table ); 212 213 out = pcorrtest( x, y, { 214 'rho': 0.5 215 }); 216 table = out.print(); 217 console.log( table ); 218 ``` 219 220 </section> 221 222 <!-- /.examples --> 223 224 <section class="links"> 225 226 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 227 228 [fisher-transform]: https://en.wikipedia.org/wiki/Fisher_transformation 229 230 [pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient 231 232 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 233 234 </section> 235 236 <!-- /.links -->