pit_residuals: PIT (probability integral transform) residuals

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

PIT (probability integral transform) residuals

Description

For each observation, computes the quantile of the observed value within the posterior predictive distribution. If the model is correct, PIT residuals follow Uniform(0, 1).

Usage

pit_residuals(object, ...)

## Default S3 method:
pit_residuals(object, observed = NULL, nsim = 250L, seed = 123L, ...)

Arguments

object	A fitted model with a simulate() method, or a matrix of simulated values (n_obs x nsim)
...	Passed to methods.
observed	Observed response vector (required if object is a matrix)
nsim	Number of simulations (default 250)
seed	Random seed (default 123)

Details

For integer-valued responses, a randomisation step avoids discrete artefacts: the residual is drawn uniformly between P(sim < obs) and P(sim <= obs).

Value

Numeric vector of length n_obs with values in ⁠[0, 1]⁠

Examples

# From a matrix of replicates (n_obs x nsim) and the observed response:
set.seed(1)
y <- rpois(30, 3)
sims <- matrix(rpois(30 * 100, 3), nrow = 30)
r <- pit_residuals(sims, observed = y)
summary(r)

# From a fitted model with a simulate() method:
set.seed(1)
d <- data.frame(x = rnorm(80))
d$y <- rpois(80, exp(0.3 + 0.5 * d$x))
fit <- tulpa(y ~ x, data = d, family = "poisson", mode = "laplace")
head(pit_residuals(fit, nsim = 50))

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