spconform (version 0.1.1)

diagnose: Comprehensive Diagnostic Suite for Spatial Conformal Prediction Objects

Description

Produces a comprehensive multi-panel diagnostic report evaluating marginal coverage validity, Winkler Interval Score (WIS) sharpness, conditional coverage across spatial strata, boundary proximity effects, spatial residual autocorrelation (Moran's I), and nonconformity score distributions.

Usage

diagnose(object, y_true, s_test = NULL, n_bins = 4, plot = TRUE, ...)

Value

An S3 object of class "spconform_diagnose" containing:

marginal

List with coverage, mean width, median width, sd width, Winkler score, and sample size.

conditional

Data frame of coverage and widths partitioned by spatial quadrant.

boundary

List comparing empirical metrics between interior and boundary units.

spatial_autocorr

List containing Moran's I statistic, expected value, z-score, and p-value.

scores

Summary of nonconformity score moments and quantiles.

alpha

Miscoverage level of the evaluated object.

Arguments

object

An object of class "spconform", typically output from scp_geostatistical or scp_areal.

y_true

Numeric vector of true observed responses at target prediction locations. Must have the same length as object$pred.

s_test

Optional numeric matrix of target prediction coordinates (\(m \times p\)). Required for spatial stratification, boundary effects, and spatial autocorrelation diagnostics.

n_bins

Integer; number of spatial bins per dimension for conditional coverage (default 4).

plot

Logical; if TRUE (default), generates a multi-panel diagnostic plot.

...

Additional graphical parameters passed to internal plotting methods.

Details

The diagnostic suite performs five rigorous audits on the prediction intervals:

1. Marginal Validity & Sharpness: Evaluates empirical coverage \(\frac{1}{m}\sum \mathbf{1}(Y_i \in C(s_i))\), mean/median interval width, and the strictly proper Winkler Interval Score (WIS): $$\text{WIS}_\alpha(l, u, y) = (u - l) + \frac{2}{\alpha}(l - y)\mathbf{1}(y < l) + \frac{2}{\alpha}(y - u)\mathbf{1}(y > u)$$

2. Conditional Spatial Stratification: Partitions the 2D spatial domain into \(\text{n\_bins} \times \text{n\_bins}\) equal-area quadrants and assesses local coverage.

3. Convex Hull Boundary Proximity: Assesses whether edge-effect extrapolations degrade coverage near the boundary of the spatial domain.

4. Spatial Autocorrelation (Moran's I): Evaluates whether prediction miscoverages or nonconformity scores exhibit residual spatial clustering via Moran's \(I\).

5. Score Distribution: Analyzes empirical quantiles and normality/QQ structure.

References

Winkler, R. L. (1972). "A Decision-Theoretic Approach to Interval Estimation." Journal of the American Statistical Association, 67(337), 187-191.

Mao, R., Martin, R., and Reich, B. J. (2023). "Valid Conformal Prediction for Dependent Data." Journal of the American Statistical Association, tools:::Rd_expr_doi("10.1080/01621459.2022.2147531").

See Also

scp_geostatistical, scp_areal, coverage_report

Examples

set.seed(42)
n <- 100
s_tr <- matrix(runif(n * 2), n, 2)
y_tr <- sin(3 * s_tr[, 1]) + rnorm(n, sd = 0.2)
s_te <- matrix(runif(30 * 2), 30, 2)
y_te <- sin(3 * s_te[, 1]) + rnorm(30, sd = 0.2)

pfun <- function(s_tr, y_tr, s_new) rep(mean(y_tr), nrow(s_new))
out <- scp_geostatistical(s_tr, y_tr, s_te, pfun, alpha = 0.1)

diag_res <- diagnose(out, y_true = y_te, s_test = s_te, plot = FALSE)
print(diag_res)