% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rank_selection.R
\name{cv_error_curve}
\alias{cv_error_curve}
\title{Cross-validated prediction-error curve for basis-rank selection}
\usage{
cv_error_curve(
  F_hat,
  W,
  K_range = NULL,
  n_folds = 5L,
  grid_weights = 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{K_range}{Integer vector of candidate \code{K} values. Defaults to
\code{2:min(nrow(F_hat) - 1, 10)}.}

\item{n_folds}{Integer number of CV folds (default \code{5}).}

\item{grid_weights}{Optional length-\code{G_grid} non-negative numeric vector.}

\item{dfspa_args}{Named list of extra arguments for \code{\link[=dfspa]{dfspa()}}.}

\item{weight_model_args}{Named list of extra arguments for
\code{\link[=fit_weight_model]{fit_weight_model()}}.}

\item{seed}{Optional integer seed for reproducible fold assignment; if
\code{NULL} no seeding is performed.}
}
\value{
A data frame with columns \code{K}, \code{cv_error} (mean over folds),
and \code{cv_se} (standard error across folds). The per-fold error matrix
is attached as the attribute \code{"fold_errors"}
(\code{length(K_range)}-by-\code{n_folds}). Folds where the pipeline fails
contribute \code{NA} and are summarised in a single warning.
}
\description{
For each candidate \code{K}, perform k-fold cross-validation at the study
level. Within each fold, the full MetaHunt pipeline (d-fSPA + constrained
projection + weight model) is refit on the training studies, and the
held-out studies' functions are predicted from their study-level
covariates. The prediction error is
\eqn{\|\hat f^{(i)} - \tilde f^{(i)}\|_{L^2(\mu)}} averaged over
held-out studies and then over folds.
}
\details{
This is the supervised rank-selection criterion of Section 3.2 of the
paper. Each held-out study is excluded from both basis hunting and
weight-model fitting.
}
\examples{
\donttest{
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.02), m, G)
cv <- cv_error_curve(F_hat, W, K_range = 2:5, n_folds = 4, seed = 1)
cv
}

}
