README.md (6309B)
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 # Z-Test 22 23 > One-sample z-Test. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var ztest = require( '@stdlib/stats/ztest' ); 31 ``` 32 33 #### ztest( x, sigma\[, opts] ) 34 35 The function performs a one-sample z-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 known standard deviation `sigma`. 36 37 ```javascript 38 var normal = require( '@stdlib/random/base/normal' ).factory; 39 40 var rnorm = normal( 0.0, 2.0, { 41 'seed': 5776 42 }); 43 44 var arr = new Array( 300 ); 45 var i; 46 for ( i = 0; i < arr.length; i++ ) { 47 arr[ i ] = rnorm(); 48 } 49 50 var out = ztest( arr, 2.0 ); 51 /* e.g., returns 52 { 53 'rejected': false, 54 'pValue': ~0.155, 55 'statistic': -1.422, 56 'ci': [~-0.391,~0.062], 57 // ... 58 } 59 */ 60 ``` 61 62 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. 63 64 <!-- run-disable --> 65 66 ```javascript 67 var table = out.print({ 68 'digits': 3 69 }); 70 console.log( table ); 71 /* e.g., => 72 One-sample z-test 73 74 Alternative hypothesis: True mean is not equal to 0 75 76 pValue: 0.155 77 statistic: -1.422 78 95% confidence interval: [-0.391,0.062] 79 80 Test Decision: Fail to reject null in favor of alternative at 5% significance level 81 */ 82 ``` 83 84 The `ztest` function accepts the following `options`: 85 86 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 87 - **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`. 88 - **mu**: `number` denoting the hypothesized true mean under the null hypothesis. Default: `0`. 89 90 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. 91 92 ```javascript 93 var table; 94 var out; 95 var arr; 96 97 arr = [ 2, 4, 3, 1, 0 ]; 98 99 out = ztest( arr, 2.0, { 100 'alpha': 0.01 101 }); 102 table = out.print(); 103 /* e.g., returns 104 One-sample z-test 105 106 Alternative hypothesis: True mean is not equal to 0 107 108 pValue: 0.0253 109 statistic: 2.2361 110 99% confidence interval: [-0.3039,4.3039] 111 112 Test Decision: Fail to reject null in favor of alternative at 1% significance level 113 */ 114 115 out = ztest( arr, 2.0, { 116 'alpha': 0.1 117 }); 118 table = out.print(); 119 /* e.g., returns 120 One-sample z-test 121 122 Alternative hypothesis: True mean is not equal to 0 123 124 pValue: 0.0253 125 statistic: 2.2361 126 90% confidence interval: [0.5288,3.4712] 127 128 Test Decision: Reject null in favor of alternative at 10% significance level 129 */ 130 ``` 131 132 To test whether the data comes from a distribution with a mean different than zero, set the `mu` option. 133 134 ```javascript 135 var out; 136 var arr; 137 138 arr = [ 4, 4, 6, 6, 5 ]; 139 140 out = ztest( arr, 1.0, { 141 'mu': 5.0 142 }); 143 /* e.g., returns 144 { 145 'rejected': false, 146 'pValue': 1, 147 'statistic': 0, 148 'ci': [ ~4.123, ~5.877 ], 149 // ... 150 } 151 */ 152 ``` 153 154 By default, a two-sided test is performed. To perform either of the one-sided tests, set the `alternative` option to `less` or `greater`. 155 156 ```javascript 157 var table; 158 var out; 159 var arr; 160 161 arr = [ 4, 4, 6, 6, 5 ]; 162 163 out = ztest( arr, 1.0, { 164 'alternative': 'less' 165 }); 166 table = out.print(); 167 /* e.g., returns 168 One-sample z-test 169 170 Alternative hypothesis: True mean is less than 0 171 172 pValue: 1 173 statistic: 11.1803 174 95% confidence interval: [-Infinity,5.7356] 175 176 Test Decision: Fail to reject null in favor of alternative at 5% significance level 177 */ 178 179 out = ztest( arr, 1.0, { 180 'alternative': 'greater' 181 }); 182 table = out.print(); 183 /* e.g., returns 184 One-sample z-test 185 186 Alternative hypothesis: True mean is greater than 0 187 188 pValue: 0 189 statistic: 11.1803 190 95% confidence interval: [4.2644,Infinity] 191 192 Test Decision: Reject null in favor of alternative at 5% significance level 193 */ 194 ``` 195 196 </section> 197 198 <!-- /.usage --> 199 200 <section class="examples"> 201 202 ## Examples 203 204 <!-- eslint no-undef: "error" --> 205 206 ```javascript 207 var normal = require( '@stdlib/random/base/normal' ).factory; 208 var ztest = require( '@stdlib/stats/ztest' ); 209 210 var rnorm; 211 var arr; 212 var out; 213 var i; 214 215 rnorm = normal( 5.0, 4.0, { 216 'seed': 37827 217 }); 218 arr = new Array( 500 ); 219 for ( i = 0; i < arr.length; i++ ) { 220 arr[ i ] = rnorm(); 221 } 222 223 // Test whether true mean is equal to zero: 224 out = ztest( arr, 4.0 ); 225 console.log( out.print() ); 226 /* e.g., => 227 One-sample z-test 228 229 Alternative hypothesis: True mean is not equal to 0 230 231 pValue: 0 232 statistic: 28.6754 233 95% confidence interval: [4.779,5.4802] 234 235 Test Decision: Reject null in favor of alternative at 5% significance level 236 */ 237 238 // Test whether true mean is equal to five: 239 out = ztest( arr, 4.0, { 240 'mu': 5.0 241 }); 242 console.log( out.print() ); 243 /* e.g., => 244 One-sample z-test 245 246 Alternative hypothesis: True mean is not equal to 5 247 248 pValue: 0.4688 249 statistic: 0.7245 250 95% confidence interval: [4.779,5.4802] 251 252 Test Decision: Fail to reject null in favor of alternative at 5% significance level 253 */ 254 ``` 255 256 </section> 257 258 <!-- /.examples --> 259 260 <section class="links"> 261 262 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 263 264 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 265 266 </section> 267 268 <!-- /.links -->