utility_pseudo: Utility for a given univariate target and pseudo-target

In qslice: Implementations of Various Slice Samplers

Utility for a given univariate target and pseudo-target

Description

Takes a pseudo-target and target (or samples from the target) and evaluates the utility function for the transformed target, which can be one of Area Under the Curve (AUC) and Mean Slice Width (MSW). See Heiner et al. (2026+).

Usage

utility_pseudo(
  pseudo,
  log_target = NULL,
  samples = NULL,
  type = "samples",
  x = NULL,
  nbins = 30,
  plot = TRUE,
  utility_type = "AUC",
  options = list(tol_int = 0.001, n_opt = 10, interval_opt = c(1e-06, 0.999999),
    diagnostics = NULL)
)

Arguments

pseudo	List containing the following functions relating to the univariate pseudo-target, each with scalar input: ld: function to evaluate the log density q: function to evaluate the quantile function p: function to evaluate the distribution function
log_target	Function to evaluate the log density of the unnormalized univariate target.
samples	Numeric vector of samples from the target distribution.
type	String specifying the input type. One of "function", "samples", or "grid". Default is to use "samples". Use of "function" requires specification of log_target. Utility is calculated using numerical integration (integrate) and, additionally for AUC, optimization (optim). Use of "samples" requires specification of samples. Use of "grid" requires specification of log_target and optionally x. Grid method is useful if numerical optimization or integration fails when employed with type = "function".
x	Optional numeric vector specifying grid (on (0,1)) over which to evaluate the transformed target. Defaults to NULL.
nbins	Number of histogram bins to use (defaults to 30). Overridden by the length of x if x is supplied.
plot	Logical for whether to generate two plots: direct comparison of the target and pseudo-target densities, and transformed target density. Defaults to TRUE.
utility_type	String identifying utility type, either AUC (default) or MSW.
options	List containing the following. tol_int: Positive numeric scalar that passes to abs.tol in the call to integrate used for type = "function". n_opt: Positive integer giving the number of equally spaced initialization points for numerical optimization (optim) in AUC with type = "function". interval_opt: Numerical vector of length two giving the interval for numerical optimization (optim) in AUC with type = "function". diagnostics: Logical, indicating whether the target log-density and pseudo-target functions should be run in diagnostic mode for informative error handling. When diagnostics is NULL, it is reset to match the value of getOption("qslice.diagnostics") which defaults to FALSE if the option is not set. Default for diagnostics is NULL.

Details

Optionally plot the target and pseudo-target densities as well as the transformed target.

Value

Scalar value of the utility function evaluation.

References

Heiner, M. J., Johnson, S. B., Christensen, J. R., and Dahl, D. B. (2026+), "Quantile Slice Sampling," arXiv preprint arXiv:2407.12608 \Sexpr[results=rd]{tools:::Rd_expr_doi("https://doi.org/10.48550/arXiv.2407.12608")}

Examples

pseu <- pseudo_list(family = "t", params = list(loc = 0.25, sc = 1.0, df = 1))
ltargdens <- function(x) dnorm(x, log = TRUE)
oldpar <- par(mfrow = c(1,2))
utility_pseudo(pseudo = pseu, log_target = ltargdens, type = "function", utility_type = "MSW")
utility_pseudo(pseudo = pseu, log_target = ltargdens, type = "function", utility_type = "AUC")
samp <- rnorm(10e3)
utility_pseudo(pseudo = pseu, samples = samp, nbins = 30, type = "samples", utility_type = "MSW")
utility_pseudo(pseudo = pseu, samples = samp, nbins = 30, type = "samples", utility_type = "AUC")
par(oldpar)
pseu <- pseudo_list(family = "beta", params = list(shape1 = 1.5, shape2 = 1.5))
ltargdens <- function(x) dbeta(x, shape1 = 2.0, shape2 = 3.0, log = TRUE)
oldpar <- par(mfrow = c(1,2))
utility_pseudo(pseudo = pseu, log_target = ltargdens, type = "function", utility_type = "MSW")
utility_pseudo(pseudo = pseu, log_target = ltargdens, type = "function", utility_type = "AUC")
samp <- rbeta(10e3, shape1 = 2.0, shape2 = 3.0)
utility_pseudo(pseudo = pseu, samples = samp, nbins = 30, type = "samples", utility_type = "MSW")
utility_pseudo(pseudo = pseu, samples = samp, nbins = 30, type = "samples", utility_type = "AUC")
par(oldpar)

qslice documentation built on Oct. 22, 2026, 1:06 a.m.