pseudo_opt: Optimal pseudo-target for a given target
In qslice: Implementations of Various Slice Samplers

pseudo_opt

R Documentation

Optimal pseudo-target for a given target

Description

Find an optimal pseudo-target in a specified family to approximate the given (unnormalized) target (Heiner et al., 2026+). Optimize over the selected utility function.

Usage

pseudo_opt(
  log_target = NULL,
  samples = NULL,
  type = "samples",
  family = "t",
  df = NULL,
  lb = -Inf,
  ub = Inf,
  utility_type = "AUC",
  nbins = 100,
  tol_opt = 1e-06,
  init_fn = NULL,
  utility_options = list(tol_int = 0.001, n_opt = 10, interval_opt = c(1e-06, 0.999999),
    diagnostics = NULL),
  plot = TRUE,
  verbose = FALSE,
  degf = NULL
)

Arguments

`log_target`	Function to evaluate the log density of the unnormalized univariate target.
`samples`	Optional numeric vector providing samples from the target distribution (for use as alternative to `log_target`).
`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`. Use of "samples" requires specification of `samples`. Use of "grid" requires specification of `log_target`.
`family`	String specifying the family of distributions for the pseudo-target. Can be any of the families accepted by pseudo_list.
`df`	Numeric vector of degrees of freedom values to try (only if `family = "t"`). Defaults to `c(1, 5, 20)`.
`lb`	Numeric scalar giving the value of left truncation. Defaults to `-Inf`.
`ub`	Numeric scalar giving the value of right truncation. Defaults to `Inf`.
`utility_type`	String identifying utility type, either AUC (default) or MSW.
`nbins`	Positive integer specifying the number of histogram bins if using "samples" or "grid". Defaults to 100.
`tol_opt`	Positive numeric scalar that passes to `reltol` in the call to optim. Defaults to `1.0e-6`.
`init_fn`	Function with no arguments that returns a vector of parameter values for the initial pseudo-target, usually consisting of a real-valued location parameter and a positive-valued scale parameter. If `init_fn` is `NULL` and `samples` are supplied, the sample mean and standard deviation are used; if `init_fn` is `NULL` and `samples` are not supplied, the vector `c(0.5, 3.0)` is used. Default is `NULL`.
`utility_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`.
`plot`	Logical for whether to generate two plots: direct comparison of the target and pseudo-target densities, and transformed target density. Defaults to `TRUE`.
`verbose`	Logical for whether to print intermediate steps of optimization. Defaults to `FALSE`.
`degf`	(deprecated) Numeric vector of degrees of freedom values to try (only if `family = "t"`). Use `df` instead.

Details

Optionally supply samples from the target distribution.

Value

A list with named components:

pseudo: a list with functions corresponding to the selected pseudo-target; output of pseudo_list.

utility: value of the utility function using the selected pseudo-target; output of utility_pseudo.

utility_type: repeats the input specifying the utility type.

opt: output of optim.

Other outputs repeating inputs.

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

oldpar <- par(mfrow = c(1,2))
(pseu <- pseudo_opt(samples = rnorm(1e3), type = "samples",
               family = "t", utility_type = "AUC",
               nbins = 10, plot = TRUE,
               verbose = FALSE))
(pseu <- pseudo_opt(log_target = function(x) dnorm(x, log = TRUE),
                type = "grid",
                family = "logistic", utility_type = "MSW",
                nbins = 30, plot = TRUE,
                verbose = FALSE))
(pseu <- pseudo_opt(log_target = function(x) dbeta(x, 4, 2, log = TRUE),
                lb = 0, ub = 1,
                type = "function",
                family = "cauchy", utility_type = "AUC",
                init_fn = function() {c(rbeta(1, 3.0, 3.0), rgamma(1, 3.0))},
                nbins = 30, plot = TRUE,
                verbose = FALSE))
par(oldpar)

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