Skip to content

Commit cb6b8af

Browse files
PlaneshifterPlaneshifter
committed
Add exponential logcdf
1 parent 011f7d3 commit cb6b8af

15 files changed

Lines changed: 871 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Logarithm of Cumulative Distribution Function
2+
3+
> Evaluate the natural logarithm of the [cumulative distribution function][cdf] for an [exponential][exponential-distribution] distribution.
4+
5+
<section class="intro">
6+
7+
The [cumulative distribution function][cdf] for an [exponential][exponential-distribution] random variable is
8+
9+
<!-- <equation class="equation" label="eq:exponential_cdf" align="center" raw="F(x;\lambda) = \begin{cases} 1-e^{-\lambda x} & x \ge 0 \\ 0 & x < 0 \end{cases}" alt="Cumulative distribution function for an exponential distribution."> -->
10+
11+
<div class="equation" align="center" data-raw-text="F(x;\lambda) = \begin{cases} 1-e^{-\lambda x} &amp; x \ge 0 \\ 0 &amp; x &lt; 0 \end{cases}" data-equation="eq:exponential_cdf">
12+
<img src="https://cdn.rawgit.com/stdlib-js/stdlib/bb29798906e119fcb2af99e94b60407a270c9b32/lib/node_modules/@stdlib/math/base/dist/exponential/cdf/docs/img/equation_exponential_cdf.svg" alt="Cumulative distribution function for an exponential distribution.">
13+
<br>
14+
</div>
15+
16+
<!-- </equation> -->
17+
18+
where `λ` is the rate parameter.
19+
20+
</section>
21+
22+
<!-- /.intro -->
23+
24+
<section class="usage">
25+
26+
## Usage
27+
28+
```javascript
29+
var logcdf = require( '@stdlib/math/base/dist/exponential/logcdf' );
30+
```
31+
32+
#### logcdf( x, lambda )
33+
34+
Evaluates the natural logarithm of the [cumulative distribution function][cdf] for an [exponential][exponential-distribution] distribution with rate parameter `lambda`.
35+
36+
```javascript
37+
var y = logcdf( 2.0, 0.3 );
38+
// returns ~-0.796
39+
40+
y = logcdf( 10.0, 0.3 );
41+
// returns ~-0.051
42+
```
43+
44+
If provided `NaN` as any argument, the function returns `NaN`.
45+
46+
```javascript
47+
var y = logcdf( NaN, 0.0 );
48+
// returns NaN
49+
50+
y = logcdf( 0.0, NaN );
51+
// returns NaN
52+
```
53+
54+
If provided `lambda < 0`, the function returns `NaN`.
55+
56+
```javascript
57+
var y = logcdf( 2.0, -1.0 );
58+
// returns NaN
59+
```
60+
61+
#### logcdf.factory( lambda )
62+
63+
Returns a function for evaluating the natural logarithm of the [cumulative distribution function (CDF)][cdf] for an exponential distribution with rate parameter `lambda`.
64+
65+
```javascript
66+
var mylogcdf = logcdf.factory( 0.1 );
67+
68+
var y = mylogcdf( 8.0 );
69+
// returns ~-0.597
70+
71+
y = mylogcdf( 2.0 );
72+
// returns ~-1.708
73+
74+
y = mylogcdf( 0.0 );
75+
// returns -Infinity
76+
```
77+
78+
</section>
79+
80+
<!-- /.usage -->
81+
82+
<section class="examples">
83+
84+
## Examples
85+
86+
```javascript
87+
var randu = require( '@stdlib/math/base/random/randu' );
88+
var logcdf = require( '@stdlib/math/base/dist/exponential/logcdf' );
89+
90+
var lambda;
91+
var x;
92+
var y;
93+
var i;
94+
95+
for ( i = 0; i < 10; i++ ) {
96+
x = randu() * 10.0;
97+
lambda = randu() * 10.0;
98+
y = logcdf( x, lambda );
99+
console.log( 'x: %d, λ: %d, ln(F(x;λ)): %d', x, lambda, y );
100+
}
101+
```
102+
103+
</section>
104+
105+
<!-- /.examples -->
106+
107+
<section class="links">
108+
109+
[cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function
110+
111+
[exponential-distribution]: https://en.wikipedia.org/wiki/Exponential_distribution
112+
113+
</section>
114+
115+
<!-- /.links -->

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/benchmark/benchmark.js‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var bench = require( '@stdlib/bench' );
6+
var randu = require( '@stdlib/math/base/random/randu' );
7+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
8+
var EPS = require( '@stdlib/math/constants/float64-eps' );
9+
var pkg = require( './../package.json' ).name;
10+
var logcdf = require( './../lib' );
11+
12+
13+
// MAIN //
14+
15+
bench( pkg, function benchmark( b ) {
16+
var lambda;
17+
var x;
18+
var y;
19+
var i;
20+
21+
b.tic();
22+
for ( i = 0; i < b.iterations; i++ ) {
23+
x = ( randu()*100.0 );
24+
lambda = ( randu()*100.0 ) + EPS;
25+
y = logcdf( x, lambda );
26+
if ( isnan( y ) ) {
27+
b.fail( 'should not return NaN' );
28+
}
29+
}
30+
b.toc();
31+
if ( isnan( y ) ) {
32+
b.fail( 'should not return NaN' );
33+
}
34+
b.pass( 'benchmark finished' );
35+
b.end();
36+
});
37+
38+
bench( pkg+':factory', function benchmark( b ) {
39+
var lambda;
40+
var mylogcdf;
41+
var x;
42+
var y;
43+
var i;
44+
45+
lambda = 10.0;
46+
mylogcdf = logcdf.factory( lambda );
47+
48+
b.tic();
49+
for ( i = 0; i < b.iterations; i++ ) {
50+
x = ( randu()*100.0 ) + EPS;
51+
y = mylogcdf( x );
52+
if ( isnan( y ) ) {
53+
b.fail( 'should not return NaN' );
54+
}
55+
}
56+
b.toc();
57+
if ( isnan( y ) ) {
58+
b.fail( 'should not return NaN' );
59+
}
60+
b.pass( 'benchmark finished' );
61+
b.end();
62+
});

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/docs/img/equation_exponential_cdf.svg‎

Lines changed: 61 additions & 0 deletions
Loading

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/docs/repl.txt‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
2+
{{alias}}( x, λ )
3+
Evaluates the natural logarithm of the cumulative distribution function
4+
(CDF) for an exponential distribution with rate parameter `λ` at a value
5+
`x`.
6+
7+
If provided `NaN` as any argument, the function returns `NaN`.
8+
9+
If provided a negative value for `λ`, the function returns `NaN`.
10+
11+
Parameters
12+
----------
13+
x: number
14+
Input value.
15+
16+
λ: number
17+
Rate parameter.
18+
19+
Returns
20+
-------
21+
out: number
22+
Evaluated logCDF.
23+
24+
Examples
25+
--------
26+
> var y = {{alias}}( 2.0, 0.1 )
27+
~-1.708
28+
> y = {{alias}}( 1.0, 2.0 )
29+
~-0.145
30+
> y = {{alias}}( -1.0, 4.0 )
31+
-Infinity
32+
> y = {{alias}}( NaN, 1.0 )
33+
NaN
34+
> y = {{alias}}( 0.0, NaN )
35+
NaN
36+
37+
// Negative rate parameter:
38+
> y = {{alias}}( 2.0, -1.0 )
39+
NaN
40+
41+
{{alias}}.factory( λ )
42+
Returns a function for evaluating the natural logarithm of the cumulative
43+
distribution function (CDF) for an exponential distribution with rate
44+
parameter `λ`.
45+
46+
Parameters
47+
----------
48+
λ: number
49+
Rate parameter.
50+
51+
Returns
52+
-------
53+
logcdf: Function
54+
Logarithm of cumulative distribution function (CDF).
55+
56+
Examples
57+
--------
58+
> var mylogCDF = {{alias}}.factory( 0.5 );
59+
> var y = mylogCDF( 3.0 )
60+
~-0.252
61+
62+
See Also
63+
--------
64+

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/examples/index.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
'use strict';
2+
3+
var randu = require( '@stdlib/math/base/random/randu' );
4+
var logcdf = require( './../lib' );
5+
6+
var lambda;
7+
var x;
8+
var y;
9+
var i;
10+
11+
for ( i = 0; i < 10; i++ ) {
12+
x = randu() * 10.0;
13+
lambda = randu() * 10.0;
14+
y = logcdf( x, lambda );
15+
console.log( 'x: %d, λ: %d, ln(F(x;λ)): %d', x, lambda, y );
16+
}

‎lib/node_modules/@stdlib/math/base/dist/exponential/logcdf/lib/factory.js‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var constantFunction = require( '@stdlib/utils/constant-function' );
6+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
7+
var log1p = require( '@stdlib/math/base/special/log1p' );
8+
var exp = require( '@stdlib/math/base/special/exp' );
9+
var NINF = require( '@stdlib/math/constants/float64-ninf' );
10+
var PINF = require( '@stdlib/math/constants/float64-pinf' );
11+
12+
13+
// MAIN //
14+
15+
/**
16+
* Returns a function for evaluating the natural logarithm of the cumulative distribution function (CDF) for an exponential distribution with rate parameter `lambda`.
17+
*
18+
* @param {PositiveNumber} lambda - rate parameter
19+
* @returns {Function} logCDF
20+
*
21+
* @example
22+
* var logcdf = factory( 0.5 );
23+
* var y = logcdf( 3.0 );
24+
* // returns ~-0.252
25+
*
26+
* y = logcdf( 1.0 );
27+
* // returns ~-0.933
28+
*/
29+
function factory( lambda ) {
30+
if (
31+
isnan( lambda ) ||
32+
lambda < 0.0 ||
33+
lambda === PINF
34+
) {
35+
return constantFunction( NaN );
36+
}
37+
return logcdf;
38+
39+
/**
40+
* Evaluates the natural logarithm of the cumulative distribution function (CDF) for an exponential distribution.
41+
*
42+
* @private
43+
* @param {number} x - input value
44+
* @returns {number} evaluated logCDF
45+
*
46+
* @example
47+
* var y = logcdf( 2.0 );
48+
* // returns <number>
49+
*/
50+
function logcdf( x ) {
51+
if ( x < 0.0 ) {
52+
return NINF;
53+
}
54+
return log1p( -exp( -lambda * x ) );
55+
} // end FUNCTION logcdf()
56+
} // end FUNCTION factory()
57+
58+
59+
// EXPORTS //
60+
61+
module.exports = factory;

0 commit comments

Comments
 (0)