`barracuda.evidence`¶

Directed model-evidence helpers. Positive log_BF_A_vs_B values support A. Savage–Dickey bf_01 supports the point null and bf_10 supports the alternative.

Model-evidence and Bayes-factor utilities.

The inference workflows return log marginal likelihoods because their raw Bayes factors can overflow even for moderately decisive comparisons. This module keeps calculations in log space for as long as possible and provides tables that can be used with event-count and trajectory results alike.

Attributes¶

LOG_10 `module-attribute` ¶

LOG_10: Final[float] = float(np.log(10.0))

_MAX_EXPONENT `module-attribute` ¶

_MAX_EXPONENT: Final[float] = float(np.log(np.finfo(float).max))

_MIN_EXPONENT `module-attribute` ¶

_MIN_EXPONENT: Final[float] = float(np.log(np.nextafter(0.0, 1.0)))

all `module-attribute` ¶

__all__ = ['SavageDickeyResult', 'bayes_factor', 'classify_bayes_factor', 'combine_independent_evidence', 'evidence_from_inference_data', 'history_effect_bayes_factors', 'log_bayes_factor', 'pairwise_bayes_factors', 'posterior_model_probabilities', 'savage_dickey_ratio', 'smc_log_evidence']

Classes¶

SavageDickeyResult `dataclass` ¶

SavageDickeyResult(parameter: str, reference: float, prior_density: float, posterior_density: float, bf_01: float, bf_10: float, log_bf_10: float)

Density-ratio evidence for a point null nested in a larger model.

bf_01 supports the point null and bf_10 supports the alternative. The calculation assumes that the nuisance-parameter priors under both models are compatible, as required by the Savage--Dickey identity.

Methods:¶

as_dict ¶

as_dict() -> dict[str, float | str]

Return a serialization-friendly representation.

Functions:¶

_finite_number ¶

_finite_number(value: Any, name: str) -> float

_validated_log_evidence ¶

_validated_log_evidence(log_evidence: Mapping[str, float]) -> dict[str, float]

_safe_exp ¶

_safe_exp(value: float) -> float

log_bayes_factor ¶

log_bayes_factor(log_evidence_1: float, log_evidence_2: float) -> float

Return log p(data|model_1) - log p(data|model_2).

Positive values favour model 1, negative values favour model 2, and zero means equal evidence under the fitted priors.

bayes_factor ¶

bayes_factor(log_evidence_1: float, log_evidence_2: float) -> float

Return the Bayes factor for model 1 against model 2.

Very large values are returned as inf and underflowing values as 0.0. Use :func:log_bayes_factor for lossless downstream work.

classify_bayes_factor ¶

classify_bayes_factor(log_bf: float) -> str

Describe evidence strength using Kass--Raftery log-BF thresholds.

The magnitude thresholds are 1, 3, and 5 natural-log units. The returned label describes strength only; inspect the sign to determine which model is favoured.

pairwise_bayes_factors ¶

pairwise_bayes_factors(log_evidence: Mapping[str, float], *, model_order: Sequence[str] | None = None) -> DataFrame

Compare every pair of models from a log-evidence mapping.

Parameters:

Name	Type	Description	Default
`log_evidence`	`Mapping[str, float]`	Mapping from model identifiers to finite log marginal likelihoods.	required
`model_order`	`Sequence[str] \| None`	Optional comparison order. It must name every supplied model exactly once. When omitted, insertion order is preserved.	`None`

Returns:

Type	Description
`DataFrame`	One row per unordered pair. Positive `log_BF_1_vs_2` values favour `model_1`. Both natural-log and base-10 representations are kept so plots never need to reconstruct them from rounded raw factors.

posterior_model_probabilities ¶

posterior_model_probabilities(log_evidence: Mapping[str, float], *, prior_probabilities: Mapping[str, float] | None = None) -> DataFrame

Convert model evidence and model priors into posterior probabilities.

Equal model priors are used by default. User-supplied priors are normalized after validation, so they may be probabilities or positive relative weights.

combine_independent_evidence ¶

combine_independent_evidence(evidence: DataFrame, *, model_column: str = 'model_key', log_evidence_column: str = 'log_evidence', dataset_columns: Sequence[str] | str | None = None, require_complete: bool = True) -> DataFrame

Sum log evidence across independent datasets for each model.

The caller is responsible for the scientific independence assumption. A common use is to combine condition-wise model comparisons after fitting the same candidate set separately to each condition. When condition is present it is used as the dataset identifier automatically. Complete and duplicate-free model coverage is required by default, preventing a model from winning merely because a difficult dataset was omitted.

smc_log_evidence ¶

smc_log_evidence(idata: Any) -> float

Return the mean final SMC log evidence across finite chains.

evidence_from_inference_data ¶

evidence_from_inference_data(idatas: Mapping[str, Any]) -> DataFrame

Build a ranked evidence table directly from InferenceData objects.

savage_dickey_ratio ¶

savage_dickey_ratio(idata: Any, parameter: str, *, reference: float = 0.0, bandwidth: str | float | None = None) -> SavageDickeyResult

Estimate a Savage--Dickey Bayes factor from prior/posterior draws.

idata must contain scalar draws for parameter in both its prior and posterior groups. Gaussian kernel density estimates are evaluated at reference. For bounded parameters or boundary nulls, use a method designed for boundary correction instead of this helper.

history_effect_bayes_factors ¶

history_effect_bayes_factors(idata: Any, *, parameters: Sequence[str] = ('beta_f', 'beta_s'), reference: float = 0.0, bandwidth: str | float | None = None) -> DataFrame

Evaluate point-null Bayes factors for trajectory history effects.

Public names beta_f and beta_s are translated to the research backend's beta_x and beta_y variables when necessary. Parameters that are absent from either the prior or posterior are omitted, which makes the function safe across history-independent model results.

barracuda.evidence¶