Skip to content

Quickstart

import numpy as np
import accudist as ad

The four letters

Every distribution has up to four functions, exactly as in R:

prefix meaning first argument
d density / mass x
p distribution function (CDF) q
q quantile function p
r random draws n (the number of draws)
ad.dnorm(1.96)                 # 0.0584...
ad.pnorm(1.96)                 # 0.9750...
ad.qnorm(0.975)                # 1.9599...
ad.rnorm(3)                    # array([...])

Tails and the log scale

lower_tail=False selects R's direct upper-tail algorithm; it is not 1 - cdf. log=True returns natural logarithms for d, p and q alike (R spells it log.p= for p/q; accudist uses log= everywhere).

ad.ppois(200, 0.1, lower_tail=False)            # 0.0     underflows in linear space, like R
ad.ppois(200, 0.1, lower_tail=False, log=True)  # -1331.45...  the actual answer
ad.qnorm(-1000, log=True)                        # -44.6157...  quantile of a log-probability
ad.pbinom(900, 1000, 1/6, lower_tail=False, log=True)   # -1312.69

Arrays and broadcasting

Everything is a NumPy ufunc underneath: array arguments broadcast, out= writes into a preallocated array, and scalar inputs return numpy.float64.

q = np.arange(100, 105)
ad.ppois(q, 0.1, lower_tail=False, log=True)          # shape (5,)
ad.dnorm(np.zeros((3, 1)), mean=[0.0, 1.0])           # shape (3, 2)

out = np.empty(5)
ad.ppois(q, 0.1, lower_tail=False, log=True, out=out)

Parameterisations, the R way

ad.pgamma(2.0, shape=3, rate=2.0)      # R: pgamma(2, 3, rate = 2)
ad.pgamma(2.0, shape=3, scale=0.5)     # same value
ad.pnbinom(3, size=5, mu=7.0)          # R's mu parameterisation
ad.pchisq(3.0, df=5, ncp=1.5)          # non-central chi-squared
ad.pchisq(3.0, df=5)                   # central algorithm (ncp=None), as in R when ncp is missing
ad.dpois(2, lambda_=3.0)               # lambda is a Python keyword

Special functions

Special functions keep Rmath's C names so gammafn sits unambiguously beside dgamma:

ad.gammafn(5.0)            # R: gamma(5)     -> 24
ad.lgammafn(100.0)         # R: lgamma(100)
ad.psigamma(2.0, deriv=1)  # R: psigamma(2, 1) == trigamma(2)
ad.bessel_i(1.0, 0.5, expon_scaled=True)   # R: besselI(1, 0.5, TRUE)
ad.lchoose(1000, 500)      # R: lchoose(1000, 500)

Warnings

Invalid arguments give NaN and a warning, like R's "NaNs produced":

ad.qbinom(0.5, -1, 0.5)          # nan, AccudistDomainWarning
with ad.errstate(domain="raise"):
    ad.qbinom(0.5, -1, 0.5)      # raises AccudistDomainError (a ValueError)
with ad.errstate(all="ignore"):
    ad.qbinom(0.5, -1, 0.5)      # nan, silently

Coming from scipy: the compat layer

You can keep scipy's names and parameters. accudist.compat provides the same distribution objects with the same method names, frozen or unfrozen, but every evaluation goes through R's algorithms. In most code the change is one import:

# from scipy.stats import binom, poisson, nbinom, chi2, gamma, norm
from accudist.compat import binom, poisson, nbinom, chi2, gamma, norm

binom.logsf(900, 1000, 1/6)             # -1312.687973    scipy: -inf
poisson(0.1).logsf(200)                 # -1331.454401    scipy: -inf
nbinom.logsf(1e5, 10, 0.5)              # -69230.834396   scipy: -inf
chi2.logsf(np.array([100, 300, 500]), 10)   # array([-37.45, -133.11, -231.08]); scipy: -inf beyond ~100

The methods that matter are sf, logsf and isf. scipy evaluates most survival functions as 1 - cdf, which becomes exactly 0 once the CDF rounds to 1, so logsf returns -inf. accudist calls R's direct upper-tail code instead. For the log-likelihood of a rare count, a tail p-value below 1e-16, or an extreme quantile, that is the difference between an answer and no answer.

Where scipy is accurate, both agree to about 1e-12, including loc and scale, so switching the import does not change existing results:

from scipy import stats
norm.isf(1e-300)                              # 37.0470962993612 (scipy: same)
gamma.pdf(3.0, 2.5, loc=1, scale=2)           # 0.1383691658068649
stats.gamma.pdf(3.0, 2.5, loc=1, scale=2)     # 0.1383691658068649
d = norm(loc=10, scale=2); d.cdf(12); d.rvs(size=3)

Available distributions: binom, poisson, nbinom, geom, hypergeom, norm, gamma, beta, chi2, t, f, expon, weibull_min, lognorm, cauchy, logistic, uniform. Methods: pmf/pdf, logpmf/logpdf, cdf, logcdf, sf, logsf, ppf, isf, rvs. Anything else (fit, mean, var, entropy, ...) raises NotImplementedError with a pointer to scipy: the shim is for evaluating distributions precisely, not a scipy replacement. Three parameterisation traps (geom support starting at 1, hypergeom's (M, n, N), lognorm's scale = exp(meanlog)) are handled and documented in the compat guide.

Random draws

ad.set_r_seed(42)                 # like R's set.seed(42) under RNGkind("Marsaglia-Multicarry")
ad.rpois(5, 3.0)
rng = ad.RNG.from_r_seed(7)       # an independent, thread-safe stream
rng.rgamma(1000, shape=2.5, rate=2.0)

See Random numbers for what is and is not reproducible against R.