Empirical picp() minus nominal coverage level. Positive values mean
over-coverage and negative values mean under-coverage. The result is on the
probability scale; multiply by 100 for percentage points.
Usage
coverage_error(
obs,
lower = NULL,
upper = NULL,
level = 0.95,
na.rm = TRUE,
pred = NULL,
predictive_sd = NULL,
distribution = NULL
)Arguments
- obs
Numeric observation vector.
- lower, upper
Optional numeric lower and upper prediction-interval bounds. Supply both, without another input representation.
- level
Nominal central interval coverage, strictly between zero and one.
- na.rm
Logical; remove incomplete cases? See Input representations.
- pred, predictive_sd
Optional numeric vectors of predictive means and predictive standard deviations, supplied together and of the same length as
obs. Assumes normal predictive distributions. Non-missing predictive standard deviations must be finite and strictly positive.- distribution
Optional numeric matrix or data frame of equally weighted predictive samples: one row per observation and one column per predictive draw. Supply this instead of bounds or predictive means and standard deviations. At least one draw is required; infinite values are not allowed.
Details
$$\mathrm{PICP\ error}(\tau) = \mathrm{PICP}(\tau) - \tau$$
Zero is ideal. Positive values mean intervals cover too often (are too wide or over-pessimistic); negative values mean intervals cover too rarely.
Input representations
Supply exactly one of explicit lower and upper bounds, predictive mean
and standard deviation (pred and predictive_sd), or predictive samples
(distribution). Normal inputs generate central intervals using normal
quantiles. Samples generate equal-tailed intervals using stats::quantile()
with type = 7, at probabilities (1 - level) / 2 and (1 + level) / 2.
With na.rm = TRUE, a case is removed if its observation or any supplied
predictive value is missing; individual missing draws are not discarded
within a case. With na.rm = FALSE, incomplete inputs give NA. No complete
cases also gives NA. Standalone interval_width() ignores missing obs.
References
Schmidinger, J. and Heuvelink, G. B. M. (2023). Validation of uncertainty predictions in digital soil mapping. Geoderma, 437, 116585. doi:10.1016/j.geoderma.2023.116585