Skip to content

Bayes factors

Use this page when you want to convert between p-values and Bayes factors, or compute Bayes factors from posterior draws.

Utilities for one-sided p-values and Bayes factors.

The functions in this module provide numerically stable conversions between one-sided p-values and Bayes factors for directional hypotheses, and direct Bayes factor estimation from posterior draws.

as_bf(pvalue)

Convert a one-sided p-value to a Bayes factor.

This is useful when a directional p-value is available and evidence is needed on a Bayes-factor scale. Smaller p-values map to larger Bayes factors in favour of a directional effect.

Parameters:

Name Type Description Default
pvalue NDArray | float

The p-value(s) to be converted to Bayes factor(s). Can be a single value or an array of values.

 required

Returns:

Type Description
NDArray | float

The corresponding Bayes factor(s). The return type matches the input type.

Raises:

Type Description
ValueError

If any p-value is not strictly within the open interval (0, 1).
See Also

as_pvalue : Convert a Bayes factor to a p-value.

Notes

The mapping is based on the one-sided p-value interpretation in [1]_. Inputs are clipped near 0 and 1 for numerical stability.

References

.. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from a Bayesian Interpretation of the One-Sided P Value." Educational and Psychological Measurement, vol. 77, no. 3, 2017, pp. 529-539. doi:10.1177/0013164416669201.

Examples:

>>> import numpy as np
>>> from samesame.bayes_factors import as_bf
>>> as_bf(0.5)
np.float64(1.0)
>>> np.round(as_bf(0.05), 1)
np.float64(19.0)
>>> as_bf(np.array([0.05, 0.1, 0.5]))
array([19., 9., 1.])
Source code in src/samesame/bayes_factors.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def as_bf(
    pvalue: NDArray | float,
) -> NDArray | float:
    """
    Convert a one-sided p-value to a Bayes factor.

    This is useful when a directional p-value is available and evidence is
    needed on a Bayes-factor scale. Smaller p-values map to larger Bayes
    factors in favour of a directional effect.

    Parameters
    ----------
    pvalue : NDArray | float
        The p-value(s) to be converted to Bayes factor(s). Can be a single
        value or an array of values.

    Returns
    -------
    NDArray | float
        The corresponding Bayes factor(s). The return type matches the
        input type.

    Raises
    ------
    ValueError
        If any p-value is not strictly within the open interval (0, 1).

    See Also
    --------
    as_pvalue : Convert a Bayes factor to a p-value.

    Notes
    -----
    The mapping is based on the one-sided p-value interpretation in [1]_.
    Inputs are clipped near 0 and 1 for numerical stability.

    References
    ----------
    .. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from
       a Bayesian Interpretation of the One-Sided P Value." *Educational and
       Psychological Measurement*, vol. 77, no. 3, 2017, pp. 529-539.
       doi:10.1177/0013164416669201.

    Examples
    --------
    >>> import numpy as np
    >>> from samesame.bayes_factors import as_bf
    >>> as_bf(0.5)
    np.float64(1.0)
    >>> np.round(as_bf(0.05), 1)
    np.float64(19.0)
    >>> as_bf(np.array([0.05, 0.1, 0.5])) # doctest: +NORMALIZE_WHITESPACE
    array([19., 9., 1.])
    """
    if np.any(np.logical_or(pvalue >= 1, pvalue <= 0)):
        raise ValueError("pvalue must be within the open interval (0, 1).")
    pvalue = np.clip(pvalue, 1e-10, 1 - 1e-10)
    return 1.0 / np.exp(logit(pvalue))

as_pvalue(bayes_factor)

Convert a Bayes factor of a directional effect to a one-sided p-value.

This is useful when evidence is summarized as a Bayes factor but reporting requires one-sided p-values under the directional null.

Parameters:

Name Type Description Default
bayes_factor float | NDArray

The Bayes factor(s) to be converted to p-value(s). Can be a single value or an array of values.

 required

Returns:

Type Description
float | NDArray

The corresponding p-value(s). The return type matches the input type.

Raises:

Type Description
ValueError

If any Bayes factor is not strictly positive.
See Also

as_bf : Convert a one-sided p-value to a Bayes factor.

Notes

This is the inverse mapping of :func:as_bf under the same directional interpretation [1]_. Inputs are clipped to improve numerical stability.

References

.. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from a Bayesian Interpretation of the One-Sided P Value." Educational and Psychological Measurement, vol. 77, no. 3, 2017, pp. 529–539, https://doi.org/10.1177/0013164416669201.

Examples:

>>> import numpy as np
>>> from samesame.bayes_factors import as_pvalue
>>> as_pvalue(1)
np.float64(0.5)
>>> np.round(as_pvalue(19), 2)
np.float64(0.05)
>>> as_pvalue(np.array([19.0, 9.0, 1.0]))
array([0.05, 0.1 , 0.5 ])
Source code in src/samesame/bayes_factors.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def as_pvalue(
    bayes_factor: float | NDArray,
) -> float | NDArray:
    """
    Convert a Bayes factor of a directional effect to a one-sided p-value.

    This is useful when evidence is summarized as a Bayes factor but
    reporting requires one-sided p-values under the directional null.

    Parameters
    ----------
    bayes_factor : float | NDArray
        The Bayes factor(s) to be converted to p-value(s). Can be a single
        value or an array of values.

    Returns
    -------
    float | NDArray
        The corresponding p-value(s). The return type matches the input type.

    Raises
    ------
    ValueError
        If any Bayes factor is not strictly positive.

    See Also
    --------
    as_bf : Convert a one-sided p-value to a Bayes factor.

    Notes
    -----
    This is the inverse mapping of :func:`as_bf` under the same directional
    interpretation [1]_. Inputs are clipped to improve numerical stability.

    References
    ----------
    .. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from a
       Bayesian Interpretation of the One-Sided P Value." *Educational and
       Psychological Measurement*, vol. 77, no. 3, 2017, pp. 529–539,
       https://doi.org/10.1177/0013164416669201.

    Examples
    --------
    >>> import numpy as np
    >>> from samesame.bayes_factors import as_pvalue
    >>> as_pvalue(1)
    np.float64(0.5)
    >>> np.round(as_pvalue(19), 2)
    np.float64(0.05)
    >>> as_pvalue(np.array([19.0, 9.0, 1.0])) # doctest: +NORMALIZE_WHITESPACE
    array([0.05, 0.1 , 0.5 ])
    """
    if np.any(bayes_factor <= 0):
        raise ValueError("bayes_factor must be strictly positive.")
    bf_ = np.clip(bayes_factor, 1e-10, 1e10)
    pvalue = expit(-np.log(bf_))
    return pvalue

bayes_factor(posterior, threshold=0.0, adjustment=0)

Compute a directional Bayes factor from posterior samples.

The Bayes factor compares posterior support for values above a threshold against support for values at or below that threshold.

Parameters:

Name Type Description Default
posterior NDArray

An array of posterior samples.

 required
threshold float

The threshold value to test against. Default is 0.0.

 0.0
adjustment (0, 1)

Adjustment to apply to the Bayes factor calculation. Default is 0.

 0

Returns:

Type Description
float

Bayes factor in favour of the posterior mass being above threshold.
See Also

as_pvalue : Convert a Bayes factor to a p-value.

as_bf : Convert a p-value to a Bayes factor.

Notes

If all posterior draws exceed threshold, the denominator is zero and the returned Bayes factor can become infinite. adjustment can be used to regularize this edge case in finite samples.

References

.. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from a Bayesian Interpretation of the One-Sided P Value." Educational and Psychological Measurement, vol. 77, no. 3, 2017, pp. 529-539. doi:10.1177/0013164416669201.

Examples:

>>> import numpy as np
>>> from samesame.bayes_factors import bayes_factor
>>> posterior_samples = np.array([0.2, 0.5, 0.8, 0.9])
>>> bayes_factor(posterior_samples, threshold=0.5)
np.float64(1.0)
>>> np.isinf(bayes_factor(posterior_samples, threshold=0.0))
np.True_
Source code in src/samesame/bayes_factors.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
def bayes_factor(
    posterior: NDArray,
    threshold: float = 0.0,
    adjustment: Literal[0, 1] = 0,
) -> float:
    """
    Compute a directional Bayes factor from posterior samples.

    The Bayes factor compares posterior support for values above a threshold
    against support for values at or below that threshold.

    Parameters
    ----------
    posterior : NDArray
        An array of posterior samples.
    threshold : float, optional
        The threshold value to test against. Default is 0.0.
    adjustment : {0, 1}, optional
        Adjustment to apply to the Bayes factor calculation. Default is 0.

    Returns
    -------
    float
        Bayes factor in favour of the posterior mass being above
        ``threshold``.

    See Also
    --------
    as_pvalue : Convert a Bayes factor to a p-value.

    as_bf : Convert a p-value to a Bayes factor.

    Notes
    -----
    If all posterior draws exceed ``threshold``, the denominator is zero and
    the returned Bayes factor can become infinite. ``adjustment`` can be used
    to regularize this edge case in finite samples.

    References
    ----------
    .. [1] Marsman, Maarten, and Eric-Jan Wagenmakers. "Three Insights from a
       Bayesian Interpretation of the One-Sided P Value." *Educational and
       Psychological Measurement*, vol. 77, no. 3, 2017, pp. 529-539.
       doi:10.1177/0013164416669201.

    Examples
    --------
    >>> import numpy as np
    >>> from samesame.bayes_factors import bayes_factor
    >>> posterior_samples = np.array([0.2, 0.5, 0.8, 0.9])
    >>> bayes_factor(posterior_samples, threshold=0.5)
    np.float64(1.0)
    >>> np.isinf(bayes_factor(posterior_samples, threshold=0.0))
    np.True_
    """
    return _bayes_factor(posterior, threshold, adjustment)