README.md (6504B)
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 # Binomial 22 23 > Binomial distribution constructor. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var Binomial = require( '@stdlib/stats/base/dists/binomial/ctor' ); 41 ``` 42 43 #### Binomial( \[n, p] ) 44 45 Returns a [binomial][binomial-distribution] distribution object. 46 47 ```javascript 48 var binomial = new Binomial(); 49 50 var mu = binomial.mean; 51 // returns 0.5 52 ``` 53 54 By default, `n = 1` and `p = 0.5`, which corresponds to a [Bernoulli][bernoulli-distribution] distribution. To create a distribution having a different `n` (number of trials) and `p` (success probability), provide the corresponding arguments. 55 56 ```javascript 57 var binomial = new Binomial( 4, 0.2 ); 58 59 var mu = binomial.mean; 60 // returns 0.8 61 ``` 62 63 * * * 64 65 ## binomial 66 67 A [binomial][binomial-distribution] distribution object has the following properties and methods... 68 69 ### Writable Properties 70 71 #### binomial.n 72 73 Number of trials of the distribution. `n` **must** be a positive integer. 74 75 ```javascript 76 var binomial = new Binomial(); 77 78 var n = binomial.n; 79 // returns 1.0 80 81 binomial.n = 4; 82 83 n = binomial.n; 84 // returns 4.0 85 ``` 86 87 #### binomial.p 88 89 Success probability of the distribution. `p` **must** be a number between 0 and 1. 90 91 ```javascript 92 var binomial = new Binomial( 4, 0.2 ); 93 94 var p = binomial.p; 95 // returns 0.2 96 97 binomial.p = 0.7; 98 99 p = binomial.p; 100 // returns 0.7 101 ``` 102 103 * * * 104 105 ### Computed Properties 106 107 #### Binomial.prototype.kurtosis 108 109 Returns the [excess kurtosis][kurtosis]. 110 111 ```javascript 112 var binomial = new Binomial( 12, 0.4 ); 113 114 var kurtosis = binomial.kurtosis; 115 // returns ~-0.153 116 ``` 117 118 #### Binomial.prototype.mean 119 120 Returns the [expected value][expected-value]. 121 122 ```javascript 123 var binomial = new Binomial( 12, 0.4 ); 124 125 var mu = binomial.mean; 126 // returns ~4.8 127 ``` 128 129 #### Binomial.prototype.median 130 131 Returns the [median][median]. 132 133 ```javascript 134 var binomial = new Binomial( 12, 0.4 ); 135 136 var median = binomial.median; 137 // returns 5.0 138 ``` 139 140 #### Binomial.prototype.mode 141 142 Returns the [mode][mode]. 143 144 ```javascript 145 var binomial = new Binomial( 12, 0.4 ); 146 147 var mode = binomial.mode; 148 // returns 5.0 149 ``` 150 151 #### Binomial.prototype.skewness 152 153 Returns the [skewness][skewness]. 154 155 ```javascript 156 var binomial = new Binomial( 12, 0.4 ); 157 158 var skewness = binomial.skewness; 159 // returns ~0.118 160 ``` 161 162 #### Binomial.prototype.stdev 163 164 Returns the [standard deviation][standard-deviation]. 165 166 ```javascript 167 var binomial = new Binomial( 12, 0.4 ); 168 169 var s = binomial.stdev; 170 // returns ~1.697 171 ``` 172 173 #### Binomial.prototype.variance 174 175 Returns the [variance][variance]. 176 177 ```javascript 178 var binomial = new Binomial( 12, 0.4 ); 179 180 var s2 = binomial.variance; 181 // returns ~2.88 182 ``` 183 184 * * * 185 186 ### Methods 187 188 #### Binomial.prototype.cdf( x ) 189 190 Evaluates the [cumulative distribution function][cdf] (CDF). 191 192 ```javascript 193 var binomial = new Binomial( 4, 0.2 ); 194 195 var y = binomial.cdf( 0.5 ); 196 // returns ~0.41 197 ``` 198 199 #### Binomial.prototype.logpmf( x ) 200 201 Evaluates the natural logarithm of the [probability mass function][pmf] (PMF). 202 203 ```javascript 204 var binomial = new Binomial( 4, 0.2 ); 205 206 var y = binomial.logpmf( 2.0 ); 207 // returns ~-1.873 208 ``` 209 210 #### Binomial.prototype.mgf( t ) 211 212 Evaluates the [moment-generating function][mgf] (MGF). 213 214 ```javascript 215 var binomial = new Binomial( 4, 0.2 ); 216 217 var y = binomial.mgf( 0.5 ); 218 // returns ~1.629 219 ``` 220 221 #### Binomial.prototype.pmf( x ) 222 223 Evaluates the [probability mass function][pmf] (PMF). 224 225 ```javascript 226 var binomial = new Binomial( 4, 0.2 ); 227 228 var y = binomial.pmf( 2.0 ); 229 // returns ~0.154 230 ``` 231 232 #### Binomial.prototype.quantile( p ) 233 234 Evaluates the [quantile function][quantile-function] at probability `p`. 235 236 ```javascript 237 var binomial = new Binomial( 4, 0.2 ); 238 239 var y = binomial.quantile( 0.5 ); 240 // returns 1.0 241 242 y = binomial.quantile( 1.9 ); 243 // returns NaN 244 ``` 245 246 </section> 247 248 <!-- /.usage --> 249 250 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 251 252 <section class="notes"> 253 254 </section> 255 256 <!-- /.notes --> 257 258 <!-- Package usage examples. --> 259 260 * * * 261 262 <section class="examples"> 263 264 ## Examples 265 266 <!-- eslint no-undef: "error" --> 267 268 ```javascript 269 var Binomial = require( '@stdlib/stats/base/dists/binomial/ctor' ); 270 271 var binomial = new Binomial( 10, 0.4 ); 272 273 var mu = binomial.mean; 274 // returns 4.0 275 276 var mode = binomial.mode; 277 // returns 4.0 278 279 var s2 = binomial.variance; 280 // returns 2.4 281 282 var y = binomial.cdf( 0.8 ); 283 // returns ~0.006 284 ``` 285 286 </section> 287 288 <!-- /.examples --> 289 290 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 291 292 <section class="references"> 293 294 </section> 295 296 <!-- /.references --> 297 298 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 299 300 <section class="links"> 301 302 [bernoulli-distribution]: https://en.wikipedia.org/wiki/Bernoulli_distribution 303 304 [binomial-distribution]: https://en.wikipedia.org/wiki/Binomial_distribution 305 306 [cdf]: https://en.wikipedia.org/wiki/Cumulative_distribution_function 307 308 [mgf]: https://en.wikipedia.org/wiki/Moment-generating_function 309 310 [pmf]: https://en.wikipedia.org/wiki/Probability_mass_function 311 312 [quantile-function]: https://en.wikipedia.org/wiki/Quantile_function 313 314 [expected-value]: https://en.wikipedia.org/wiki/Expected_value 315 316 [kurtosis]: https://en.wikipedia.org/wiki/Kurtosis 317 318 [median]: https://en.wikipedia.org/wiki/Median 319 320 [mode]: https://en.wikipedia.org/wiki/Mode_%28statistics%29 321 322 [skewness]: https://en.wikipedia.org/wiki/Skewness 323 324 [standard-deviation]: https://en.wikipedia.org/wiki/Standard_deviation 325 326 [variance]: https://en.wikipedia.org/wiki/Variance 327 328 </section> 329 330 <!-- /.links -->