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