README.md (4826B)
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 # Logarithm of Cumulative Distribution Function 22 23 > Evaluate the natural logarithm of the [cumulative distribution function][cdf] for a [beta prime][betaprime-distribution] distribution . 24 25 <section class="intro"> 26 27 The [cumulative distribution function][cdf] for a [beta prime][betaprime-distribution] random variable is 28 29 <!-- <equation class="equation" label="eq:betaprime_cdf" align="center" raw="F(x;\alpha,\beta) = \begin{cases} I_{\frac{x}{1+x}}(\alpha, \beta) & \text{ for } x > 0 \\ 0 & \text{ otherwise } \end{cases}" alt="Cumulative distribution function for a beta prime distribution."> --> 30 31 <div class="equation" align="center" data-raw-text="F(x;\alpha,\beta) = \begin{cases} I_{\frac{x}{1+x}}(\alpha, \beta) & \text{ for } x > 0 \\ 0 & \text{ otherwise } \end{cases}" data-equation="eq:betaprime_cdf"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/betaprime/logcdf/docs/img/equation_betaprime_cdf.svg" alt="Cumulative distribution function for a beta prime distribution."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `alpha > 0` is the first shape parameter, `beta > 0` is the second shape parameter and `I` is the [incomplete beta function][incomplete-beta]. 39 40 </section> 41 42 <!-- /.intro --> 43 44 <section class="usage"> 45 46 ## Usage 47 48 ```javascript 49 var logcdf = require( '@stdlib/stats/base/dists/betaprime/logcdf' ); 50 ``` 51 52 #### logcdf( x, alpha, beta ) 53 54 Evaluates the natural logarithm of the [cumulative distribution function][cdf] (CDF) for a [beta prime][betaprime-distribution] distribution with parameters `alpha` (first shape parameter) and `beta` (second shape parameter). 55 56 ```javascript 57 var y = logcdf( 0.5, 1.0, 1.0 ); 58 // returns ~-1.099 59 60 y = logcdf( 0.5, 2.0, 4.0 ); 61 // returns ~-0.618 62 63 y = logcdf( 0.2, 2.0, 2.0 ); 64 // returns ~-2.603 65 66 y = logcdf( 0.8, 4.0, 4.0 ); 67 // returns ~-0.968 68 69 y = logcdf( -0.5, 4.0, 2.0 ); 70 // returns -Infinity 71 72 y = logcdf( +Infinity, 4.0, 2.0 ); 73 // returns 0.0 74 ``` 75 76 If provided `NaN` as any argument, the function returns `NaN`. 77 78 ```javascript 79 var y = logcdf( NaN, 1.0, 1.0 ); 80 // returns NaN 81 82 y = logcdf( 0.0, NaN, 1.0 ); 83 // returns NaN 84 85 y = logcdf( 0.0, 1.0, NaN ); 86 // returns NaN 87 ``` 88 89 If provided `alpha <= 0`, the function returns `NaN`. 90 91 ```javascript 92 var y = logcdf( 2.0, -1.0, 0.5 ); 93 // returns NaN 94 95 y = logcdf( 2.0, 0.0, 0.5 ); 96 // returns NaN 97 ``` 98 99 If provided `beta <= 0`, the function returns `NaN`. 100 101 ```javascript 102 var y = logcdf( 2.0, 0.5, -1.0 ); 103 // returns NaN 104 105 y = logcdf( 2.0, 0.5, 0.0 ); 106 // returns NaN 107 ``` 108 109 #### logcdf.factory( alpha, beta ) 110 111 Returns a function for evaluating the natural logarithm of the [cumulative distribution function][cdf] for a [beta prime][betaprime-distribution] distribution with parameters `alpha` (first shape parameter) and `beta` (second shape parameter). 112 113 ```javascript 114 var mylogcdf = logcdf.factory( 0.5, 0.5 ); 115 116 var y = mylogcdf( 0.8 ); 117 // returns ~-0.767 118 119 y = mylogcdf( 0.3 ); 120 // returns ~-1.143 121 ``` 122 123 </section> 124 125 <!-- /.usage --> 126 127 <section class="notes"> 128 129 ## Notes 130 131 - In virtually all cases, using the `logpdf` or `logcdf` functions is preferable to manually computing the logarithm of the `pdf` or `cdf`, respectively, since the latter is prone to overflow and underflow. 132 133 </section> 134 135 <!-- /.notes --> 136 137 <section class="examples"> 138 139 ## Examples 140 141 <!-- eslint no-undef: "error" --> 142 143 ```javascript 144 var randu = require( '@stdlib/random/base/randu' ); 145 var EPS = require( '@stdlib/constants/float64/eps' ); 146 var logcdf = require( '@stdlib/stats/base/dists/betaprime/logcdf' ); 147 148 var alpha; 149 var beta; 150 var x; 151 var y; 152 var i; 153 154 for ( i = 0; i < 10; i++ ) { 155 x = randu(); 156 alpha = ( randu()*5.0 ) + EPS; 157 beta = ( randu()*5.0 ) + EPS; 158 y = logcdf( x, alpha, beta ); 159 console.log( 'x: %d, α: %d, β: %d, ln(F(x;α,β)): %d', x.toFixed( 4 ), alpha.toFixed( 4 ), beta.toFixed( 4 ), y.toFixed( 4 ) ); 160 } 161 ``` 162 163 </section> 164 165 <!-- /.examples --> 166 167 <section class="links"> 168 169 [betaprime-distribution]: https://en.wikipedia.org/wiki/Beta_prime_distribution 170 171 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function 172 173 [incomplete-beta]: https://en.wikipedia.org/wiki/Beta_function#Incomplete_beta_function 174 175 </section> 176 177 <!-- /.links -->