README.md (10074B)
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 # Hypergeometric Random Numbers 22 23 > [Hypergeometric][hypergeometric] distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var hypergeometric = require( '@stdlib/random/base/hypergeometric' ); 31 ``` 32 33 #### hypergeometric( N, K, n ) 34 35 Returns a pseudorandom number drawn from a [hypergeometric][hypergeometric] distribution with parameters `N` (population size), `K` (subpopulation size), and `n` (number of draws). 36 37 ```javascript 38 var r = hypergeometric( 20, 10, 7 ); 39 // returns <number> 40 ``` 41 42 `N`, `K`, and `n` must all be nonnegative integers; otherwise, the function returns `NaN`. 43 44 ```javascript 45 var r = hypergeometric( 10.5, 10, 10 ); 46 // returns NaN 47 48 r = hypergeometric( 10, 4.4, 2 ); 49 // returns NaN 50 51 r = hypergeometric( 10, 5, -1 ); 52 // returns NaN 53 54 r = hypergeometric( NaN, NaN, NaN ); 55 // returns NaN 56 ``` 57 58 If `n > N` or `K > N`, the function returns `NaN`. 59 60 ```javascript 61 var r = hypergeometric( 7, 5, 12 ); 62 // returns NaN 63 ``` 64 65 #### hypergeometric.factory( \[N, K, n, ]\[options] ) 66 67 Returns a pseudorandom number generator (PRNG) for generating pseudorandom numbers drawn from a [hypergeometric][hypergeometric] distribution. 68 69 ```javascript 70 var rand = hypergeometric.factory(); 71 72 var r = rand( 20, 10, 15 ); 73 // returns <number> 74 ``` 75 76 If provided `N`, `K`, and `n`, the returned generator returns random variates from the specified distribution. 77 78 ```javascript 79 var rand = hypergeometric.factory( 20, 10, 15 ); 80 81 var r = rand(); 82 // returns <number> 83 84 r = rand(); 85 // returns <number> 86 ``` 87 88 If not provided `N`, `K`, and `n`, the returned generator requires that all three parameters be specified at each invocation. 89 90 ```javascript 91 var rand = hypergeometric.factory(); 92 93 var r = rand( 10, 7, 3 ); 94 // returns <number> 95 96 r = rand( 104, 48, 21 ); 97 // returns <number> 98 ``` 99 100 The function accepts the following `options`: 101 102 - **prng**: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval `[0,1)`. If provided, the function **ignores** both the `state` and `seed` options. In order to seed the returned pseudorandom number generator, one must seed the provided `prng` (assuming the provided `prng` is seedable). 103 - **seed**: pseudorandom number generator seed. 104 - **state**: a [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option. 105 - **copy**: `boolean` indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that a returned generator has exclusive control over its internal state. Default: `true`. 106 107 To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option. 108 109 ```javascript 110 var minstd = require( '@stdlib/random/base/minstd' ); 111 112 var rand = hypergeometric.factory({ 113 'prng': minstd.normalized 114 }); 115 116 var r = rand( 10, 8, 5 ); 117 // returns <number> 118 ``` 119 120 To seed a pseudorandom number generator, set the `seed` option. 121 122 ```javascript 123 var rand1 = hypergeometric.factory({ 124 'seed': 12345 125 }); 126 127 var r1 = rand1( 10, 8, 5 ); 128 // returns <number> 129 130 var rand2 = hypergeometric.factory( 10, 8, 5, { 131 'seed': 12345 132 }); 133 134 var r2 = rand2(); 135 // returns <number> 136 137 var bool = ( r1 === r2 ); 138 // returns true 139 ``` 140 141 To return a generator having a specific initial state, set the generator `state` option. 142 143 ```javascript 144 var rand; 145 var bool; 146 var r; 147 var i; 148 149 // Generate pseudorandom numbers, thus progressing the generator state: 150 for ( i = 0; i < 1000; i++ ) { 151 r = hypergeometric( 10, 8, 5 ); 152 } 153 154 // Create a new PRNG initialized to the current state of `hypergeometric`: 155 rand = hypergeometric.factory({ 156 'state': hypergeometric.state 157 }); 158 159 // Test that the generated pseudorandom numbers are the same: 160 bool = ( rand( 10, 8, 5 ) === hypergeometric( 10, 8, 5 ) ); 161 // returns true 162 ``` 163 164 #### hypergeometric.NAME 165 166 The generator name. 167 168 ```javascript 169 var str = hypergeometric.NAME; 170 // returns 'hypergeometric' 171 ``` 172 173 #### hypergeometric.PRNG 174 175 The underlying pseudorandom number generator. 176 177 ```javascript 178 var prng = hypergeometric.PRNG; 179 // returns <Function> 180 ``` 181 182 #### hypergeometric.seed 183 184 The value used to seed `hypergeometric()`. 185 186 ```javascript 187 var rand; 188 var r; 189 var i; 190 191 // Generate pseudorandom values... 192 for ( i = 0; i < 100; i++ ) { 193 r = hypergeometric( 20, 10, 15 ); 194 } 195 196 // Generate the same pseudorandom values... 197 rand = hypergeometric.factory( 20, 10, 15, { 198 'seed': hypergeometric.seed 199 }); 200 for ( i = 0; i < 100; i++ ) { 201 r = rand(); 202 } 203 ``` 204 205 If provided a PRNG for uniformly distributed numbers, this value is `null`. 206 207 <!-- eslint-disable stdlib/no-builtin-math --> 208 209 ```javascript 210 var rand = hypergeometric.factory({ 211 'prng': Math.random 212 }); 213 214 var seed = rand.seed; 215 // returns null 216 ``` 217 218 #### hypergeometric.seedLength 219 220 Length of generator seed. 221 222 ```javascript 223 var len = hypergeometric.seedLength; 224 // returns <number> 225 ``` 226 227 If provided a PRNG for uniformly distributed numbers, this value is `null`. 228 229 <!-- eslint-disable stdlib/no-builtin-math --> 230 231 ```javascript 232 var rand = hypergeometric.factory({ 233 'prng': Math.random 234 }); 235 236 var len = rand.seedLength; 237 // returns null 238 ``` 239 240 #### hypergeometric.state 241 242 Writable property for getting and setting the generator state. 243 244 ```javascript 245 var r = hypergeometric( 10, 8, 5 ); 246 // returns <number> 247 248 r = hypergeometric( 10, 8, 5 ); 249 // returns <number> 250 251 // ... 252 253 // Get a copy of the current state: 254 var state = hypergeometric.state; 255 // returns <Uint32Array> 256 257 r = hypergeometric( 10, 8, 5 ); 258 // returns <number> 259 260 r = hypergeometric( 10, 8, 5 ); 261 // returns <number> 262 263 // Reset the state: 264 hypergeometric.state = state; 265 266 // Replay the last two pseudorandom numbers: 267 r = hypergeometric( 10, 8, 5 ); 268 // returns <number> 269 270 r = hypergeometric( 10, 8, 5 ); 271 // returns <number> 272 273 // ... 274 ``` 275 276 If provided a PRNG for uniformly distributed numbers, this value is `null`. 277 278 <!-- eslint-disable stdlib/no-builtin-math --> 279 280 ```javascript 281 var rand = hypergeometric.factory({ 282 'prng': Math.random 283 }); 284 285 var state = rand.state; 286 // returns null 287 ``` 288 289 #### hypergeometric.stateLength 290 291 Length of generator state. 292 293 ```javascript 294 var len = hypergeometric.stateLength; 295 // returns <number> 296 ``` 297 298 If provided a PRNG for uniformly distributed numbers, this value is `null`. 299 300 <!-- eslint-disable stdlib/no-builtin-math --> 301 302 ```javascript 303 var rand = hypergeometric.factory({ 304 'prng': Math.random 305 }); 306 307 var len = rand.stateLength; 308 // returns null 309 ``` 310 311 #### hypergeometric.byteLength 312 313 Size (in bytes) of generator state. 314 315 ```javascript 316 var sz = hypergeometric.byteLength; 317 // returns <number> 318 ``` 319 320 If provided a PRNG for uniformly distributed numbers, this value is `null`. 321 322 <!-- eslint-disable stdlib/no-builtin-math --> 323 324 ```javascript 325 var rand = hypergeometric.factory({ 326 'prng': Math.random 327 }); 328 329 var sz = rand.byteLength; 330 // returns null 331 ``` 332 333 #### hypergeometric.toJSON() 334 335 Serializes the pseudorandom number generator as a JSON object. 336 337 ```javascript 338 var o = hypergeometric.toJSON(); 339 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 340 ``` 341 342 If provided a PRNG for uniformly distributed numbers, this method returns `null`. 343 344 <!-- eslint-disable stdlib/no-builtin-math --> 345 346 ```javascript 347 var rand = hypergeometric.factory({ 348 'prng': Math.random 349 }); 350 351 var o = rand.toJSON(); 352 // returns null 353 ``` 354 355 </section> 356 357 <!-- /.usage --> 358 359 <section class="notes"> 360 361 ## Notes 362 363 - If PRNG state is "shared" (meaning a state array was provided during PRNG creation and **not** copied) and one sets the generator state to a state array having a different length, the PRNG does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for **each** relevant PRNG must be **explicitly** set. 364 - If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array). 365 366 </section> 367 368 <!-- /.notes --> 369 370 <section class="examples"> 371 372 ## Examples 373 374 <!-- eslint no-undef: "error" --> 375 376 ```javascript 377 var hypergeometric = require( '@stdlib/random/base/hypergeometric' ); 378 379 var seed; 380 var rand; 381 var i; 382 383 // Generate pseudorandom numbers... 384 for ( i = 0; i < 100; i++ ) { 385 console.log( hypergeometric( 10, 10, 10 ) ); 386 } 387 388 // Create a new pseudorandom number generator... 389 seed = 1234; 390 rand = hypergeometric.factory( 5, 3, 2, { 391 'seed': seed 392 }); 393 for ( i = 0; i < 100; i++ ) { 394 console.log( rand() ); 395 } 396 397 // Create another pseudorandom number generator using a previous seed... 398 rand = hypergeometric.factory( 10, 10, 10, { 399 'seed': hypergeometric.seed 400 }); 401 for ( i = 0; i < 100; i++ ) { 402 console.log( rand() ); 403 } 404 ``` 405 406 </section> 407 408 <!-- /.examples --> 409 410 * * * 411 412 <section class="references"> 413 414 ## References 415 416 - Kachitvichyanukul, Voratas., and Burce Schmeiser. 1985. "Computer generation of hypergeometric random variates." _Journal of Statistical Computation and Simulation_ 22 (2): 127–45. doi:[10.1080/00949658508810839][@kachitvichyanukul:1985]. 417 418 </section> 419 420 <!-- /.references --> 421 422 <section class="links"> 423 424 [hypergeometric]: https://en.wikipedia.org/wiki/Hypergeometric_distribution 425 426 [@kachitvichyanukul:1985]: http://dx.doi.org/10.1080/00949658508810839 427 428 [@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32 429 430 </section> 431 432 <!-- /.links -->