README.md (4628B)
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 [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution. 24 25 <section class="intro"> 26 27 The [cumulative distribution function][cdf] for a [Kumaraswamy's double bounded][kumaraswamy-distribution] random variable is 28 29 <!-- <equation class="equation" label="eq:kumaraswamy_cdf" align="center" raw="F(x;a,b) = 1-(1-x^{a})^{b}" alt="Cumulative distribution function for a Kumaraswamy's double bounded distribution."> --> 30 31 <div class="equation" align="center" data-raw-text="F(x;a,b) = 1-(1-x^{a})^{b}" data-equation="eq:kumaraswamy_cdf"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/kumaraswamy/logcdf/docs/img/equation_kumaraswamy_cdf.svg" alt="Cumulative distribution function for a Kumaraswamy's double bounded distribution."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `a > 0` is the first shape parameter and `b > 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 logcdf = require( '@stdlib/stats/base/dists/kumaraswamy/logcdf' ); 50 ``` 51 52 #### logcdf( x, a, b ) 53 54 Evaluates the natural logarithm of the [cumulative distribution function][cdf] (CDF) for a [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution with parameters `a` (first shape parameter) and `b` (second shape parameter). 55 56 ```javascript 57 var y = logcdf( 0.5, 1.0, 1.0 ); 58 // returns ~-0.693 59 60 y = logcdf( 0.5, 2.0, 4.0 ); 61 // returns ~-0.38 62 63 y = logcdf( 0.2, 2.0, 2.0 ); 64 // returns ~-2.546 65 66 y = logcdf( 0.8, 4.0, 4.0 ); 67 // returns ~-0.13 68 69 y = logcdf( -0.5, 4.0, 2.0 ); 70 // returns -Infinity 71 72 y = logcdf( -Infinity, 4.0, 2.0 ); 73 // returns -Infinity 74 75 y = logcdf( 1.5, 4.0, 2.0 ); 76 // returns 0.0 77 78 y = logcdf( +Infinity, 4.0, 2.0 ); 79 // returns 0.0 80 ``` 81 82 If provided `NaN` as any argument, the function returns `NaN`. 83 84 ```javascript 85 var y = logcdf( NaN, 1.0, 1.0 ); 86 // returns NaN 87 88 y = logcdf( 0.0, NaN, 1.0 ); 89 // returns NaN 90 91 y = logcdf( 0.0, 1.0, NaN ); 92 // returns NaN 93 ``` 94 95 If provided `a <= 0`, the function returns `NaN`. 96 97 ```javascript 98 var y = logcdf( 2.0, -1.0, 0.5 ); 99 // returns NaN 100 101 y = logcdf( 2.0, 0.0, 0.5 ); 102 // returns NaN 103 ``` 104 105 If provided `b <= 0`, the function returns `NaN`. 106 107 ```javascript 108 var y = logcdf( 2.0, 0.5, -1.0 ); 109 // returns NaN 110 111 y = logcdf( 2.0, 0.5, 0.0 ); 112 // returns NaN 113 ``` 114 115 #### logcdf.factory( a, b ) 116 117 Returns a function for evaluating the natural logarithm of the [cumulative distribution function][cdf] for a [Kumaraswamy's double bounded][kumaraswamy-distribution] distribution with parameters `a` (first shape parameter) and `b` (second shape parameter). 118 119 ```javascript 120 var mylogcdf = logcdf.factory( 0.5, 0.5 ); 121 122 var y = mylogcdf( 0.8 ); 123 // returns ~-0.393 124 125 y = mylogcdf( 0.3 ); 126 // returns ~-1.116 127 ``` 128 129 </section> 130 131 <!-- /.usage --> 132 133 <section class="notes"> 134 135 ## Notes 136 137 - 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. 138 139 </section> 140 141 <!-- /.notes --> 142 143 <section class="examples"> 144 145 ## Examples 146 147 <!-- eslint no-undef: "error" --> 148 149 ```javascript 150 var randu = require( '@stdlib/random/base/randu' ); 151 var EPS = require( '@stdlib/constants/float64/eps' ); 152 var logcdf = require( '@stdlib/stats/base/dists/kumaraswamy/logcdf' ); 153 154 var a; 155 var b; 156 var x; 157 var y; 158 var i; 159 160 for ( i = 0; i < 10; i++ ) { 161 x = randu(); 162 a = ( randu()*5.0 ) + EPS; 163 b = ( randu()*5.0 ) + EPS; 164 y = logcdf( x, a, b ); 165 console.log( 'x: %d, a: %d, b: %d, ln(F(x;a,b)): %d', x.toFixed( 4 ), a.toFixed( 4 ), b.toFixed( 4 ), y.toFixed( 4 ) ); 166 } 167 ``` 168 169 </section> 170 171 <!-- /.examples --> 172 173 <section class="links"> 174 175 [kumaraswamy-distribution]: https://en.wikipedia.org/wiki/Kumaraswamy_distribution 176 177 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function 178 179 </section> 180 181 <!-- /.links -->