bayesplain.rate

bayesplain.rate(events, exposure=1.0, reference=None, prior='jeffreys', label='', unit='', n_draws=None, seed='unset')[source]

Estimate one rate of events per unit of exposure.

With a Gamma(a, b) prior and events over exposure, the posterior is Gamma(a + events, b + exposure) – exact, with nothing to converge.

Parameters:
events : int or array_like

Events counted. Pass one count per period (with exposure per period, or a single shared one) and the counts are summed – and checked for whether they vary more than a steady rate allows.

exposure : float or array_like, default 1.0

How much was watched, in whatever units you want the rate reported in. To report crashes per million vehicle-miles, give the exposure in millions of vehicle-miles.

reference : float

The rate to compare against, per unit of exposure: a statewide rate, last year’s figure, a target. Required, because unlike a proportion there is no neutral default – a rate of 0.5 means nothing until you say per what.

prior : str, tuple, or RatePrior, default 'jeffreys'

A preset name, a (shape, exposure) pair, or the result of bayesplain.priors.from_previous_period().

label : str, optional

What is being counted, e.g. "pedestrian collisions".

unit : str, optional

How to print the rate, e.g. "per year" or "per 1,000 households".

n_draws : int, optional

Draws to take. Defaults to the package setting.

seed : int or None, optional

Seed for those draws.

Returns:

Call .summary() for the full report, and .predict(exposure=...) for a forecast of the next period’s count.

Return type:

Result

Examples

An intersection saw 14 pedestrian collisions over 4 years; the citywide average for comparable intersections is 2 a year.

>>> import bayesplain as bp
>>> res = bp.rate(14, exposure=4, reference=2.0, unit="per year")
>>> round(res.point(), 2)
3.54
>>> round(res.probability(">", 2.0), 3)
0.976
>>> res.predict(exposure=1).interval()
(0.0, 8.0)