Scope, and what is deliberately missing

A package that names its limits is more trustworthy than one that quietly degrades. Here is what bayesplain does not do, and why.

Not implemented, on purpose

Multi-factor ANOVA, interactions, and regression with more than one predictor. regression() handles a line with one predictor, which is closed form. Anything more requires integrating over several hyperparameters at once, which means importance sampling, which means a sampler in the dependency chain. That would break the constraint the whole package is organised around. Use Bambi, which reads much like statsmodels and is built for exactly this:

import bambi as bmb

model = bmb.Model("assessed_value ~ sqft + construction", data)
fitted = model.fit()

Mixed models and anything with random effects beyond one level of pooling. compare_groups(..., pool=True) gives you closed-form partial pooling across a single grouping. Anything nested or crossed belongs in a real modelling framework.

An omnibus Bayes factor for compare_groups. This one is a judgement call rather than a technical limit. The omnibus question — “is there a difference somewhere among these groups?” — is one a planner almost never needs answered, and grading the evidence for it requires a prior over every pattern of group differences at once. .pairwise() reports a validated Bayes factor for each pair you actually care about, which is both more useful and better grounded.

The hypergeometric contingency scheme for tables larger than 2×2. The sum runs over every table sharing the observed margins, which is rarely what a study design justifies anyway. The error message says so and points at the independent-multinomial scheme.

Causal inference of any kind. Nothing in this package makes a finding causal, and the correlation analysis attaches a note saying so to every result.

Known limitations of what is implemented

Partial pooling is empirical Bayes. compare_groups(pool=True) estimates the between-group variance and then treats it as known, and compare_proportions(..., pool=True) does the same with the spread of a Beta population of rates. That is what buys the closed form. It understates uncertainty slightly when the number of groups is small — under about five groups, prefer the unpooled estimates and say the smallest group is uncertain, rather than leaning on a τ² estimated from four numbers.

Means assume roughly normal data. The Student-t posterior comes from a normal likelihood. For small samples the package adds a note telling you to look at a histogram. For heavy-tailed or strongly skewed data — house prices, for instance — consider working on a log scale and reporting the result as a ratio.

Rates assume a steady Poisson process. Events that cluster vary more than that allows, and the interval comes out too narrow. rate() checks per-period counts for this and says so, but a single total cannot be checked. Overdispersed counts need a negative-binomial model, which is outside the one-dimensional line.

Effect sizes that cannot be negative are pulled upward by noise. Cohen’s w and Cramér’s V add up the uncertainty in every cell or category without letting any of it cancel, so a small sample reports a departure even when there is none. categories() measures its headline against that noise floor by default; for contingency(), compare the interval against the same table’s expected counts before reading much into a small V.

The correlation posterior is grid-based. Accurate to the resolution of the grid, which is adaptive and fine enough that the error is far below anything that would change a conclusion. It is not a closed form, and the documentation does not pretend otherwise.

Bayes factors are prior-sensitive, always. This is not a limitation of the implementation but of the quantity. .sensitivity() exists to make it visible rather than to make it go away, and its output frequently shows the interval barely moving while the Bayes factor moves by an order of magnitude. That is the honest picture.

Where the line sits

The rule is simple enough to apply without arguing about it: if a question can be answered by a conjugate update, a closed-form Bayes factor, or a one-dimensional integral, it belongs here. Otherwise it belongs in a modelling framework, and the documentation should hand you over cleanly rather than growing a worse version of one.