README.md (7400B)
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 # Student's t-Test 22 23 > Two-sample Student's t-Test. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var ttest2 = require( '@stdlib/stats/ttest2' ); 31 ``` 32 33 #### ttest2( x, y\[, opts] ) 34 35 By default, the function performs a two-sample t-test for the null hypothesis that the data in [arrays][mdn-array] or [typed arrays][mdn-typed-array] `x` and `y` is independently drawn from normal distributions with _equal_ means. 36 37 ```javascript 38 // Student's sleep data: 39 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 40 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 41 42 var out = ttest2( x, y ); 43 /* e.g., returns 44 { 45 'rejected': false, 46 'pValue': ~0.079, 47 'statistic': ~-1.861, 48 'ci': [ ~-3.365, ~0.205 ], 49 // ... 50 } 51 */ 52 ``` 53 54 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. 55 56 <!-- run-disable --> 57 58 ```javascript 59 console.log( out.print() ); 60 /* e.g., => 61 Welch two-sample t-test 62 63 Alternative hypothesis: True difference in means is not equal to 0 64 65 pValue: 0.0794 66 statistic: -1.8608 67 95% confidence interval: [-3.3655,0.2055] 68 69 Test Decision: Fail to reject null in favor of alternative at 5% significance level 70 */ 71 ``` 72 73 The function accepts the following `options`: 74 75 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 76 - **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`. 77 - **difference**: `number` denoting the difference in means under the null hypothesis. Default: `0`. 78 - **variance**: `string` indicating if the test should be conducted under the assumption that the unknown variances of the normal distributions are `equal` or `unequal`. Default: `unequal`. 79 80 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. 81 82 ```javascript 83 var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ]; 84 var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ]; 85 86 var out = ttest2( x, y, { 87 'alpha': 0.1 88 }); 89 var table = out.print(); 90 /* e.g., returns 91 Welch two-sample t-test 92 93 Alternative hypothesis: True difference in means is not equal to 0 94 95 pValue: 0.0794 96 statistic: -1.8608 97 90% confidence interval: [-3.0534,-0.1066] 98 99 Test Decision: Reject null in favor of alternative at 10% significance level 100 */ 101 ``` 102 103 By default, a two-sided test is performed. To perform either of the one-sided tests, set the `alternative` option to `less` or `greater`. 104 105 ```javascript 106 // Student's sleep data: 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 = ttest2( x, y, { 111 'alternative': 'less' 112 }); 113 var table = out.print(); 114 /* e.g., returns 115 Welch two-sample t-test 116 117 Alternative hypothesis: True difference in means is less than 0 118 119 pValue: 0.0397 120 statistic: -1.8608 121 df: 17.7765 122 95% confidence interval: [-Infinity,-0.1066] 123 124 Test Decision: Reject null in favor of alternative at 5% significance level 125 */ 126 127 out = ttest2( x, y, { 128 'alternative': 'greater' 129 }); 130 table = out.print(); 131 /* e.g., returns 132 Welch two-sample t-test 133 134 Alternative hypothesis: True difference in means is greater than 0 135 136 pValue: 0.9603 137 statistic: -1.8608 138 df: 17.7765 139 95% confidence interval: [-3.0534,Infinity] 140 141 Test Decision: Fail to reject null in favor of alternative at 5% significance level 142 */ 143 ``` 144 145 As a default choice, the `ttest2` function carries out the Welch test (using the Satterthwaite approximation for the degrees of freedom), which does not have the requirement that the variances of the underlying distributions are equal. If the equal variances assumption seems warranted, set the `variance` option to `equal`. 146 147 ```javascript 148 var x = [ 2, 3, 1, 4 ]; 149 var y = [ 1, 2, 3, 1, 2, 5, 3, 4 ]; 150 151 var out = ttest2( x, y, { 152 'variance': 'equal' 153 }); 154 var table = out.print(); 155 /* e.g., returns 156 Two-sample t-test 157 158 Alternative hypothesis: True difference in means is not equal to 0 159 160 pValue: 0.8848 161 statistic: -0.1486 162 df: 10 163 95% confidence interval: [-1.9996,1.7496] 164 165 Test Decision: Fail to reject null in favor of alternative at 5% significance level 166 */ 167 ``` 168 169 To test whether the difference in the population means is equal to some other value than `0`, set the `difference` option. 170 171 ```javascript 172 var normal = require( '@stdlib/random/base/normal' ).factory; 173 174 var table; 175 var rnorm; 176 var out; 177 var x; 178 var y; 179 var i; 180 181 rnorm = normal({ 182 'seed': 372 183 }); 184 185 x = new Array( 100 ); 186 for ( i = 0; i < x.length; i++ ) { 187 x[ i ] = rnorm( 2.0, 3.0 ); 188 } 189 y = new Array( 100 ); 190 for ( i = 0; i < x.length; i++ ) { 191 y[ i ] = rnorm( 1.0, 3.0 ); 192 } 193 194 out = ttest2( x, y, { 195 'difference': 1.0, 196 'variance': 'equal' 197 }); 198 /* e.g., returns 199 { 200 'rejected': false, 201 'pValue': ~0.642, 202 'statistic': ~-0.466, 203 'ci': [ ~-0.0455, ~1.646 ], 204 // ... 205 } 206 */ 207 208 table = out.print(); 209 /* e.g., returns 210 Two-sample t-test 211 212 Alternative hypothesis: True difference in means is not equal to 1 213 214 pValue: 0.6419 215 statistic: -0.4657 216 df: 198 217 95% confidence interval: [-0.0455,1.646] 218 219 Test Decision: Fail to reject null in favor of alternative at 5% significance level 220 */ 221 ``` 222 223 </section> 224 225 <!-- /.usage --> 226 227 <section class="examples"> 228 229 ## Examples 230 231 <!-- eslint no-undef: "error" --> 232 233 ```javascript 234 var incrspace = require( '@stdlib/array/incrspace' ); 235 var ttest2 = require( '@stdlib/stats/ttest2' ); 236 237 var table; 238 var out; 239 var a; 240 var b; 241 242 a = incrspace( 1, 11, 1 ); 243 b = incrspace( 7, 21, 1 ); 244 245 out = ttest2( a, b ); 246 table = out.print(); 247 /* e.g., returns 248 Welch two-sample t-test 249 250 Alternative hypothesis: True difference in means is not equal to 0 251 252 pValue: 0 253 statistic: -5.4349 254 95% confidence interval: [-11.0528,-4.9472] 255 256 Test Decision: Reject null in favor of alternative at 5% significance level 257 */ 258 ``` 259 260 </section> 261 262 <!-- /.examples --> 263 264 <section class="links"> 265 266 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 267 268 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 269 270 </section> 271 272 <!-- /.links -->