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
¶
The consistency constant of R's mad, which scales the median absolute
deviation to the standard deviation of a normal sample.
RowLabel
¶
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:
|
columns
|
Statistic labels, for instance
TYPE:
|
components
|
Labels of the third axis, empty for a two-way table.
TYPE:
|
values
|
Float64 statistics in row, column, and component order.
TYPE:
|
value
¶
Read one statistic by its labels.
| PARAMETER | DESCRIPTION |
|---|---|
row
|
Row label.
TYPE:
|
column
|
Statistic label.
TYPE:
|
component
|
Component label of a three-way table; None for a two-way table.
TYPE:
|
| 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
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:
|
| RETURNS | DESCRIPTION |
|---|---|
DataFrame
|
Rows indexed by |
| RAISES | DESCRIPTION |
|---|---|
KeyError
|
If a component is required, not allowed, or unknown. |
Source code in src/quivers/diagnostics/posterior_tables.py
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 |
probs
|
Quantile probabilities strictly between zero and one.
TYPE:
|
robust
|
Report the median and R's
TYPE:
|
labels
|
Row labels of a positional tensor; 0-based positions by default.
TYPE:
|
components
|
Labels of a positional tensor's component axis; 0-based by default.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SummaryTable
|
Columns |
| 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
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 |
prob
|
Central probability mass, 0.95 by default as in brms.
TYPE:
|
labels
|
Row labels of a positional tensor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SummaryTable
|
Columns |
Source code in src/quivers/diagnostics/posterior_tables.py
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
TYPE:
|
prob
|
Central probability mass, 0.9 by default as in brms.
TYPE:
|
labels
|
Row labels; 0-based positions by default.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SummaryTable
|
Columns |
Source code in src/quivers/diagnostics/posterior_tables.py
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
TYPE:
|
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
TYPE:
|
labels
|
Row labels; 0-based positions by default.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SummaryTable
|
Columns |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If draws contain a value outside the given levels. |
Source code in src/quivers/diagnostics/posterior_tables.py
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.