tulpa_psis: Pareto-smoothed importance sampling

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

Pareto-smoothed importance sampling

Description

Smooths a set of importance ratios by replacing the largest weights with the order statistics of a generalized-Pareto fit to their upper tail, and returns the Pareto shape diagnostic pareto_k together with the smoothed (normalized) log weights and their importance-sampling effective sample size. pareto_k estimates the number of finite moments of the raw weight distribution: ⁠< 0.5⁠ is good (finite variance). The usable upper boundary is sample-size dependent, min(1 - 1/log10(S), 0.7) for S draws (Vehtari et al. 2024): about 0.565 at S = 200, reaching the 0.7 cap only past S ~ 2154. Above it the proposal cannot be reliably corrected to the target.

Usage

tulpa_psis(log_ratios, tail_points = NULL)

Arguments

log_ratios	Numeric vector of (unnormalized) log importance ratios ⁠log p_target(x) - log q_proposal(x)⁠ evaluated at draws x ~ q. -Inf marks a draw of zero weight (it keeps its place and counts towards S); NA / NaN is an error. A +Inf ratio is the worst possible one and returns pareto_k = Inf with all the weight on the +Inf draws.
tail_points	Number of upper-tail order statistics for the generalized-Pareto fit, or NULL (default) for the automatic PSIS rule ceil(min(0.2 * S, 3 * sqrt(S))). An explicit value is an expert tail-threshold control, capped at floor(0.2 * S) so the fit stays an extreme tail; it is NOT a precision knob (raise the draw count for a tighter shape estimate).

Value

A list with pareto_k (the tail shape, NA if the sample is too small to fit), is_ess (importance-sampling effective sample size, 1 / sum(w^2) on the normalized smoothed weights), log_weights (the normalized smoothed log weights, one per element of log_ratios and in the same order; with fewer than 5 draws the raw ratios, normalized), tail_len (the tail size used, 0 when no tail was fitted), and tail_smoothed (FALSE when the tail kept its raw log ratios because the generalized-Pareto fit was not attempted or returned a shape / scale the quantile function is undefined at; pareto_k then reports the attempted fit and does not describe the returned weights).

References

Vehtari, Simpson, Gelman, Yao & Gabry (2024). Pareto smoothed importance sampling. JMLR 25(72):1-58.

See Also

diagnostics() for the fit-level diagnostic front door.

Examples

set.seed(1)
# Well-behaved importance ratios: k-hat is small.
ps <- tulpa_psis(rnorm(2000))
ps$pareto_k
ps$is_ess

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