% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rank_selection.R
\name{reconstruction_error_curve}
\alias{reconstruction_error_curve}
\title{Reconstruction-error curve for basis-rank selection}
\usage{
reconstruction_error_curve(
  F_hat,
  K_range = NULL,
  grid_weights = NULL,
  dfspa_args = list()
)
}
\arguments{
\item{F_hat}{An \code{m}-by-\code{G_grid} numeric matrix of study-level function
evaluations on the shared grid.}

\item{K_range}{Integer vector of candidate \code{K} values. Defaults to
\code{2:min(nrow(F_hat) - 1, 10)}.}

\item{grid_weights}{Optional length-\code{G_grid} non-negative numeric vector
used for the \eqn{L^2(\mu)} norm; defaults to uniform.}

\item{dfspa_args}{Named list of extra arguments passed to \code{\link[=dfspa]{dfspa()}},
e.g. \code{list(denoise = FALSE, N = 2)}.}
}
\value{
A data frame with columns \code{K} (integer) and \code{error} (numeric).
Rows where \code{dfspa()} or the projection fails are reported with
\code{error = NA} and a single warning summarising the failures.
}
\description{
For each candidate number of bases \code{K}, run \code{\link[=dfspa]{dfspa()}} followed by
\code{\link[=project_to_simplex]{project_to_simplex()}} and report the average projection residual
\deqn{\mathcal E(K) = \frac{1}{m}\sum_{i=1}^m
       \left\|\hat f^{(i)} - \sum_{k=1}^K \hat\pi_{ik}\hat g_k\right\|_{L^2(\mu)}.}
Plotting \code{error} against \code{K} typically shows an elbow.
}
\details{
This is the unsupervised rank-selection criterion of Section 3.2 of the
paper (Equation for \eqn{\mathcal E(K)}). It does not require
study-level covariates.
}
\examples{
set.seed(1)
G <- 40
x <- seq(0, 1, length.out = G)
basis <- rbind(sin(pi * x), cos(pi * x), x)
m <- 50
pi_mat <- matrix(stats::rgamma(m * 3, shape = 0.5), m, 3)
pi_mat <- pi_mat / rowSums(pi_mat)
F_hat  <- pi_mat \%*\% basis + matrix(stats::rnorm(m * G, sd = 0.02), m, G)

elbow <- reconstruction_error_curve(F_hat, K_range = 2:6)
elbow

}
