categorical_accessors: Observation-level accessors for categorical fits

In tulpa: Templated Unified Library for Posterior Approximation in Bayesian Hierarchical Models

Observation-level accessors for categorical fits

Description

stats::fitted(), stats::residuals(), stats::predict() and posterior_predict() for a categorical response: a tulpa_multinomial() fit (family = "multinomial") or a tulpa_ordinal() fit (family = "ordinal"). The response is one of K classes, so the response-scale quantities are N x K matrices with one column per class.

• fitted() returns the class probabilities at the posterior mode.

• residuals() returns, per class, the indicator of the observed class minus its fitted probability ("response"), or that difference divided by the indicator's standard deviation sqrt(p (1 - p)) ("pearson"). A categorical response has no single scalar residual; each class column is the Bernoulli residual of that class's indicator.

• predict() returns the link scale – the K - 1 baseline-category logits of the multinomial model (N x (K - 1)), or the ordinal location predictor ⁠x' beta⁠ (length N) – or the class probabilities (type = "response").

• posterior_predict() draws one class per observation for each posterior draw and returns the class indices, with the response levels attached; simulate.tulpa_fit() turns them into factor columns.

The pointwise log-likelihood behind cpo(), dic(), loo::waic() and loo::loo() is the log probability of each observed class at each stored posterior draw; dic() evaluates it at the posterior-mean parameters.

Usage

## S3 method for class 'tulpa_categorical'
fitted(object, ...)

## S3 method for class 'tulpa_categorical'
residuals(object, type = c("pearson", "response"), ...)

## S3 method for class 'tulpa_categorical'
predict(
  object,
  newdata = NULL,
  type = c("link", "response"),
  se.fit = FALSE,
  level = 0.95,
  ...
)

## S3 method for class 'tulpa_categorical'
posterior_predict(object, newdata = NULL, ndraws = NULL, seed = NULL, ...)

## S3 method for class 'tulpa_categorical'
pp_check(object, ndraws = 50, ...)

Arguments

object	A tulpa_multinomial or tulpa_ordinal fit.
...	Ignored.
type	For residuals(), "pearson" (default) or "response". For predict(), "link" (default) or "response".
newdata	Optional data frame of covariates; NULL uses the training design.
se.fit	For predict(), also return standard errors and credible bounds. On the link scale the standard error is exact for the Gaussian (Laplace) posterior, ⁠sqrt(a' V a)⁠, with Gaussian bounds; on the response scale the standard error and the bounds are the posterior SD and quantiles of each class probability over the fit's posterior draws.
level	Credible-interval level (default 0.95).
ndraws	Number of posterior draws for posterior_predict(); defaults to all stored draws.
seed	Optional integer seed (RNG state is restored on exit).

Value

fitted(): an N x K probability matrix. residuals(): an N x K matrix. predict(): a matrix (or, for the ordinal link scale, a vector); with se.fit = TRUE a list of fit, se.fit, lower, upper of that shape. posterior_predict(): an ⁠ndraws x N⁠ integer matrix of class indices with attributes levels and ordered.

See Also

tulpa_multinomial(), tulpa_ordinal()

tulpa documentation built on Oct. 19, 2026, 5:09 p.m.