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