bayesplain.compare_proportions

bayesplain.compare_proportions(successes, n, prior='uninformed', labels=None, estimand='difference', pool=False, threshold=0.0, n_draws=None, seed='unset')[source]

Compare a rate between two groups, or across several.

Each group gets its own exact Beta posterior. The quantity of interest – the difference, the risk ratio, or the odds ratio – is then obtained by drawing from both and combining draw by draw.

Those draws are independent samples from distributions known in closed form, the same operation as rolling dice. They are not MCMC: there is no chain, no burn-in, nothing to check for convergence. The distinction is worth making explicitly, because “simulation” and “MCMC” get used interchangeably and are not the same idea.

With three or more groups the headline becomes the spread between the highest and lowest rate, and the analysis is really about .pairwise() – the same shape as bayesplain.compare_groups(), for rates.

Parameters:
successes : array_like

Success counts, one per group: [x1, x2], or more.

n : array_like

Trial counts, one per group.

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

Prior applied to each group’s rate independently.

labels : sequence of str, optional

Group names, used in output and in the plain-English sentence. Defaults to ('group 1', 'group 2', ...).

estimand : {'difference', 'risk_ratio', 'odds_ratio'}, default 'difference'

Which comparison to report, for two groups. Always oriented as group 2 relative to group 1.

pool : bool, default False

With three or more groups, partially pool the rates: estimate how much groups like these typically differ, and pull each rate toward the typical one in proportion to how little data it rests on. Stops the smallest district from topping the ranking on noise alone.

threshold : float, default 0.0

With three or more groups, the spread between the highest and lowest rate that the reported probability is measured against, as a proportion (0.05 for five points).

n_draws : int, optional

Number of draws. Defaults to the package setting.

seed : int or None, optional

Seed for the draws.

Returns:

Call .summary() for the full report.

Return type:

Result

Examples

Two districts’ eviction filing rates – the case where the two frameworks give the same numbers and very different advice:

>>> import bayesplain as bp
>>> res = bp.compare_proportions(
...     successes=[34, 51],
...     n=[220, 240],
...     labels=["District A", "District B"],
... )
>>> round(res.probability(">", 0), 2)
0.94
>>> res.frequentist.pvalue > 0.05
True