PICP is the empirical proportion of observations satisfying
lower <= obs <= upper; endpoints are included. It is returned on the
probability scale from zero to one, so multiply by 100 to report a percent.
Usage
picp(
obs,
lower = NULL,
upper = NULL,
na.rm = TRUE,
level = 0.95,
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.
- na.rm
Logical; remove incomplete cases? See Input representations.
- level
Nominal central interval coverage, strictly between zero and one. Used to generate bounds from predictive means and standard deviations or predictive samples; it does not alter explicit bounds.
- 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}(\tau) = \frac{1}{n}\sum_{i=1}^{n} I(lower_i \leq obs_i \leq upper_i)$$
For a well-calibrated central interval, picp() should be close to its
nominal level. Missing triplets are removed when na.rm = TRUE.
A single PICP does not reveal whether non-coverage is balanced between the
lower and upper tails. Use gg_coverage() to inspect PICP across interval
levels; assess tail-specific calibration separately when directional bias is
scientifically important.
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
Goovaerts, P. (2001). Geostatistical modelling of uncertainty in soil science. Geoderma, 103, 3-26. doi:10.1016/S0016-7061(01)00067-2
Shrestha, D. L. and Solomatine, D. P. (2008). Data-driven approaches for estimating uncertainty in rainfall-runoff modelling. International Journal of River Basin Management, 6, 109-122. doi:10.1080/15715124.2008.9635341