% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conformal.R
\name{split_conformal}
\alias{split_conformal}
\title{Split conformal prediction intervals for target-function predictions}
\usage{
split_conformal(
  F_hat,
  W,
  W_new,
  K,
  alpha = 0.05,
  cal_frac = 0.3,
  wrapper = NULL,
  grid_weights = NULL,
  calibration_idx = NULL,
  dfspa_args = list(),
  weight_model_args = list(),
  seed = NULL
)
}
\arguments{
\item{F_hat}{An \code{m}-by-\code{G_grid} numeric matrix of study-level function
evaluations.}

\item{W}{An \code{m}-by-\code{p} matrix or data frame of study-level covariates.}

\item{W_new}{A matrix or data frame of new target covariates. Must
contain columns matching \code{W}.}

\item{K}{Integer number of basis functions.}

\item{alpha}{Miscoverage level; interval has nominal coverage
\eqn{1-\alpha}. Default \code{0.05}.}

\item{cal_frac}{Numeric in \verb{(0, 1)} giving the fraction of studies in
the calibration set. Default \code{0.3}. Ignored if \code{calibration_idx} is
supplied.}

\item{wrapper}{Optional reduction function (see \code{\link[=apply_wrapper]{apply_wrapper()}}). If
\code{NULL}, intervals are constructed pointwise at every grid point.}

\item{grid_weights}{Optional length-\code{G_grid} non-negative numeric vector
used for the \eqn{L^2(\mu)} norm and for the default wrapper.}

\item{calibration_idx}{Optional integer vector of row indices in \code{F_hat}
to use as the calibration set. If supplied, \code{cal_frac} is ignored.}

\item{dfspa_args, weight_model_args}{Named lists passed to \code{\link[=dfspa]{dfspa()}} and
\code{\link[=fit_weight_model]{fit_weight_model()}} respectively.}

\item{seed}{Optional integer seed for reproducible train/calibration
splits.}
}
\value{
An object of class \code{"metahunt_conformal"}: a list with
\describe{
\item{\code{prediction}}{Point predictions for \code{W_new}. A numeric vector
of length \code{nrow(W_new)} in the scalar case, or an
\code{nrow(W_new)}-by-\code{G_grid} matrix in the pointwise case.}
\item{\code{lower}, \code{upper}}{Interval endpoints, same shape as
\code{prediction}.}
\item{\code{alpha}}{Miscoverage level used.}
\item{\code{method}}{\code{"split"}.}
\item{\code{n_cal}}{Calibration sample size.}
\item{\code{quantile}}{The conformal quantile: a scalar (scalar case)
or a length-\code{G_grid} vector (pointwise case).}
\item{\code{wrapper}}{The wrapper used, or \code{NULL}.}
}
}
\description{
Implements Algorithm 2 of the paper (split conformal prediction) over
the MetaHunt pipeline. Studies are partitioned into training and
calibration sets. The training set is used to fit d-fSPA, the constrained
projection, and the weight model; the calibration set supplies
conformity scores, which determine the width of the intervals.
}
\details{
Given a target function, one can either construct intervals \strong{pointwise
at every grid point} (when \code{wrapper = NULL}) or for a \strong{scalar summary}
of the target function (when \code{wrapper} is a function).
\itemize{
\item \strong{Pointwise} (\code{wrapper = NULL}): for each grid point \code{g} the
conformity score is \eqn{R_{i,g} = |\hat f^{(i)}(x_g) - \tilde
  f^{(i)}(x_g)|} across calibration studies \code{i}. A separate
\eqn{(1-\alpha)}-quantile \eqn{q_g} is computed per grid point, and
the interval at grid point \code{g} for target \code{j} is
\eqn{[\tilde f^{(j)}(x_g)-q_g,\ \tilde f^{(j)}(x_g)+q_g]}.
\item \strong{Scalar} (\code{wrapper} supplied): conformity scores are
\eqn{R_i = |s(\hat f^{(i)}) - s(\tilde f^{(i)})|} with
\code{s = wrapper}, and the interval for each target is
\eqn{[s(\tilde f^{(j)})-q,\ s(\tilde f^{(j)})+q]} with a single
shared quantile \eqn{q}.
}

The finite-sample quantile is
\eqn{q = R_{(k)}} with \eqn{k = \lceil(1-\alpha)(n_\mathrm{cal}+1)\rceil};
if \eqn{k > n_\mathrm{cal}}, \code{q = Inf} and intervals are
\eqn{(-\infty, \infty)}.
}
\examples{
set.seed(1)
G <- 40; m <- 80; K_true <- 3
x <- seq(0, 1, length.out = G)
basis <- rbind(sin(pi * x), cos(pi * x), x)
W <- data.frame(w1 = rnorm(m), w2 = rnorm(m))
eta <- as.matrix(W) \%*\% cbind(c(1, -0.8), c(-0.5, 1.2), c(0, 0))
pi_true <- exp(eta) / rowSums(exp(eta))
F_hat <- pi_true \%*\% basis + matrix(rnorm(m * G, sd = 0.05), m, G)

W_new <- data.frame(w1 = c(0, 1), w2 = c(0, -1))
# pointwise intervals at every grid point
pi_grid <- split_conformal(F_hat, W, W_new, K = 3, seed = 1)
dim(pi_grid$lower)  # 2 x 40
# scalar intervals for the grid-weighted mean (ATE-style)
pi_ate  <- split_conformal(F_hat, W, W_new, K = 3, wrapper = mean, seed = 1)
pi_ate$prediction

}
