README.md (4831B)
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 > [Binomial][binomial-distribution] distribution [cumulative distribution function][cdf]. 24 25 <section class="intro"> 26 27 The [cumulative distribution function][cdf] for a [binomial][binomial-distribution] random variable is 28 29 <!-- <equation class="equation" label="eq:binomial_cdf" align="center" raw="F(x;n,p) = \sum_{i=0}^{\lfloor x \rfloor} {n\choose i}p^i(1-p)^{n-i}" alt="Cumulative distribution function for a Binomial distribution."> --> 30 31 <div class="equation" align="center" data-raw-text="F(x;n,p) = \sum_{i=0}^{\lfloor x \rfloor} {n\choose i}p^i(1-p)^{n-i}" data-equation="eq:binomial_cdf"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/binomial/cdf/docs/img/equation_binomial_cdf.svg" alt="Cumulative distribution function for a Binomial distribution."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 where `n` is the number of trials and `p` is the success probability. The CDF can be equivalently expressed as 39 40 <!-- <equation class="equation" label="eq:binomial_cdf_incomplete_beta" align="center" raw="F(x;n,p) = I_{1-p}( n-x, x+1 )" alt="Cumulative distribution function for a Binomial distribution expressed using the incomplete beta function."> --> 41 42 <div class="equation" align="center" data-raw-text="F(x;n,p) = I_{1-p}( n-x, x+1 )" data-equation="eq:binomial_cdf_incomplete_beta"> 43 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@51534079fef45e990850102147e8945fb023d1d0/lib/node_modules/@stdlib/stats/base/dists/binomial/cdf/docs/img/equation_binomial_cdf_incomplete_beta.svg" alt="Cumulative distribution function for a Binomial distribution expressed using the incomplete beta function."> 44 <br> 45 </div> 46 47 <!-- </equation> --> 48 49 where `I` is the [lower regularized incomplete beta function][incomplete-beta]. 50 51 </section> 52 53 <!-- /.intro --> 54 55 <section class="usage"> 56 57 ## Usage 58 59 ```javascript 60 var cdf = require( '@stdlib/stats/base/dists/binomial/cdf' ); 61 ``` 62 63 #### cdf( x, n, p ) 64 65 Evaluates the [cumulative distribution function][cdf] for a [binomial][binomial-distribution] distribution with number of trials `n` and success probability `p`. 66 67 ```javascript 68 var y = cdf( 3.0, 20, 0.2 ); 69 // returns ~0.411 70 71 y = cdf( 21.0, 20, 0.2 ); 72 // returns 1.0 73 74 y = cdf( 5.0, 10, 0.4 ); 75 // returns ~0.834 76 77 y = cdf( 0.0, 10, 0.4 ); 78 // returns ~0.006 79 ``` 80 81 If provided `NaN` as any argument, the function returns `NaN`. 82 83 ```javascript 84 var y = cdf( NaN, 20, 0.5 ); 85 // returns NaN 86 87 y = cdf( 0.0, NaN, 0.5 ); 88 // returns NaN 89 90 y = cdf( 0.0, 20, NaN ); 91 // returns NaN 92 ``` 93 94 If provided a number of trials `n` which is not a nonnegative integer, the function returns `NaN`. 95 96 ```javascript 97 var y = cdf( 2.0, 1.5, 0.5 ); 98 // returns NaN 99 100 y = cdf( 2.0, -2.0, 0.5 ); 101 // returns NaN 102 ``` 103 104 If provided a success probability `p` outside of `[0,1]`, the function returns `NaN`. 105 106 ```javascript 107 var y = cdf( 2.0, 20, -1.0 ); 108 // returns NaN 109 110 y = cdf( 2.0, 20, 1.5 ); 111 // returns NaN 112 ``` 113 114 #### cdf.factory( n, p ) 115 116 Returns a function for evaluating the [cumulative distribution function][cdf] of a [binomial][binomial-distribution] distribution with number of trials `n` and success probability `p`. 117 118 ```javascript 119 var mycdf = cdf.factory( 10, 0.5 ); 120 121 var y = mycdf( 3.0 ); 122 // returns ~0.172 123 124 y = mycdf( 1.0 ); 125 // returns ~0.011 126 ``` 127 128 </section> 129 130 <!-- /.usage --> 131 132 <section class="examples"> 133 134 ## Examples 135 136 <!-- eslint no-undef: "error" --> 137 138 ```javascript 139 var randu = require( '@stdlib/random/base/randu' ); 140 var round = require( '@stdlib/math/base/special/round' ); 141 var cdf = require( '@stdlib/stats/base/dists/binomial/cdf' ); 142 143 var i; 144 var n; 145 var p; 146 var x; 147 var y; 148 149 for ( i = 0; i < 10; i++ ) { 150 x = randu() * 20.0; 151 n = round( randu() * 100.0 ); 152 p = randu(); 153 y = cdf( x, n, p ); 154 console.log( 'x: %d, n: %d, p: %d, F(x;n,p): %d', x.toFixed( 4 ), n, p.toFixed( 4 ), y.toFixed( 4 ) ); 155 } 156 ``` 157 158 </section> 159 160 <!-- /.examples --> 161 162 <section class="links"> 163 164 [binomial-distribution]: https://en.wikipedia.org/wiki/Binomial_distribution 165 166 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function 167 168 [incomplete-beta]: https://en.wikipedia.org/wiki/Beta_function#Incomplete_beta_function 169 170 </section> 171 172 <!-- /.links -->