README.md (6185B)
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 > Two-sample z-Test. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var ztest2 = require( '@stdlib/stats/ztest2' ); 31 ``` 32 33 #### ztest2( x, y, sigmax, sigmay\[, opts] ) 34 35 By default, the function performs a two-sample z-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 and known standard deviations `sigmax` and `sigmay`. 36 37 ```javascript 38 var x = [ 2.66, 1.5, 3.25, 0.993, 2.31, 2.41, 1.76, 2.57, 2.62, 1.23 ]; // Drawn from N(2,1) 39 var y = [ 4.88, 2.93, 2.96, 4.5, -0.0603, 4.62, 3.35, 2.98 ]; // Drawn from N(3,2) 40 41 var out = ztest2( x, y, 1.0, 2.0 ); 42 /* e.g., returns 43 { 44 'rejected': false, 45 'pValue': ~0.141, 46 'statistic': ~-1.471, 47 'ci': [ ~-2.658, ~0.379 ], 48 // ... 49 } 50 */ 51 ``` 52 53 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. 54 55 <!-- run-disable --> 56 57 ```javascript 58 console.log( out.print() ); 59 /* e.g., => 60 Two-sample z-test 61 62 Alternative hypothesis: True difference in means is not equal to 0 63 64 pValue: 0.1412 65 statistic: -1.4713 66 95% confidence interval: [-2.6578,0.3785] 67 68 Test Decision: Fail to reject null in favor of alternative at 5% significance level 69 */ 70 ``` 71 72 The function accepts the following `options`: 73 74 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 75 - **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`. 76 - **difference**: `number` denoting the difference in means under the null hypothesis. Default: `0`. 77 78 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. 79 80 <!-- run-disable --> 81 82 ```javascript 83 var out = ztest2( x, y, 1.0, 2.0, { 84 'alpha': 0.2 85 }); 86 var table = out.print(); 87 /* e.g., returns 88 Two-sample z-test 89 90 Alternative hypothesis: True difference in means is not equal to 0 91 92 pValue: 0.1412 93 statistic: -1.4713 94 80% confidence interval: [-2.1323,-0.147] 95 96 Test Decision: Reject null in favor of alternative at 20% significance level 97 */ 98 ``` 99 100 By default, a two-sided test is performed. To perform either of the one-sided tests, set the `alternative` option to `less` or `greater`. 101 102 <!-- run-disable --> 103 104 ```javascript 105 var out = ztest2( x, y, { 106 'alternative': 'less' 107 }); 108 var table = out.print(); 109 /* e.g., returns 110 Two-sample z-test 111 112 Alternative hypothesis: True difference in means is less than 0 113 114 pValue: 0.0706 115 statistic: -1.4713 116 95% confidence interval: [-Infinity,0.1344] 117 118 Test Decision: Fail to reject null in favor of alternative at 5% significance level 119 */ 120 121 out = ztest2( x, y, { 122 'alternative': 'greater' 123 }); 124 table = out.print(); 125 /* e.g., returns 126 Two-sample z-test 127 128 Alternative hypothesis: True difference in means is greater than 0 129 130 pValue: 0.9294 131 statistic: -1.4713 132 95% confidence interval: [-2.4138,Infinity] 133 134 Test Decision: Fail to reject null in favor of alternative at 5% significance level 135 */ 136 ``` 137 138 To test whether the difference in the population means is equal to some other value than `0`, set the `difference` option. 139 140 ```javascript 141 var normal = require( '@stdlib/random/base/normal' ).factory; 142 143 var rnorm = normal({ 144 'seed': 372 145 }); 146 147 var x = new Array( 100 ); 148 var i; 149 for ( i = 0; i < x.length; i++ ) { 150 x[ i ] = rnorm( 2.0, 1.0 ); 151 } 152 var y = new Array( 100 ); 153 for ( i = 0; i < x.length; i++ ) { 154 y[ i ] = rnorm( 1.0, 1.0 ); 155 } 156 157 var out = ztest2( x, y, 1.0, 1.0, { 158 'difference': 1.0 159 }); 160 /* e.g., returns 161 { 162 'rejected': false, 163 'pValue': ~0.74, 164 'statistic': ~0.332, 165 'ci': [ ~0.77, ~1.324 ], 166 // ... 167 } 168 */ 169 170 var table = out.print(); 171 /* e.g., returns 172 Two-sample z-test 173 174 Alternative hypothesis: True difference in means is not equal to 1 175 176 pValue: 0.7395 177 statistic: 0.3325 178 95% confidence interval: [0.7698,1.3242] 179 180 Test Decision: Fail to reject null in favor of alternative at 5% significance level 181 */ 182 ``` 183 184 </section> 185 186 <!-- /.usage --> 187 188 <section class="examples"> 189 190 ## Examples 191 192 <!-- eslint no-undef: "error" --> 193 194 ```javascript 195 var rnorm = require( '@stdlib/random/base/normal' ); 196 var ztest2 = require( '@stdlib/stats/ztest2' ); 197 198 var table; 199 var out; 200 var x; 201 var y; 202 var i; 203 204 // Values drawn from a Normal(4,2) distribution 205 x = new Array( 100 ); 206 for ( i = 0; i < 100; i++ ) { 207 x[ i ] = rnorm( 4.0, 2.0 ); 208 } 209 // Values drawn from a Normal(3,2) distribution 210 y = new Array( 80 ); 211 for ( i = 0; i < 80; i++ ) { 212 y[ i ] = rnorm( 3.0, 2.0 ); 213 } 214 215 out = ztest2( x, y, 2.0, 2.0 ); 216 table = out.print(); 217 console.log( table ); 218 219 out = ztest2( x, y, 2.0, 2.0, { 220 'difference': 1.0 221 }); 222 table = out.print(); 223 console.log( table ); 224 ``` 225 226 </section> 227 228 <!-- /.examples --> 229 230 <section class="links"> 231 232 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 233 234 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 235 236 </section> 237 238 <!-- /.links -->