README.md (9956B)
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 # Negative Binomial Random Numbers 22 23 > [Negative binomially][negative-binomial] distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var negativeBinomial = require( '@stdlib/random/base/negative-binomial' ); 31 ``` 32 33 #### negativeBinomial( r, p ) 34 35 Returns a pseudorandom number drawn from a [negative binomial][negative-binomial] distribution with parameters `r` (number of successes until experiment is stopped) and `p` (success probability). 36 37 ```javascript 38 var r = negativeBinomial( 20, 0.8 ); 39 // returns <number> 40 ``` 41 42 If `r` or `p` is `NaN`, the function returns `NaN`. 43 44 ```javascript 45 var r = negativeBinomial( NaN, 0.4 ); 46 // returns NaN 47 48 r = negativeBinomial( 20, NaN ); 49 // returns NaN 50 ``` 51 52 If `p` is not in the interval `(0,1)` (exclusive), the function returns `NaN`. 53 54 ```javascript 55 var r = negativeBinomial( 10, 1.1 ); 56 // returns NaN 57 58 r = negativeBinomial( 10, 1.0 ); 59 // returns NaN 60 61 r = negativeBinomial( 10, 0.0 ); 62 // returns NaN 63 ``` 64 65 #### negativeBinomial.factory( \[r, p, ]\[options] ) 66 67 Returns a pseudorandom number generator (PRNG) for generating pseudorandom numbers drawn from a [negative binomial][negative-binomial] distribution. 68 69 ```javascript 70 var rand = negativeBinomial.factory(); 71 72 var r = rand( 20, 0.3 ); 73 // returns <number> 74 ``` 75 76 If provided `r` and `p`, the returned generator returns random variates from the specified distribution. 77 78 ```javascript 79 var rand = negativeBinomial.factory( 10, 0.8 ); 80 81 var r = rand(); 82 // returns <number> 83 84 r = rand(); 85 // returns <number> 86 ``` 87 88 If not provided `r` and `p`, the returned generator requires that both parameters be provided at each invocation. 89 90 ```javascript 91 var rand = negativeBinomial.factory(); 92 93 var r = rand( 20, 0.8 ); 94 // returns <number> 95 96 r = rand( 123, 0.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 = negativeBinomial.factory({ 113 'prng': minstd.normalized 114 }); 115 116 var r = rand( 8, 0.9 ); 117 // returns <number> 118 ``` 119 120 To seed a pseudorandom number generator, set the `seed` option. 121 122 ```javascript 123 var rand1 = negativeBinomial.factory({ 124 'seed': 12345 125 }); 126 127 var r1 = rand1( 8, 0.9 ); 128 // returns <number> 129 130 var rand2 = negativeBinomial.factory( 8, 0.9, { 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 = negativeBinomial( 8, 0.9 ); 152 } 153 154 // Create a new PRNG initialized to the current state of `negativeBinomial`: 155 rand = negativeBinomial.factory({ 156 'state': negativeBinomial.state 157 }); 158 159 // Test that the generated pseudorandom numbers are the same: 160 bool = ( rand( 8, 0.9 ) === negativeBinomial( 8, 0.9 ) ); 161 // returns true 162 ``` 163 164 #### negativeBinomial.NAME 165 166 The generator name. 167 168 ```javascript 169 var str = negativeBinomial.NAME; 170 // returns 'negative-binomial' 171 ``` 172 173 #### negativeBinomial.PRNG 174 175 The underlying pseudorandom number generator. 176 177 ```javascript 178 var prng = negativeBinomial.PRNG; 179 // returns <Function> 180 ``` 181 182 #### negativeBinomial.seed 183 184 The value used to seed `negativeBinomial()`. 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 = negativeBinomial( 20, 0.5 ); 194 } 195 196 // Generate the same pseudorandom values... 197 rand = negativeBinomial.factory( 20, 0.5, { 198 'seed': negativeBinomial.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 = negativeBinomial.factory({ 211 'prng': Math.random 212 }); 213 214 var seed = rand.seed; 215 // returns null 216 ``` 217 218 #### negativeBinomial.seedLength 219 220 Length of generator seed. 221 222 ```javascript 223 var len = negativeBinomial.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 = negativeBinomial.factory({ 233 'prng': Math.random 234 }); 235 236 var len = rand.seedLength; 237 // returns null 238 ``` 239 240 #### negativeBinomial.state 241 242 Writable property for getting and setting the generator state. 243 244 ```javascript 245 var r = negativeBinomial( 20, 0.5 ); 246 // returns <number> 247 248 r = negativeBinomial( 20, 0.5 ); 249 // returns <number> 250 251 // ... 252 253 // Get a copy of the current state: 254 var state = negativeBinomial.state; 255 // returns <Uint32Array> 256 257 r = negativeBinomial( 20, 0.5 ); 258 // returns <number> 259 260 r = negativeBinomial( 20, 0.5 ); 261 // returns <number> 262 263 // Reset the state: 264 negativeBinomial.state = state; 265 266 // Replay the last two pseudorandom numbers: 267 r = negativeBinomial( 20, 0.5 ); 268 // returns <number> 269 270 r = negativeBinomial( 20, 0.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 = negativeBinomial.factory({ 282 'prng': Math.random 283 }); 284 285 var state = rand.state; 286 // returns null 287 ``` 288 289 #### negativeBinomial.stateLength 290 291 Length of generator state. 292 293 ```javascript 294 var len = negativeBinomial.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 = negativeBinomial.factory({ 304 'prng': Math.random 305 }); 306 307 var len = rand.stateLength; 308 // returns null 309 ``` 310 311 #### negativeBinomial.byteLength 312 313 Size (in bytes) of generator state. 314 315 ```javascript 316 var sz = negativeBinomial.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 = negativeBinomial.factory({ 326 'prng': Math.random 327 }); 328 329 var sz = rand.byteLength; 330 // returns null 331 ``` 332 333 #### negativeBinomial.toJSON() 334 335 Serializes the pseudorandom number generator as a JSON object. 336 337 ```javascript 338 var o = negativeBinomial.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 = negativeBinomial.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 - The `r` parameter is the shape parameter of the gamma mixing distribution when expressing the negative binomial distribution as a Gamma–Poisson mixture. Accordingly, `r` is **not** required to be an integer value. 364 - 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. 365 - 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). 366 367 </section> 368 369 <!-- /.notes --> 370 371 <section class="examples"> 372 373 ## Examples 374 375 <!-- eslint no-undef: "error" --> 376 377 ```javascript 378 var negativeBinomial = require( '@stdlib/random/base/negative-binomial' ); 379 380 var seed; 381 var rand; 382 var i; 383 384 // Generate pseudorandom numbers... 385 for ( i = 0; i < 100; i++ ) { 386 console.log( negativeBinomial( 10, 0.5 ) ); 387 } 388 389 // Create a new pseudorandom number generator... 390 seed = 1234; 391 rand = negativeBinomial.factory( 8, 0.8, { 392 'seed': seed 393 }); 394 for ( i = 0; i < 100; i++ ) { 395 console.log( rand() ); 396 } 397 398 // Create another pseudorandom number generator using a previous seed... 399 rand = negativeBinomial.factory( 10, 0.5, { 400 'seed': negativeBinomial.seed 401 }); 402 for ( i = 0; i < 100; i++ ) { 403 console.log( rand() ); 404 } 405 ``` 406 407 </section> 408 409 <!-- /.examples --> 410 411 <section class="links"> 412 413 [negative-binomial]: https://en.wikipedia.org/wiki/Negative_binomial_distribution 414 415 [@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32 416 417 </section> 418 419 <!-- /.links -->