Skip to content

quivers.diagnostics.comparison

Pointwise PSIS-LOO and model comparison via ArviZ.

comparison

Model comparison and PSIS-LOO via ArviZ.

Thin wrappers around the canonical ArviZ entry points with quivers-typed inputs. No information-criterion or PSIS math lives here; ArviZ is the source of truth.

compare 

compare(fits: Mapping[str, DataTree], *, method: Literal['stacking', 'BB-pseudo-BMA', 'pseudo-BMA'] = 'stacking', var_name: str | None = None, reference: str | None = None, round_to: int | Literal['auto', 'none', 'None'] | None = 'auto') -> object

Rank candidate models by expected log predictive density.

Delegates to ArviZ, which computes PSIS-LOO on each fit's log-likelihood group and combines the results into a ranked comparison table.

PARAMETER DESCRIPTION
fits

Per-model fits produced by quivers.diagnostics.to_datatree. Every fit must carry a log-likelihood group.

TYPE: Mapping[str, DataTree]

method

Model-weight estimator. Default "stacking" follows Yao, Vehtari, Simpson, and Gelman (2018).

TYPE: "stacking", "BB-pseudo-BMA", or "pseudo-BMA" DEFAULT: 'stacking'

var_name

Observed variable in the log-likelihood group; required when a fit carries multiple log-likelihood variables.

TYPE: str DEFAULT: None

reference

Fit name used as the reference for ELPD differences. Default is the top-ranked model.

TYPE: str DEFAULT: None

round_to

ArviZ rounding policy. Default "auto" retains display rounding. An integer specifies decimal places, while "none" or "None" preserves full numeric precision. None uses ArviZ's configured default.

TYPE: int, "auto", "none", "None", or None DEFAULT: 'auto'

RETURNS DESCRIPTION
DataFrame

ArviZ ranking table with one row per model.
Source code in src/quivers/diagnostics/comparison.py 
16
17
18
19
20
21
22
23
24
25
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
def compare(
    fits: Mapping[str, xr.DataTree],
    *,
    method: Literal["stacking", "BB-pseudo-BMA", "pseudo-BMA"] = "stacking",
    var_name: str | None = None,
    reference: str | None = None,
    round_to: int | Literal["auto", "none", "None"] | None = "auto",
) -> object:
    """Rank candidate models by expected log predictive density.

    Delegates to ArviZ, which computes PSIS-LOO on each fit's
    log-likelihood group and combines the results into a ranked
    comparison table.

    Parameters
    ----------
    fits : Mapping[str, xr.DataTree]
        Per-model fits produced by quivers.diagnostics.to_datatree.
        Every fit must carry a log-likelihood group.
    method : "stacking", "BB-pseudo-BMA", or "pseudo-BMA"
        Model-weight estimator. Default "stacking" follows Yao,
        Vehtari, Simpson, and Gelman (2018).
    var_name : str, optional
        Observed variable in the log-likelihood group; required
        when a fit carries multiple log-likelihood variables.
    reference : str, optional
        Fit name used as the reference for ELPD differences.
        Default is the top-ranked model.
    round_to : int, "auto", "none", "None", or None, optional
        ArviZ rounding policy. Default "auto" retains display
        rounding. An integer specifies decimal places, while
        "none" or "None" preserves full numeric precision. None
        uses ArviZ's configured default.

    Returns
    -------
    pandas.DataFrame
        ArviZ ranking table with one row per model.
    """
    return az.compare(
        dict(fits),
        method=method,
        var_name=var_name,
        reference=reference,
        round_to=round_to,
    )

loo 

loo(fit: DataTree, *, pointwise: bool | None = None, var_name: str | None = None) -> object

Estimate expected log predictive density with PSIS-LOO.

This thin wrapper delegates all computation to ArviZ. It preserves ArviZ's canonical log scale and, with pointwise=True, returns its per-observation elpd_i and pareto_k arrays unchanged, including nonfinite Pareto estimates.

PARAMETER DESCRIPTION
fit

Fit containing posterior and log-likelihood groups.

TYPE: DataTree

pointwise

Whether to include one elpd_i and pareto_k value per observation. None uses ArviZ's configured default.

TYPE: bool DEFAULT: None

var_name

Log-likelihood variable to evaluate. Required when the log-likelihood group contains multiple variables.

TYPE: str DEFAULT: None

RETURNS DESCRIPTION
ELPDData

ArviZ's canonical PSIS-LOO result.
Source code in src/quivers/diagnostics/comparison.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
def loo(
    fit: xr.DataTree,
    *,
    pointwise: bool | None = None,
    var_name: str | None = None,
) -> object:
    """Estimate expected log predictive density with PSIS-LOO.

    This thin wrapper delegates all computation to ArviZ. It
    preserves ArviZ's canonical log scale and, with pointwise=True,
    returns its per-observation elpd_i and pareto_k arrays unchanged,
    including nonfinite Pareto estimates.

    Parameters
    ----------
    fit : xr.DataTree
        Fit containing posterior and log-likelihood groups.
    pointwise : bool, optional
        Whether to include one elpd_i and pareto_k value per
        observation. None uses ArviZ's configured default.
    var_name : str, optional
        Log-likelihood variable to evaluate. Required when the
        log-likelihood group contains multiple variables.

    Returns
    -------
    arviz.ELPDData
        ArviZ's canonical PSIS-LOO result.
    """
    _require_log_likelihood_variable(fit, var_name)
    return az.loo(fit, pointwise=pointwise, var_name=var_name)