Exceedance probability from a fitted model

exceedance() returns Pr(Y > threshold | x) (or, with lower.tail = TRUE, Pr(Y <= threshold | x)) at a fitted model's per-row conditional distribution. It is a thin wrapper over the shared CDF exposed by fitted_distribution(): 1 - fitted_distribution(object, newdata)$p(threshold) (or the p(threshold) complement for lower.tail = TRUE).

Usage

exceedance(object, threshold, newdata = NULL, lower.tail = FALSE, ...)

# S3 method for class 'drmTMB'
exceedance(
  object,
  threshold,
  newdata = NULL,
  lower.tail = FALSE,
  response = NULL,
  ...
)

Arguments

object: A drmTMB fit.
threshold: Numeric threshold c. Either a single value (recycled across rows) or one value per row of newdata (or per fitted row when newdata is omitted).
newdata: Optional data frame for prediction. If omitted, fitted rows are used; see fitted_distribution().
lower.tail: Logical. If FALSE (default), returns Pr(Y > threshold). If TRUE, returns Pr(Y <= threshold).
...: Reserved for future options.
response: For a bivariate biv_gaussian fit, 1 or 2, selecting which response's marginal exceedance to compute; see fitted_distribution(). Must be NULL (the default) for univariate model types.

Value

A numeric vector, one value per row, with attr(., "calibrated") == FALSE.

Details

threshold is evaluated with the standard CDF convention F(c) = Pr(Y <= c), so for atom-bearing families (e.g. Tweedie's point mass at y = 0) a threshold exactly at the atom includes that atom's mass in F(c): exceedance(fit, 0) (the default lower.tail = FALSE) excludes the atom at 0, matching Pr(Y > 0); exceedance(fit, 0, lower.tail = TRUE) recovers the atom mass Pr(Y <= 0) = Pr(Y == 0) when the family's support has no continuous mass below the atom.

This is a distributional (plug-in) output at predict_parameters()'s fixed-effect, population-level parameter estimates theta_hat: the result carries attr(., "calibrated") <- FALSE and does not propagate theta_hat uncertainty. See fitted_distribution() for the "spike"/"unimplemented" status gate this inherits (a "spike"-status family emits a one-time warning) and for the response argument's contract on a bivariate biv_gaussian fit (REQUIRED there: 1 or 2, selecting which response's MARGINAL exceedance to return; rho12 and any joint tail structure are ignored).

Examples

dat <- data.frame(y = c(0.2, 0.5, 1.1, 1.4), x = c(-1, -0.5, 0, 0.5))
fit <- drmTMB(bf(y ~ x, sigma ~ 1), data = dat)
exceedance(fit, threshold = 1)
#> [1] 0.000000e+00 4.921903e-10 5.592518e-01 1.000000e+00
#> attr(,"calibrated")
#> [1] FALSE
#> attr(,"lower.tail")
#> [1] FALSE
#> attr(,"threshold")
#> [1] 1 1 1 1