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