README.md (4401B)
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 # Cumulative Distribution Function 22 23 > [Gamma][gamma-distribution] distribution [cumulative distribution function][cdf]. 24 25 <section class="intro"> 26 27 The [cumulative distribution function][cdf] for a [gamma][gamma-distribution] random variable is 28 29 <!-- <equation class="equation" label="eq:gamma_cdf" align="center" raw="F(x;\alpha,\beta) = \int_0^x f(u;\alpha,\beta)\,du= \frac{\gamma(\alpha, \beta x)}{\Gamma(\alpha)}" alt="Cumulative distribution function for a Gamma distribution."> --> 30 31 <div class="equation" align="center" data-raw-text="F(x;\alpha,\beta) = \int_0^x f(u;\alpha,\beta)\,du= \frac{\gamma(\alpha, \beta x)}{\Gamma(\alpha)}" data-equation="eq:gamma_cdf"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/gamma/cdf/docs/img/equation_gamma_cdf.svg" alt="Cumulative distribution function for a Gamma distribution."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `alpha` is the shape parameter and `beta` is the rate parameter of the distribution. `gamma` is the lower [incomplete gamma function][@stdlib/math/base/special/gammainc]. 39 40 </section> 41 42 <!-- /.intro --> 43 44 <section class="usage"> 45 46 ## Usage 47 48 ```javascript 49 var cdf = require( '@stdlib/stats/base/dists/gamma/cdf' ); 50 ``` 51 52 #### cdf( x, alpha, beta ) 53 54 Evaluates the [cumulative distribution function][cdf] (CDF) for a [gamma][gamma-distribution] distribution with parameters `alpha` (shape parameter) and `beta` (rate parameter). 55 56 ```javascript 57 var y = cdf( 2.0, 1.0, 1.0 ); 58 // returns ~0.865 59 60 y = cdf( 2.0, 3.0, 1.0 ); 61 // returns ~0.323 62 63 y = cdf( -1.0, 2.0, 2.0 ); 64 // returns 0.0 65 66 y = cdf( -Infinity, 4.0, 2.0 ); 67 // returns 0.0 68 69 y = cdf( +Infinity, 4.0, 2.0 ); 70 // returns 1.0 71 ``` 72 73 If provided `NaN` as any argument, the function returns `NaN`. 74 75 ```javascript 76 var y = cdf( NaN, 1.0, 1.0 ); 77 // returns NaN 78 79 y = cdf( 0.0, NaN, 1.0 ); 80 // returns NaN 81 82 y = cdf( 0.0, 1.0, NaN ); 83 // returns NaN 84 ``` 85 86 If provided `alpha < 0`, the function returns `NaN`. 87 88 ```javascript 89 var y = cdf( 2.0, -1.0, 0.5 ); 90 // returns NaN 91 ``` 92 93 If provided `alpha = 0`, the function evaluates the [CDF][cdf] of a [degenerate distribution][degenerate-distribution] centered at `0`. 94 95 ```javascript 96 var y = cdf( 2.0, 0.0, 2.0 ); 97 // returns 1.0 98 99 y = cdf( -2.0, 0.0, 2.0 ); 100 // returns 0.0 101 102 y = cdf( 0.0, 0.0, 2.0 ); 103 // returns 1.0 104 ``` 105 106 If provided `beta <= 0`, the function returns `NaN`. 107 108 ```javascript 109 var y = cdf( 2.0, 0.5, -1.0 ); 110 // returns NaN 111 ``` 112 113 #### cdf.factory( alpha, beta ) 114 115 Returns a function for evaluating the [cumulative distribution function][cdf] for a [gamma][gamma-distribution] distribution with parameters `alpha` (shape parameter) and `beta` (rate parameter). 116 117 ```javascript 118 var mycdf = cdf.factory( 0.5, 0.1 ); 119 120 var y = mycdf( 12.0 ); 121 // returns ~0.879 122 123 y = mycdf( 8.0 ); 124 // returns ~0.794 125 ``` 126 127 </section> 128 129 <!-- /.usage --> 130 131 <section class="examples"> 132 133 ## Examples 134 135 <!-- eslint no-undef: "error" --> 136 137 ```javascript 138 var randu = require( '@stdlib/random/base/randu' ); 139 var cdf = require( '@stdlib/stats/base/dists/gamma/cdf' ); 140 141 var alpha; 142 var beta; 143 var x; 144 var y; 145 var i; 146 147 for ( i = 0; i < 10; i++ ) { 148 x = randu() * 3.0; 149 alpha = randu() * 5.0; 150 beta = randu() * 5.0; 151 y = cdf( x, alpha, beta ); 152 console.log( 'x: %d, α: %d, β: %d, F(x;α,β): %d', x.toFixed( 4 ), alpha.toFixed( 4 ), beta.toFixed( 4 ), y.toFixed( 4 ) ); 153 } 154 ``` 155 156 </section> 157 158 <!-- /.examples --> 159 160 <section class="links"> 161 162 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function 163 164 [degenerate-distribution]: https://en.wikipedia.org/wiki/Degenerate_distribution 165 166 [gamma-distribution]: https://en.wikipedia.org/wiki/Gamma_distribution 167 168 [@stdlib/math/base/special/gammainc]: https://www.npmjs.com/package/@stdlib/math-base-special-gammainc 169 170 </section> 171 172 <!-- /.links -->