README.md (9783B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 # Wilcoxon Signed Rank Test 22 23 > One-sample and paired Wilcoxon signed rank test. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var wilcoxon = require( '@stdlib/stats/wilcoxon' ); 31 ``` 32 33 #### wilcoxon( x\[, y]\[, opts] ) 34 35 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 distribution that is symmetric around zero (i.e., with median zero). 36 37 ```javascript 38 // Differences in plant heights, see Cureton (1967) 39 var x = [ 6, 8, 14, 16, 23, 24, 28, 29, 41, -48, 49, 56, 60, -67, 75 ]; 40 var out = wilcoxon( x ); 41 /* e.g., returns 42 { 43 'rejected': true, 44 'alpha': 0.05, 45 'pValue': 0.04125976562499978, 46 'statistic': 96, 47 // ... 48 } 49 */ 50 ``` 51 52 When [array][mdn-array] or [typed array][mdn-typed-array] `y` is supplied, the function tests whether the paired differences `x - y` come from a distribution that is symmetric around zero (i.e., with median zero). 53 54 ```javascript 55 // Patient measurements at first (x) and second (y) visit, see Hollander & Wolfe (1973) 56 var x = [ 1.83, 0.50, 1.62, 2.48, 1.68, 1.88, 1.55, 3.06, 1.30 ]; 57 var y = [ 0.878, 0.647, 0.598, 2.05, 1.06, 1.29, 1.06, 3.14, 1.29 ]; 58 59 var out = wilcoxon( x, y ); 60 /* e.g., returns 61 { 62 'rejected': true, 63 'alpha': 0.05, 64 'pValue': 0.0390625, 65 'statistic': 40, 66 // ... 67 } 68 */ 69 ``` 70 71 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. 72 73 <!-- run-disable --> 74 75 ```javascript 76 console.log( out.print() ); 77 /* e.g., => 78 Paired Wilcoxon signed rank test 79 80 Alternative hypothesis: Median of the difference `x - y` is not equal to 0 81 82 pValue: 0.0391 83 statistic: 40 84 85 Test Decision: Reject null in favor of alternative at 5% significance level 86 */ 87 ``` 88 89 The `wilcoxon` function accepts the following `options`: 90 91 - **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`. 92 - **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`. 93 - **correction**: continuity correction adjusting the Wilcoxon rank statistic by 0.5 towards the mean when using the normal approximation. Default: `true`. 94 - **exact**: Determines whether to force use of the exact distribution instead of a normal approximation when there are more than fifty data points. Default: `false`. 95 - **mu**: `number` denoting the hypothesized median under the null hypothesis. Default: `0`. 96 - **zeroMethod**: Method governing how zero-differences are handled (`pratt`, `wilcox`, or `zsplit`). Default: `'wilcox'`. 97 98 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. 99 100 ```javascript 101 var table; 102 var out; 103 var arr; 104 105 arr = [ 2, 4, 3, 1, 0 ]; 106 out = wilcoxon( arr, { 107 'alpha': 0.01 108 }); 109 table = out.print(); 110 /* e.g., returns 111 One-Sample Wilcoxon signed rank test 112 113 Alternative hypothesis: Median of `x` is not equal to 0 114 115 pValue: 0.035 116 statistic: 21 117 118 Test Decision: Reject null in favor of alternative at 5% significance level 119 */ 120 121 out = wilcoxon( arr, { 122 'alpha': 0.1 123 }); 124 table = out.print(); 125 /* e.g., returns 126 One-Sample Wilcoxon signed rank test 127 128 Alternative hypothesis: Median of `x` is not equal to 0 129 130 pValue: 0.035 131 statistic: 21 132 133 Test Decision: Fail to reject null in favor of alternative at 1% significance level 134 */ 135 ``` 136 137 To test whether the data comes from a distribution with a median different than zero, set the `mu` option. 138 139 ```javascript 140 var arr = [ 4, 4, 6, 6, 5 ]; 141 var out = wilcoxon( arr, { 142 'mu': 5 143 }); 144 /* e.g., returns 145 { 146 'rejected': false, 147 'pValue': 1, 148 'statistic': 0, 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 arr = [ 4, 4, 6, 6, 5 ]; 158 var out = wilcoxon( arr, { 159 'alternative': 'less' 160 }); 161 var table = out.print(); 162 /* e.g., returns 163 One-Sample Wilcoxon signed rank test 164 165 Alternative hypothesis: Median of `x` is less than 0 166 167 pValue: 0.9853 168 statistic: 15 169 170 Test Decision: Fail to reject null in favor of alternative at 5% significance level 171 */ 172 173 out = wilcoxon( arr, { 174 'alternative': 'greater' 175 }); 176 table = out.print(); 177 /* e.g., returns 178 One-Sample Wilcoxon signed rank test 179 180 Alternative hypothesis: Median of `x` is greater than 0 181 182 pValue: 0.0284 183 statistic: 15 184 185 Test Decision: Reject null in favor of alternative at 5% significance level 186 */ 187 ``` 188 189 By default, all zero-differences are discarded before calculating the ranks. Set `zeroMethod` to `pratt` when you wish differences of zero to be used in the rank calculation but then drop them or to `zsplit` when differences of zero are shall be used in the ranking procedure and the ranks then split between positive and negative ones. 190 191 ```javascript 192 var arr = [ 0, 2, 3, -1, -4, 0, 0, 8, 9 ]; 193 var out = wilcoxon( arr, { 194 'zeroMethod': 'pratt' 195 }); 196 /* e.g., returns 197 { 198 'rejected': false, 199 'alpha': 0.05, 200 'pValue': ~0.331, 201 'statistic': 28, 202 // ... 203 } 204 */ 205 206 out = wilcoxon( arr, { 207 'zeroMethod': 'zsplit' 208 }); 209 /* e.g., returns 210 { 211 'rejected': false, 212 'alpha': 0.05, 213 'pValue': ~0.342, 214 'statistic': 31, 215 // ... 216 } 217 */ 218 ``` 219 220 By default, the test uses the exact distribution of the rank statistic to calculate the critical values for the test in case of no ties and no zero-differences. Since it is more computationally efficient, starting with fifty observations a normal approximation is employed. If you would like the test to use the correct distribution even for larger samples, set the `exact` option to `true`. 221 222 ```javascript 223 var normal = require( '@stdlib/random/base/normal' ).factory; 224 var rnorm; 225 var arr; 226 var out; 227 var i; 228 229 rnorm = normal( 0.0, 4.0, { 230 'seed': 100 231 }); 232 arr = new Array( 100 ); 233 for ( i = 0; i < arr.length; i++ ) { 234 arr[ i ] = rnorm(); 235 } 236 237 out = wilcoxon( arr, { 238 'exact': false 239 }); 240 /* e.g., returns 241 { 242 'rejected': false, 243 'alpha': 0.05, 244 'pValue': ~0.422, 245 'statistic': 2291, 246 // ... 247 } 248 */ 249 250 out = wilcoxon( arr, { 251 'exact': true 252 }); 253 /* e.g., returns 254 { 255 'rejected': false, 256 'alpha': 0.05, 257 'pValue': ~0.424, 258 'statistic': 2291, 259 // ... 260 } 261 */ 262 ``` 263 264 By default, when using the normal approximation, the test uses a continuity correction, which adjusts the Wilcoxon rank statistic by `0.5` towards the mean. To disable this correction, set `correction` to `false`. 265 266 ```javascript 267 var normal = require( '@stdlib/random/base/normal' ).factory; 268 var rnorm; 269 var arr; 270 var out; 271 var i; 272 273 rnorm = normal( 0.0, 4.0, { 274 'seed': 100 275 }); 276 arr = new Array( 100 ); 277 for ( i = 0; i < arr.length; i++ ) { 278 arr[ i ] = rnorm(); 279 } 280 281 out = wilcoxon( arr, { 282 'correction': false 283 }); 284 /* e.g., returns 285 { 286 'rejected': false, 287 'alpha': 0.05, 288 'pValue': ~0.421, 289 'statistic': 2291, 290 // ... 291 } 292 */ 293 294 out = wilcoxon( arr, { 295 'correction': true 296 }); 297 /* e.g., returns 298 { 299 'rejected': false, 300 'alpha': 0.05, 301 'pValue': ~0.422, 302 'statistic': 2291, 303 // ... 304 } 305 */ 306 ``` 307 308 </section> 309 310 <!-- /.usage --> 311 312 <section class="examples"> 313 314 ## Examples 315 316 <!-- eslint no-undef: "error" --> 317 318 ```javascript 319 var uniform = require( '@stdlib/random/base/discrete-uniform' ).factory; 320 var wilcoxon = require( '@stdlib/stats/wilcoxon' ); 321 322 var table; 323 var runif; 324 var arr; 325 var out; 326 var i; 327 328 runif = uniform( -50.0, 50.0, { 329 'seed': 37827 330 }); 331 arr = new Array( 100 ); 332 for ( i = 0; i < arr.length; i++ ) { 333 arr[ i ] = runif(); 334 } 335 336 // Test whether distribution is symmetric around zero: 337 out = wilcoxon( arr ); 338 table = out.print(); 339 /* e.g., returns 340 One-Sample Wilcoxon signed rank test 341 342 Alternative hypothesis: Median of `x` is not equal to 0 343 344 pValue: 0.7714 345 statistic: 2438.5 346 347 Test Decision: Fail to reject null in favor of alternative at 5% significance level 348 */ 349 350 // Test whether distribution has median of five: 351 out = wilcoxon( arr, { 352 'mu': 5.0 353 }); 354 table = out.print(); 355 /* e.g, returns 356 One-Sample Wilcoxon signed rank test 357 358 Alternative hypothesis: Median of `x` is not equal to 5 359 360 pValue: 0.0529 361 statistic: 1961.5 362 363 Test Decision: Fail to reject null in favor of alternative at 5% significance level 364 */ 365 ``` 366 367 </section> 368 369 <!-- /.examples --> 370 371 <section class="links"> 372 373 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 374 375 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 376 377 </section> 378 379 <!-- /.links -->