README.md (4979B)
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 # Moment-Generating Function 22 23 > [Discrete uniform][discrete-uniform-distribution] distribution moment-generating function (MGF). 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 The [moment-generating function][mgf] for a [discrete uniform][discrete-uniform-distribution] random variable is 30 31 <!-- <equation class="equation" label="eq:discrete_uniform_mgf" align="center" raw="M_X(t) := \mathbb{E}\!\left[e^{tX}\right]= \begin{cases} \frac{\mathrm{e}^{at}-\mathrm{e}^{t(b+1)}}{(b-a+1)(1-e^t)} & \text{for } t \neq 0 \\ 1 & \text{for } t = 0 \end{cases}" alt="Moment-generating function (MGF) for a discrete uniform distribution."> --> 32 33 <div class="equation" align="center" data-raw-text="M_X(t) := \mathbb{E}\!\left[e^{tX}\right]= \begin{cases} \frac{\mathrm{e}^{at}-\mathrm{e}^{t(b+1)}}{(b-a+1)(1-e^t)} & \text{for } t \neq 0 \\ 1 & \text{for } t = 0 \end{cases}" data-equation="eq:discrete_uniform_mgf"> 34 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/discrete-uniform/mgf/docs/img/equation_discrete_uniform_mgf.svg" alt="Moment-generating function (MGF) for a discrete uniform distribution."> 35 <br> 36 </div> 37 38 <!-- </equation> --> 39 40 where `a` is the minimum support and `b` is the maximum support. The parameters must satisfy `a <= b`. 41 42 </section> 43 44 <!-- /.intro --> 45 46 <!-- Package usage documentation. --> 47 48 <section class="usage"> 49 50 ## Usage 51 52 ```javascript 53 var mgf = require( '@stdlib/stats/base/dists/discrete-uniform/mgf' ); 54 ``` 55 56 #### mgf( t, a, b ) 57 58 Evaluates the [moment-generating function][mgf] (MGF) for a [discrete uniform][discrete-uniform-distribution] distribution with parameters `a` (minimum support) and `b` (maximum support). 59 60 ```javascript 61 var y = mgf( 2.0, 0, 4 ); 62 // returns ~689.475 63 64 y = mgf( -0.2, 0, 4 ); 65 // returns ~0.697 66 67 y = mgf( 2.0, 0, 1 ); 68 // returns ~4.195 69 ``` 70 71 If `a` or `b` is not an integer value, the function returns `NaN`. 72 73 ```javascript 74 var y = mgf( 0.2, 1, 5.5 ); 75 // returns NaN 76 ``` 77 78 If provided `a > b`, the function returns `NaN`. 79 80 ```javascript 81 var y = mgf( 0.5, 3, 2); 82 // returns NaN 83 ``` 84 85 If provided `NaN` for any parameter, the function returns `NaN`. 86 87 ```javascript 88 var y = mgf( NaN, 0, 1 ); 89 // returns NaN 90 91 y = mgf( 0.0, NaN, 1 ); 92 // returns NaN 93 94 y = mgf( 0.0, 0, NaN ); 95 // returns NaN 96 ``` 97 98 #### mgf.factory( a, b ) 99 100 Returns a function for evaluating the [moment-generating function][mgf] (MGF) of a [discrete uniform][discrete-uniform-distribution] distribution with parameters `a` (minimum support) and `b` (maximum support). 101 102 ```javascript 103 var mymgf = mgf.factory( 6, 7 ); 104 var y = mymgf( 0.1 ); 105 // returns ~1.918 106 107 y = mymgf( 1.1 ); 108 // returns ~1471.722 109 ``` 110 111 </section> 112 113 <!-- /.usage --> 114 115 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 116 117 <section class="notes"> 118 119 </section> 120 121 <!-- /.notes --> 122 123 <!-- Package usage examples. --> 124 125 <section class="examples"> 126 127 ## Examples 128 129 <!-- eslint no-undef: "error" --> 130 131 ```javascript 132 var randint = require( '@stdlib/random/base/discrete-uniform' ); 133 var randu = require( '@stdlib/random/base/randu' ); 134 var mgf = require( '@stdlib/stats/base/dists/discrete-uniform/mgf' ); 135 136 var randa = randint.factory( 0, 5 ); 137 var randb = randint.factory(); 138 var a; 139 var b; 140 var t; 141 var v; 142 var i; 143 144 for ( i = 0; i < 10; i++ ) { 145 t = randu(); 146 a = randa(); 147 b = randb( a, a+randa() ); 148 v = mgf( t, a, b ); 149 console.log( 't: %d, a: %d, b: %d, M_X(t;a,b): %d', t.toFixed( 4 ), a.toFixed( 4 ), b.toFixed( 4 ), v.toFixed( 4 ) ); 150 } 151 ``` 152 153 </section> 154 155 <!-- /.examples --> 156 157 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 158 159 <section class="references"> 160 161 </section> 162 163 <!-- /.references --> 164 165 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 166 167 <section class="links"> 168 169 [discrete-uniform-distribution]: https://en.wikipedia.org/wiki/Discrete_uniform_distribution 170 171 [mgf]: https://en.wikipedia.org/wiki/Moment-generating_function 172 173 </section> 174 175 <!-- /.links -->