Skip to content

quivers.diagnostics.posterior_tables

The table functions reproduce brms's posterior_summary, posterior_interval, predictive_interval, and posterior_table (BΓΌrkner, 2017) on retained (chain, draw, ...) draws. Chains are pooled. Missing values are removed per coordinate, as R's na.rm = TRUE does. Quantiles interpolate linearly between order statistics (R's type 7), and the robust dispersion is R's mad, the median absolute deviation scaled by 1.4826. Every result is a SummaryTable with labeled rows and statistic columns, and a component axis for brms's three-way arrays. The analysis guide shows the fit methods built on these tables.

posterior_tables

brms-style summary tables over retained draws.

The functions here reproduce the table layouts of brms's posterior_summary, posterior_interval, predictive_interval, and posterior_table [@burkner2017brms]. Every input keeps its chain and draw axes, (chain, draw, ...), and every function pools them, as brms pools the draws of all chains. Missing values (NaN) are removed per coordinate before summarizing, as R's na.rm = TRUE does; infinite draws are retained. Quantiles use linear interpolation between order statistics (R's type 7), and the robust dispersion is R's mad, the median absolute deviation scaled by the constant 1.4826.

MAD_CONSTANT module-attribute

MAD_CONSTANT = 1.4826

The consistency constant of R's mad, which scales the median absolute deviation to the standard deviation of a normal sample.

RowLabel

RowLabel = str | int

A table row identity: a variable name or an original observation label.

SummaryTable didactic-model

SummaryTable(*, rows: tuple[RowLabel, ...] = field(opaque=True, extras=OPAQUE_BY_VALUE), columns: tuple[str, ...], components: tuple[RowLabel, ...] = field(default=(), opaque=True, extras=OPAQUE_BY_VALUE), values: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY))

Bases: ValueModel

A labeled summary matrix or three-way array of retained draws.

Two-way tables have shape (row, column); three-way tables, which brms returns for vector-valued predictions and per-level coefficients, have shape (row, column, component).

PARAMETER DESCRIPTION
rows

Row labels: variable names or observation identities.

TYPE: tuple[str or int, ...] DEFAULT: field(opaque=True, extras=OPAQUE_BY_VALUE)

columns

Statistic labels, for instance ("Estimate", "Est.Error", "Q2.5", "Q97.5").

TYPE: tuple[str, ...]

components

Labels of the third axis, empty for a two-way table.

TYPE: tuple[str or int, ...] DEFAULT: field(default=(), opaque=True, extras=OPAQUE_BY_VALUE)

values

Float64 statistics in row, column, and component order.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

value

value(row: RowLabel, column: str, component: RowLabel | None = None) -> float

Read one statistic by its labels.

PARAMETER DESCRIPTION
row

Row label.

TYPE: str or int

column

Statistic label.

TYPE: str

component

Component label of a three-way table; None for a two-way table.

TYPE: str or int or None DEFAULT: None

RETURNS DESCRIPTION
float

The selected statistic.

RAISES DESCRIPTION
KeyError

If a label is unknown, or a component is required or not allowed.

Source code in src/quivers/diagnostics/posterior_tables.py
def value(
    self, row: RowLabel, column: str, component: RowLabel | None = None
) -> float:
    """Read one statistic by its labels.

    Parameters
    ----------
    row : str or int
        Row label.
    column : str
        Statistic label.
    component : str or int or None
        Component label of a three-way table; None for a two-way table.

    Returns
    -------
    float
        The selected statistic.

    Raises
    ------
    KeyError
        If a label is unknown, or a component is required or not allowed.
    """
    if (component is None) != (not self.components):
        raise KeyError("select a component exactly for a three-way table")
    try:
        index = (self.rows.index(row), self.columns.index(column))
        if component is not None:
            index += (self.components.index(component),)
    except ValueError as error:
        raise KeyError(f"unknown summary label: {error}") from error
    return float(self.values[index].item())

to_frame

to_frame(component: RowLabel | None = None) -> DataFrame

Return a two-way table, or one component slice, as a DataFrame.

PARAMETER DESCRIPTION
component

Component of a three-way table; None for a two-way table.

TYPE: str or int or None DEFAULT: None

RETURNS DESCRIPTION
DataFrame

Rows indexed by rows, columns named by columns.

RAISES DESCRIPTION
KeyError

If a component is required, not allowed, or unknown.

Source code in src/quivers/diagnostics/posterior_tables.py
def to_frame(self, component: RowLabel | None = None) -> pd.DataFrame:
    """Return a two-way table, or one component slice, as a DataFrame.

    Parameters
    ----------
    component : str or int or None
        Component of a three-way table; None for a two-way table.

    Returns
    -------
    pandas.DataFrame
        Rows indexed by `rows`, columns named by `columns`.

    Raises
    ------
    KeyError
        If a component is required, not allowed, or unknown.
    """
    if (component is None) != (not self.components):
        raise KeyError("select a component exactly for a three-way table")
    values = self.values
    if component is not None:
        if component not in self.components:
            raise KeyError(f"unknown component {component!r}")
        values = values[..., self.components.index(component)]
    return pd.DataFrame(
        values.cpu().numpy(), index=list(self.rows), columns=list(self.columns)
    )

posterior_summary

posterior_summary(draws: Mapping[str, Tensor] | Tensor, *, probs: Sequence[float] = (0.025, 0.975), robust: bool = False, labels: Sequence[RowLabel] | None = None, components: Sequence[RowLabel] | None = None) -> SummaryTable

Summarize draws with brms's posterior_summary layout.

PARAMETER DESCRIPTION
draws

Named variables (chain, draw, *event), or positional draws (chain, draw, row) or (chain, draw, row, component).

TYPE: Mapping[str, Tensor] or Tensor

probs

Quantile probabilities strictly between zero and one.

TYPE: Sequence[float] DEFAULT: (0.025, 0.975)

robust

Report the median and R's mad instead of the mean and SD.

TYPE: bool DEFAULT: False

labels

Row labels of a positional tensor; 0-based positions by default.

TYPE: Sequence[str or int] or None DEFAULT: None

components

Labels of a positional tensor's component axis; 0-based by default.

TYPE: Sequence[str or int] or None DEFAULT: None

RETURNS DESCRIPTION
SummaryTable

Columns Estimate, Est.Error and Q<100 p>. A four-axis tensor gives brms's N x E x C array with a component axis.

RAISES DESCRIPTION
ValueError

If probabilities, labels, or draw axes are invalid.

TypeError

If draws are not real tensors.

Notes

Cost is O(S M log S) for S pooled draws and M summarized coordinates.

Source code in src/quivers/diagnostics/posterior_tables.py
def posterior_summary(
    draws: Mapping[str, torch.Tensor] | torch.Tensor,
    *,
    probs: Sequence[float] = (0.025, 0.975),
    robust: bool = False,
    labels: Sequence[RowLabel] | None = None,
    components: Sequence[RowLabel] | None = None,
) -> SummaryTable:
    """Summarize draws with brms's ``posterior_summary`` layout.

    Parameters
    ----------
    draws : Mapping[str, torch.Tensor] or torch.Tensor
        Named variables ``(chain, draw, *event)``, or positional draws
        ``(chain, draw, row)`` or ``(chain, draw, row, component)``.
    probs : Sequence[float]
        Quantile probabilities strictly between zero and one.
    robust : bool
        Report the median and R's ``mad`` instead of the mean and SD.
    labels : Sequence[str or int] or None
        Row labels of a positional tensor; 0-based positions by default.
    components : Sequence[str or int] or None
        Labels of a positional tensor's component axis; 0-based by default.

    Returns
    -------
    SummaryTable
        Columns ``Estimate``, ``Est.Error`` and ``Q<100 p>``. A four-axis
        tensor gives brms's ``N x E x C`` array with a component axis.

    Raises
    ------
    ValueError
        If probabilities, labels, or draw axes are invalid.
    TypeError
        If draws are not real tensors.

    Notes
    -----
    Cost is O(S M log S) for S pooled draws and M summarized coordinates.
    """
    levels = probabilities(probs)
    if type(robust) is not bool:
        raise TypeError("robust must be Boolean")
    rows, pooled = _matrix(draws, labels, "posterior_summary")
    statistics = _statistics(pooled, levels, robust).transpose(0, 1)
    columns = ("Estimate", "Est.Error", *(f"Q{_percent(100 * p)}" for p in levels))
    if pooled.ndim == 3:
        names = (
            tuple(range(pooled.shape[2])) if components is None else tuple(components)
        )
        if len(names) != pooled.shape[2]:
            raise ValueError("posterior_summary requires one label per component")
        return SummaryTable(
            rows=rows, columns=columns, components=names, values=statistics
        )
    if components is not None:
        raise ValueError("component labels require a component axis")
    return SummaryTable(rows=rows, columns=columns, values=statistics)

posterior_interval

posterior_interval(draws: Mapping[str, Tensor] | Tensor, *, prob: float = 0.95, labels: Sequence[RowLabel] | None = None) -> SummaryTable

Compute central posterior intervals, as brms posterior_interval.

PARAMETER DESCRIPTION
draws

Named variables (chain, draw, *event) or positional draws (chain, draw, row).

TYPE: Mapping[str, Tensor] or Tensor

prob

Central probability mass, 0.95 by default as in brms.

TYPE: float DEFAULT: 0.95

labels

Row labels of a positional tensor.

TYPE: Sequence[str or int] or None DEFAULT: None

RETURNS DESCRIPTION
SummaryTable

Columns 2.5% and 97.5% for the default mass.

Source code in src/quivers/diagnostics/posterior_tables.py
def posterior_interval(
    draws: Mapping[str, torch.Tensor] | torch.Tensor,
    *,
    prob: float = 0.95,
    labels: Sequence[RowLabel] | None = None,
) -> SummaryTable:
    """Compute central posterior intervals, as brms ``posterior_interval``.

    Parameters
    ----------
    draws : Mapping[str, torch.Tensor] or torch.Tensor
        Named variables ``(chain, draw, *event)`` or positional draws
        ``(chain, draw, row)``.
    prob : float
        Central probability mass, 0.95 by default as in brms.
    labels : Sequence[str or int] or None
        Row labels of a positional tensor.

    Returns
    -------
    SummaryTable
        Columns ``2.5%`` and ``97.5%`` for the default mass.
    """
    return _interval(draws, prob, labels, "posterior_interval")

predictive_interval

predictive_interval(draws: Tensor, *, prob: float = 0.9, labels: Sequence[RowLabel] | None = None) -> SummaryTable

Compute central predictive intervals, as brms predictive_interval.

PARAMETER DESCRIPTION
draws

Predictive draws (chain, draw, row).

TYPE: Tensor

prob

Central probability mass, 0.9 by default as in brms.

TYPE: float DEFAULT: 0.9

labels

Row labels; 0-based positions by default.

TYPE: Sequence[str or int] or None DEFAULT: None

RETURNS DESCRIPTION
SummaryTable

Columns 5% and 95% for the default mass.

Source code in src/quivers/diagnostics/posterior_tables.py
def predictive_interval(
    draws: torch.Tensor,
    *,
    prob: float = 0.9,
    labels: Sequence[RowLabel] | None = None,
) -> SummaryTable:
    """Compute central predictive intervals, as brms ``predictive_interval``.

    Parameters
    ----------
    draws : torch.Tensor
        Predictive draws ``(chain, draw, row)``.
    prob : float
        Central probability mass, 0.9 by default as in brms.
    labels : Sequence[str or int] or None
        Row labels; 0-based positions by default.

    Returns
    -------
    SummaryTable
        Columns ``5%`` and ``95%`` for the default mass.
    """
    return _interval(draws, prob, labels, "predictive_interval")

posterior_table

posterior_table(draws: Tensor, *, levels: Sequence[float | int | str] | None = None, labels: Sequence[RowLabel] | None = None) -> SummaryTable

Tabulate relative frequencies of discrete draws, as brms posterior_table.

PARAMETER DESCRIPTION
draws

Discrete draws (chain, draw, row), such as ordinal predictions.

TYPE: Tensor

levels

Possible values in column order; None uses every distinct non-missing value in ascending order. A string sequence labels the columns of integer codes 0..K-1.

TYPE: Sequence or None DEFAULT: None

labels

Row labels; 0-based positions by default.

TYPE: Sequence[str or int] or None DEFAULT: None

RETURNS DESCRIPTION
SummaryTable

Columns P(Y = <level>) holding each row's frequencies among its non-missing draws.

RAISES DESCRIPTION
ValueError

If draws contain a value outside the given levels.

Source code in src/quivers/diagnostics/posterior_tables.py
def posterior_table(
    draws: torch.Tensor,
    *,
    levels: Sequence[float | int | str] | None = None,
    labels: Sequence[RowLabel] | None = None,
) -> SummaryTable:
    """Tabulate relative frequencies of discrete draws, as brms ``posterior_table``.

    Parameters
    ----------
    draws : torch.Tensor
        Discrete draws ``(chain, draw, row)``, such as ordinal predictions.
    levels : Sequence or None
        Possible values in column order; None uses every distinct non-missing
        value in ascending order. A string sequence labels the columns of
        integer codes ``0..K-1``.
    labels : Sequence[str or int] or None
        Row labels; 0-based positions by default.

    Returns
    -------
    SummaryTable
        Columns ``P(Y = <level>)`` holding each row's frequencies among its
        non-missing draws.

    Raises
    ------
    ValueError
        If draws contain a value outside the given levels.
    """
    rows, pooled = _matrix(draws, labels, "posterior_table")
    if pooled.ndim != 2:
        raise ValueError("posterior_table requires one value per row and draw")
    present = ~torch.isnan(pooled)
    if levels is None:
        values = torch.unique(pooled[present]).tolist()
        names = [
            _percent(v) if not float(v).is_integer() else str(int(v)) for v in values
        ]
    else:
        given = tuple(levels)
        if all(isinstance(level, str) for level in given):
            values = [float(code) for code in range(len(given))]
            names = [str(level) for level in given]
        else:
            values = [float(level) for level in given]
            names = [
                _percent(float(v)) if not float(v).is_integer() else str(int(v))
                for v in given
            ]
    counts = torch.stack([(pooled == value).sum(0) for value in values], dim=1)
    total = present.sum(0)
    if bool((counts.sum(1) != total).any()):
        raise ValueError("posterior_table draws contain values outside the levels")
    return SummaryTable(
        rows=rows,
        columns=tuple(f"P(Y = {name})" for name in names),
        values=counts.to(torch.float64) / total.unsqueeze(1),
    )

Cited sources

Paul-Christian BΓΌrkner. brms: An R Package for Bayesian Multilevel Models Using Stan. Journal of Statistical Software, 2017. doi:10.18637/jss.v080.i01.