README.md (4678B)
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 > [Gamma][gamma-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 [gamma][gamma-distribution] random variable is 30 31 <!-- <equation class="equation" label="eq:gamma_mgf_function" align="center" raw="M_X(t) := \mathbb{E}\!\left[e^{tX}\right] = \left( 1 - \frac{t}{\beta} \right)^{-\alpha}" alt="Moment-generating function (MGF) for a gamma distribution."> --> 32 33 <div class="equation" align="center" data-raw-text="M_X(t) := \mathbb{E}\!\left[e^{tX}\right] = \left( 1 - \frac{t}{\beta} \right)^{-\alpha}" data-equation="eq:gamma_mgf_function"> 34 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@591cf9d5c3a0cd3c1ceec961e5c49d73a68374cb/lib/node_modules/@stdlib/stats/base/dists/gamma/mgf/docs/img/equation_gamma_mgf_function.svg" alt="Moment-generating function (MGF) for a gamma distribution."> 35 <br> 36 </div> 37 38 <!-- </equation> --> 39 40 where `alpha` is the shape parameter and `beta` is the rate parameter. For `t >= beta`, the MGF is not defined. 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/gamma/mgf' ); 54 ``` 55 56 #### mgf( t, alpha, beta ) 57 58 Evaluates the [moment-generating function][mgf] (MGF) for a [gamma][gamma-distribution] distribution with parameters `alpha` (shape parameter) and `beta` (rate parameter). 59 60 ```javascript 61 var y = mgf( 0.5, 0.5, 1.0 ); 62 // returns ~1.414 63 64 y = mgf( 0.1, 1.0, 1.0 ); 65 // returns ~1.111 66 67 y = mgf( -1.0, 4.0, 2.0 ); 68 // returns ~0.198 69 ``` 70 71 If provided `NaN` as any argument, the function returns `NaN`. 72 73 ```javascript 74 var y = mgf( NaN, 1.0, 1.0 ); 75 // returns NaN 76 77 y = mgf( 0.0, NaN, 1.0 ); 78 // returns NaN 79 80 y = mgf( 0.0, 1.0, NaN ); 81 // returns NaN 82 ``` 83 84 If provided `t >= beta`, the function returns `NaN`. 85 86 ```javascript 87 var y = mgf( 2.0, 4.0, 1.0 ); 88 // returns NaN 89 ``` 90 91 If provided `alpha < 0`, the function returns `NaN`. 92 93 ```javascript 94 var y = mgf( 2.0, -0.5, 1.0 ); 95 // returns NaN 96 ``` 97 98 If provided `beta <= 0`, the function returns `NaN`. 99 100 ```javascript 101 var y = mgf( 2.0, 1.0, 0.0 ); 102 // returns NaN 103 104 y = mgf( 2.0, 1.0, -1.0 ); 105 // returns NaN 106 ``` 107 108 #### mgf.factory( alpha, beta ) 109 110 Return a function for evaluating the [MGF][mgf] of a [gamma][gamma-distribution] distribution with parameters `alpha` (shape parameter) and `beta` (rate parameter). 111 112 ```javascript 113 var mymgf = mgf.factory( 3.0, 1.5 ); 114 115 var y = mymgf( 1.0 ); 116 // returns ~27.0 117 118 y = mymgf( 0.5 ); 119 // returns ~3.375 120 ``` 121 122 </section> 123 124 <!-- /.usage --> 125 126 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 127 128 <section class="notes"> 129 130 </section> 131 132 <!-- /.notes --> 133 134 <!-- Package usage examples. --> 135 136 <section class="examples"> 137 138 ## Examples 139 140 <!-- eslint no-undef: "error" --> 141 142 ```javascript 143 var randu = require( '@stdlib/random/base/randu' ); 144 var mgf = require( '@stdlib/stats/base/dists/gamma/mgf' ); 145 146 var a; 147 var b; 148 var t; 149 var v; 150 var i; 151 152 for ( i = 0; i < 10; i++ ) { 153 t = randu(); 154 a = randu() * 5.0; 155 b = a + (randu() * 5.0); 156 v = mgf( t, a, b ); 157 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 ) ); 158 } 159 ``` 160 161 </section> 162 163 <!-- /.examples --> 164 165 <!-- 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. --> 166 167 <section class="references"> 168 169 </section> 170 171 <!-- /.references --> 172 173 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 174 175 <section class="links"> 176 177 [gamma-distribution]: https://en.wikipedia.org/wiki/Gamma_distribution 178 179 [mgf]: https://en.wikipedia.org/wiki/Moment-generating_function 180 181 </section> 182 183 <!-- /.links -->