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