README.md (7057B)
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 > One-sample and paired Student's t-Test. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var ttest = require( '@stdlib/stats/ttest' ); 31 ``` 32 33 #### ttest( x\[, y]\[, opts] ) 34 35 The function performs a one-sample t-test for the null hypothesis that the data in [array][mdn-array] or [typed array][mdn-typed-array] `x` is drawn from a normal distribution with mean zero and unknown variance. 36 37 ```javascript 38 var normal = require( '@stdlib/random/base/normal' ).factory; 39 40 var rnorm; 41 var arr; 42 var out; 43 var i; 44 45 rnorm = normal( 0.0, 2.0, { 46 'seed': 5776 47 }); 48 arr = new Array( 100 ); 49 for ( i = 0; i < arr.length; i++ ) { 50 arr[ i ] = rnorm(); 51 } 52 out = ttest( arr ); 53 /* e.g., returns 54 { 55 'rejected': false, 56 'pValue': ~0.722, 57 'statistic': ~0.357, 58 'ci': [~-0.333,~0.479], 59 // ... 60 } 61 */ 62 ``` 63 64 When [array][mdn-array] or [typed array][mdn-typed-array] `y` is supplied, the function tests whether the differences `x - y` come from a normal distribution with mean zero and unknown variance via the paired t-test. 65 66 ```javascript 67 var normal = require( '@stdlib/random/base/normal' ).factory; 68 69 var rnorm; 70 var out; 71 var i; 72 var x; 73 var y; 74 75 rnorm = normal( 1.0, 2.0, { 76 'seed': 786 77 }); 78 x = new Array( 100 ); 79 y = new Array( 100 ); 80 for ( i = 0; i < x.length; i++ ) { 81 x[ i ] = rnorm(); 82 y[ i ] = rnorm(); 83 } 84 out = ttest( x, y ); 85 /* e.g., returns 86 { 87 'rejected': false, 88 'pValue': ~0.191, 89 'statistic': ~1.315, 90 'ci': [ ~-0.196, ~0.964 ], 91 // ... 92 } 93 */ 94 ``` 95 96 The returned object comes with a `.print()` method which when invoked will print a formatted output of the hypothesis test results. `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. 97 98 <!-- run-disable --> 99 100 ```javascript 101 console.log( out.print() ); 102 /* e.g., => 103 Paired t-test 104 105 Alternative hypothesis: True difference in means is not equal to 0 106 107 pValue: 0.1916 108 statistic: 1.3148 109 df: 99 110 95% confidence interval: [-0.1955,0.9635] 111 112 Test Decision: Fail to reject null in favor of alternative at 5% significance level 113 */ 114 ``` 115 116 The `ttest` function accepts the following `options`: 117 118 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 119 - **alternative**: Either `two-sided`, `less` or `greater`. Indicates whether the alternative hypothesis is that the mean of `x` is larger than `mu` (`greater`), smaller than `mu` (`less`) or equal to `mu` (`two-sided`). Default: `two-sided`. 120 - **mu**: `number` denoting the hypothesized true mean under the null hypothesis. Default: `0`. 121 122 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. 123 124 ```javascript 125 var table; 126 var out; 127 var arr; 128 129 arr = [ 2, 4, 3, 1, 0 ]; 130 131 out = ttest( arr, { 132 'alpha': 0.01 133 }); 134 table = out.print(); 135 /* e.g., returns 136 One-sample t-test 137 138 Alternative hypothesis: True mean is not equal to 0 139 140 pValue: 0.0474 141 statistic: 2.8284 142 df: 4 143 99% confidence interval: [-1.2556,5.2556] 144 145 Test Decision: Fail to reject null in favor of alternative at 1% significance level 146 */ 147 148 out = ttest( arr, { 149 'alpha': 0.1 150 }); 151 table = out.print(); 152 /* e.g., returns 153 One-sample t-test 154 155 Alternative hypothesis: True mean is not equal to 0 156 157 pValue: 0.0474 158 statistic: 2.8284 159 df: 4 160 90% confidence interval: [0.4926,3.5074] 161 162 Test Decision: Reject null in favor of alternative at 10% significance level 163 */ 164 ``` 165 166 To test whether the data comes from a distribution with a mean different than zero, set the `mu` option. 167 168 ```javascript 169 var out; 170 var arr; 171 172 arr = [ 4, 4, 6, 6, 5 ]; 173 174 out = ttest( arr, { 175 'mu': 5 176 }); 177 /* e.g., returns 178 { 179 'rejected': false, 180 'pValue': 1, 181 'statistic': 0, 182 'ci': [ ~3.758, ~6.242 ], 183 // ... 184 } 185 */ 186 ``` 187 188 By default, a two-sided test is performed. To perform either of the one-sided tests, set the `alternative` option to `less` or `greater`. 189 190 ```javascript 191 var table; 192 var out; 193 var arr; 194 195 arr = [ 4, 4, 6, 6, 5 ]; 196 197 out = ttest( arr, { 198 'alternative': 'less' 199 }); 200 table = out.print(); 201 /* e.g., returns 202 One-sample t-test 203 204 Alternative hypothesis: True mean is less than 0 205 206 pValue: 0.9998 207 statistic: 11.1803 208 df: 4 209 95% confidence interval: [-Infinity,5.9534] 210 211 Test Decision: Fail to reject null in favor of alternative at 5% significance level 212 */ 213 214 out = ttest( arr, { 215 'alternative': 'greater' 216 }); 217 table = out.print(); 218 /* e.g., returns 219 One-sample t-test 220 221 Alternative hypothesis: True mean is greater than 0 222 223 pValue: 0.0002 224 statistic: 11.1803 225 df: 4 226 95% confidence interval: [4.0466,Infinity] 227 228 Test Decision: Reject null in favor of alternative at 5% significance level 229 */ 230 ``` 231 232 </section> 233 234 <!-- /.usage --> 235 236 <section class="examples"> 237 238 ## Examples 239 240 <!-- eslint no-undef: "error" --> 241 242 ```javascript 243 var normal = require( '@stdlib/random/base/normal' ).factory; 244 var ttest = require( '@stdlib/stats/ttest' ); 245 246 var rnorm; 247 var arr; 248 var out; 249 var i; 250 251 rnorm = normal( 5.0, 4.0, { 252 'seed': 37827 253 }); 254 arr = new Array( 100 ); 255 for ( i = 0; i < arr.length; i++ ) { 256 arr[ i ] = rnorm(); 257 } 258 259 // Test whether true mean is equal to zero: 260 out = ttest( arr ); 261 console.log( out.print() ); 262 /* e.g., => 263 One-sample t-test 264 265 Alternative hypothesis: True mean is not equal to 0 266 267 pValue: 0 268 statistic: 15.0513 269 df: 99 270 95% confidence interval: [4.6997,6.127] 271 272 Test Decision: Reject null in favor of alternative at 5% significance level 273 */ 274 275 // Test whether true mean is equal to five: 276 out = ttest( arr, { 277 'mu': 5.0 278 }); 279 console.log( out.print() ); 280 /* e.g., => 281 One-sample t-test 282 283 Alternative hypothesis: True mean is not equal to 5 284 285 pValue: 0.2532 286 statistic: 1.1494 287 df: 99 288 95% confidence interval: [4.6997,6.127] 289 290 Test Decision: Fail to reject null in favor of alternative at 5% significance level 291 */ 292 ``` 293 294 </section> 295 296 <!-- /.examples --> 297 298 <section class="links"> 299 300 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 301 302 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 303 304 </section> 305 306 <!-- /.links -->