improve docs (#42)

src/numba_stats/bernstein.py

@@ -1,3 +1,14 @@
+"""
+Empirical density distribution formed by a Bernstein polynomial.
+
+The Bernstein polynomial basis is better suited to model a probability distribution
+than the Chebychev basis, since it is possible to implement the constraint
+f(x; p) >= 0 with simple parameter limits p >= 0 (where p is a vector).
+
+The density function and its integral are not normalised. This is not an issue when
+the density is used in an extended maximum-likelihood fit.
+"""
+
 import numpy as np
 import numba as nb
 

src/numba_stats/norm.py

@@ -26,7 +26,7 @@ def _ppf(p):
 @_vectorize(3)
 def logpdf(x, loc, scale):
     """
-    Return log of probability density of normal distribution.
+    Return log of probability density.
     """
     z = (x - loc) / scale
     return _logpdf(z) - np.log(scale)
@@ -35,15 +35,15 @@ def logpdf(x, loc, scale):
 @_vectorize(3)
 def pdf(x, loc, scale):
     """
-    Return probability density of normal distribution.
+    Return probability density.
     """
     return np.exp(logpdf(x, loc, scale))
 
 
 @_vectorize(3)
 def cdf(x, loc, scale):
     """
-    Return cumulative probability of normal distribution.
+    Return cumulative probability.
     """
     z = (x - loc) / scale
     return _cdf(z)
@@ -52,7 +52,7 @@ def cdf(x, loc, scale):
 @_vectorize(3, cache=False)  # cannot cache this
 def ppf(p, loc, scale):
     """
-    Return quantile of normal distribution for given probability.
+    Return quantile for given probability.
     """
     z = _ppf(p)
     return scale * z + loc

src/numba_stats/poisson.py

@@ -1,3 +1,7 @@
+"""
+Poisson distribution.
+"""
+
 import numba as nb
 import numpy as np
 from ._special import gammaincc as _gammaincc
@@ -12,7 +16,7 @@
 @nb.vectorize(_signatures)
 def logpmf(k, mu):
     """
-    Return log of probability mass for Poisson distribution.
+    Return log of probability mass.
     """
     if mu == 0:
         return 0.0 if k == 0 else -np.inf
@@ -22,14 +26,14 @@ def logpmf(k, mu):
 @nb.vectorize(_signatures)
 def pmf(k, mu):
     """
-    Return probability mass for Poisson distribution.
+    Return probability mass.
     """
     return np.exp(logpmf(k, mu))
 
 
 @nb.vectorize(_signatures)
 def cdf(k, mu):
     """
-    Evaluate cumulative distribution function of Poisson distribution.
+    Evaluate cumulative distribution function.
     """
     return _gammaincc(k + 1, mu)

src/numba_stats/qgaussian.py

@@ -1,3 +1,15 @@
+"""
+Q-Gaussian distribution.
+
+A generalisation (q-analog) of the normal distribution based on Tsallis entropy. It
+can be used an alternative model for the normal distribution to check for model bias.
+
+It is equivalent to Student's t distribution and can be computed from the latter via
+a change of variables, which is exploited in this implementation.
+
+https://en.wikipedia.org/wiki/Q-Gaussian_distribution
+"""
+
 import numpy as np
 from math import lgamma as _lgamma
 from . import norm as _norm, t as _t

src/numba_stats/t.py

@@ -1,3 +1,6 @@
+"""
+Student's t distribution.
+"""
 import numpy as np
 from ._special import stdtr as _cdf, stdtrit as _ppf
 from ._util import _vectorize
@@ -7,7 +10,7 @@
 @_vectorize(4, cache=False)
 def logpdf(x, df, loc, scale):
     """
-    Return probability density of student's distribution.
+    Return probability density.
     """
     z = (x - loc) / scale
     k = 0.5 * (df + 1)
@@ -19,15 +22,15 @@ def logpdf(x, df, loc, scale):
 @_vectorize(4, cache=False)
 def pdf(x, df, loc, scale):
     """
-    Return probability density of student's distribution.
+    Return probability density.
     """
     return np.exp(logpdf(x, df, loc, scale))
 
 
 @_vectorize(4, cache=False)
 def cdf(x, df, loc, scale):
     """
-    Return cumulative probability of student's distribution.
+    Return cumulative probability.
     """
     z = (x - loc) / scale
     return _cdf(df, z)
@@ -36,7 +39,7 @@ def cdf(x, df, loc, scale):
 @_vectorize(4, cache=False)
 def ppf(p, df, loc, scale):
     """
-    Return quantile of student's distribution for given probability.
+    Return quantile for given probability.
     """
     if p == 0:
         return -np.inf

src/numba_stats/truncexpon.py

@@ -1,3 +1,6 @@
+"""
+Truncated exponential distribution.
+"""
 import numpy as np
 from ._util import _vectorize
 from .expon import _cdf, _ppf
@@ -6,7 +9,7 @@
 @_vectorize(5)
 def logpdf(x, xmin, xmax, loc, scale):
     """
-    Return log of probability density of truncated exponential distribution.
+    Return log of probability density.
     """
     if x < xmin:
         return -np.inf
@@ -22,15 +25,15 @@ def logpdf(x, xmin, xmax, loc, scale):
 @_vectorize(5)
 def pdf(x, xmin, xmax, loc, scale):
     """
-    Return probability density of truncated exponential distribution.
+    Return probability density.
     """
     return np.exp(logpdf(x, xmin, xmax, loc, scale))
 
 
 @_vectorize(5)
 def cdf(x, xmin, xmax, loc, scale):
     """
-    Return cumulative probability of truncated exponential distribution.
+    Return cumulative probability.
     """
     if x < xmin:
         return 0.0
@@ -49,7 +52,7 @@ def cdf(x, xmin, xmax, loc, scale):
 @_vectorize(5)
 def ppf(p, xmin, xmax, loc, scale):
     """
-    Return quantile of truncated exponential distribution for given probability.
+    Return quantile for given probability.
     """
     scale_inv = 1 / scale
     zmin = (xmin - loc) * scale_inv

src/numba_stats/tsallis.py

@@ -1,3 +1,11 @@
+"""
+Tsallis-Hagedorn distribution.
+
+A generalisation (q-analog) of the exponential distribution based on Tsallis entropy. It
+approximately describes the pT distribution charged particles produced in high-energy
+minimum bias particle collisions.
+"""
+
 import numpy as np
 from ._util import _vectorize
 

src/numba_stats/voigt.py

@@ -1,10 +1,21 @@
+"""
+Voigtian distribution.
+
+This is the convolution of a Cauchy distribution with a normal distribution.
+
+There is a closed form for the cdf, but the required hypergeometric function is not
+implemented anywhere.
+
+https://en.wikipedia.org/wiki/Voigt_profile
+"""
+
 from ._special import voigt_profile as _voigt
 from ._util import _vectorize
 
 
 @_vectorize(4, cache=False)
 def pdf(x, gamma, loc, scale):
     """
-    Return probability density of Voigtian distribution.
+    Return probability density.
     """
     return _voigt(x - loc, scale, gamma)