bayesplain.correlation

bayesplain.correlation(x, y, prior='uninformed', labels=None, aggregated=False, n_draws=None, seed='unset', data=None)[source]

Estimate the correlation between two variables.

The posterior is computed from the exact sampling density of the correlation coefficient, evaluated on a grid and sampled by inverting its cumulative distribution. Not a conjugate update and not MCMC – a one-dimensional integral, which is all this problem needs.

Parameters:
x : array_like or str

Paired observations, or the names of two columns in data. Rows where either value is missing are dropped, and the summary says how many.

y : array_like or str

Paired observations, or the names of two columns in data. Rows where either value is missing are dropped, and the summary says how many.

prior : str, float, or CorrelationPrior, default 'uninformed'

Stretched-beta prior width on the correlation. The default is flat on (-1, 1). See bayesplain.priors.describe().

labels : sequence of str, optional

Names of the two variables, used in output.

aggregated : bool, default False

Set to True when the rows are geographic areas rather than individuals. This adds the ecological-correlation and modifiable-areal- unit warnings to the result, because a correlation between tract averages is not a correlation between people.

n_draws : int, optional

Number of draws. Defaults to the package setting.

seed : int or None, optional

Seed for the draws.

data : data frame, optional

Where to look x and y up when they are column names. The column names become the labels unless labels is given.

Returns:

Call .summary() for the full report.

Return type:

Result

Examples

>>> import numpy as np, bayesplain as bp
>>> rng = np.random.default_rng(0)
>>> x = rng.normal(size=60)
>>> y = 0.5 * x + rng.normal(size=60)
>>> res = bp.correlation(x, y, labels=["density", "transit use"])
>>> res.probability(">", 0) > 0.95
True