% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conformal.R
\name{coverage}
\alias{coverage}
\title{Empirical coverage of a conformal prediction-interval object}
\usage{
coverage(object, F_obs, grid_weights = NULL)
}
\arguments{
\item{object}{A \code{"metahunt_conformal"} object from \code{\link[=split_conformal]{split_conformal()}},
\code{\link[=cross_conformal]{cross_conformal()}}, or \code{\link[=conformal_from_fit]{conformal_from_fit()}}.}

\item{F_obs}{An \code{n_target}-by-\code{G_grid} numeric matrix of observed
study-level functions for the target studies, in the same row order
as \code{object$prediction}.}

\item{grid_weights}{Optional length-\code{G_grid} non-negative numeric
vector. Only used in scalar mode (passed to \code{\link[=apply_wrapper]{apply_wrapper()}}).}
}
\value{
A list. In \strong{pointwise} mode the list contains
\describe{
\item{\code{pointwise}}{\code{n_target}-by-\code{G_grid} logical matrix of
coverage indicators.}
\item{\code{per_target}}{Length-\code{n_target} numeric vector of mean
coverage across the grid for each target.}
\item{\code{per_grid_point}}{Length-\code{G_grid} numeric vector of mean
coverage across targets at each grid point.}
\item{\code{overall}}{Scalar mean coverage across all entries.}
\item{\code{nominal}}{Nominal coverage \code{1 - object$alpha}.}
}
In \strong{scalar} mode the list contains
\describe{
\item{\code{pointwise}}{Length-\code{n_target} logical vector of coverage
indicators.}
\item{\code{overall}}{Scalar mean coverage.}
\item{\code{nominal}}{Nominal coverage \code{1 - object$alpha}.}
}
}
\description{
Computes empirical coverage indicators of a fitted
\code{"metahunt_conformal"} object against held-out observed study-level
functions. The held-out studies must correspond positionally to the
targets used to build \code{object} (i.e. \code{F_obs[i, ]} is the observed
function for the same target whose prediction is in
\code{object$prediction[i, ]} or \code{object$prediction[i]}).
}
\details{
In \strong{pointwise} mode each entry \verb{(i, g)} of \code{F_obs} is compared against
\verb{[object$lower[i, g], object$upper[i, g]]}. In \strong{scalar} mode \code{F_obs}
is first reduced to a length-\code{n_target} vector via
\code{\link[=apply_wrapper]{apply_wrapper()}} using \code{object$wrapper} and the supplied
\code{grid_weights}, and then compared against
\verb{[object$lower, object$upper]}.

Coverage is a finite-sample diagnostic. Nominal coverage is
\code{1 - object$alpha}; empirical coverage will fluctuate around this
value due to sampling.
}
\examples{
set.seed(1)
G <- 25; m <- 80
x <- seq(0, 1, length.out = G)
basis <- rbind(sin(pi * x), cos(pi * x), x)
W <- data.frame(w1 = rnorm(m))
eta <- cbind(0.6 * W$w1, -0.3 * W$w1, rep(0, m))
pi_true <- exp(eta) / rowSums(exp(eta))
F_hat <- pi_true \%*\% basis + matrix(rnorm(m * G, sd = 0.05), m, G)

# held-out test set: same data-generating process, same W
test_idx <- 1:10
train_idx <- setdiff(seq_len(m), test_idx)
res <- split_conformal(F_hat[train_idx, ], W[train_idx, , drop = FALSE],
                       W[test_idx, , drop = FALSE], K = 3,
                       dfspa_args = list(denoise = FALSE), seed = 1)
cov <- coverage(res, F_obs = F_hat[test_idx, , drop = FALSE])
cov$overall

}
