bayesplain.proportion

bayesplain.proportion(successes, n, prior='uninformed', reference=0.5, n_draws=None, seed='unset')[source]

Estimate one unknown rate from counts.

The posterior is exact. With a Beta(a, b) prior and successes out of n, it is Beta(a + successes, b + n - successes) – conjugacy means observing data just adds counts to the two shape parameters, so there is nothing to approximate and nothing to converge.

Parameters:
successes : int

Number of cases with the attribute of interest.

n : int

Number of cases examined.

prior : str, tuple, or BetaPrior, default 'uninformed'

A preset name, an (a, b) pair, or the result of bayesplain.priors.from_previous_study(...). See bayesplain.priors.describe().

reference : float, default 0.5

The rate to compare against: the null value for the frequentist test, the threshold for the reported direction probability, and the point null for the Bayes factor. Set this to a policy-relevant number rather than leaving it at 0.5 whenever one exists.

n_draws : int, optional

Draws to take for derived quantities. Defaults to the package setting.

seed : int or None, optional

Seed for those draws. Defaults to the package seed, so that a whole class sees identical digits.

Returns:

Call .summary() for the full report, and .predict(n=...) for a forecast of the successes among the next n cases.

Return type:

Result

Examples

>>> import bayesplain as bp
>>> res = bp.proportion(successes=34, n=220, reference=0.10)
>>> round(res.point(), 4)
0.1566
>>> round(res.probability(">", 0.10), 3)
0.996

Notes

The 95% equal-tailed credible interval here will land very close to a Wilson score confidence interval on the same data. That is worth showing students explicitly: the two frameworks often produce nearly the same numbers while licensing very different sentences, so the choice between them is rarely about arithmetic.