Documentation: Negative Binomial

[fullerf]

Reading the documentation on the Univariate Discrete > NegativeBinomial, I was led to think that the wikipedia definition of the distribution was being used. Upon testing it appears that the "Mathematica definition" is used instead. You'll get good agreement between the observed mean and the formula: E[NB(n,p)] = n(1-p)/p. Also tested Var[NB(n,p)] = n(1-p)/p^2. Both of these agreed well with the implementation in Distributions.jl.

The difference between the Wikipedia definition and the "Mathematica Definition", is just a change of variables: NB_wiki(n,1-p) = NB_mathematica(n,p). For the wiki definition, the mean has the formula np/(1-p), variance = np/(1-p)^2.

tl;dr: Documentation doesn't quite match implementation. It's off by a change of variables.

[johnmyleswhite]

A pull request that improves the documentation would very helpful.

[sivapvarma]

@fullerf The definition in documenation says the samething as mathematica's documentation here.

Both Julia and Mathematica's implementation count the number of failures before r th success with p as probability of success in an individual trial.

I guess the confusion was due to subtle difference in pmf's between the two definitions.

For Julia/Mathematica definition pmf(k) will be proportional to p^r (1-p)^k whereas for the Wikipedia definition(which counts number of success until r failures) pmf(k) will be proportional to p^k (1-p)^r

[konkam]

I got into the same trap, the pmf in the documentation matches that of the function, but the parameterisation is different from Wikipedia.

The parameterisation used here matches that of R and Mathematica.

I'd suggest simply writing a warning next to the link to Wikipedia. I can make the pull request if you agree with this.

[mschauer]

This problem could be alleviated by means of keyword arguments via #823, with named arguments such as psuccess or pfailure in the constructor.

[matbesancon]

I would consider this closed by #825