% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_denoising_params.R
\name{select_denoising_params}
\alias{select_denoising_params}
\title{Choose d-fSPA denoising parameters by cross-validation}
\usage{
select_denoising_params(
  F_hat,
  W,
  K,
  N_grid = NULL,
  Delta_grid = 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}{Integer number of basis functions (fixed during this search).}

\item{N_grid}{Optional numeric vector of candidate \code{N} values. Defaults
to \code{c(0.2, 0.5, 1.0) * log(nrow(F_hat))}.}

\item{Delta_grid}{Optional numeric vector of candidate \code{Delta} values.
Defaults to \code{c(0.05, 0.10, 0.20, 0.30)} times the maximum pairwise
\eqn{L^2(\mu)} distance among studies.}

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

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

\item{dfspa_args}{Named list of additional arguments for \code{\link[=dfspa]{dfspa()}}
(e.g. \code{list()}; do not include \code{N}, \code{Delta}, or \code{denoise} here, they
are set by the search).}

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

\item{seed}{Optional integer seed for reproducible fold assignment.}
}
\value{
An object of class \code{metahunt_denoising_search}: a list with
\describe{
\item{\code{grid}}{A data frame with one row per \verb{(N, Delta)} pair,
columns \code{N}, \code{Delta}, \code{cv_error}, \code{cv_se}, \code{n_folds_ok}.}
\item{\code{best}}{A list with the \verb{(N, Delta)} minimising \code{cv_error}.}
\item{\code{K}, \code{n_folds}, \code{grid_weights}}{Inputs echoed back for
traceability.}
}
}
\description{
At a fixed \code{K}, performs k-fold cross-validation over a grid of denoising
parameter pairs \verb{(N, Delta)} for \code{\link[=dfspa]{dfspa()}}. For each candidate pair and
each fold, the full MetaHunt pipeline is fit on the out-of-fold studies
and predicts the held-out studies' functions. The pair with the lowest
average prediction error is selected.
}
\details{
This is the cross-validated tuning of the denoising parameters discussed
in Section 3.1 of the paper. Joint tuning over \verb{(K, N, Delta)} is not
supported because it scales poorly; if you also want to choose \code{K}, do
it first via \code{\link[=cv_error_curve]{cv_error_curve()}} and then call this function at the
selected \code{K}.

Default candidate grids:
\itemize{
\item \code{N_grid    = m * c(NA, NA, NA)} resolved at runtime to
\code{c(0.2, 0.5, 1.0) * log(m)}.
\item \code{Delta_grid = max_pairwise_dist * c(0.05, 0.10, 0.20, 0.30)}.
}

Pass your own \code{N_grid} / \code{Delta_grid} (in original units) to override.
}
\examples{
\donttest{
set.seed(1)
G <- 30; m <- 80
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.5), c(-0.4, 1), c(0, 0))
pi_true <- exp(eta) / rowSums(exp(eta))
F_hat <- pi_true \%*\% basis + matrix(rnorm(m * G, sd = 0.05), m, G)

tune <- select_denoising_params(F_hat, W, K = 3, n_folds = 4, seed = 1)
tune$grid
tune$best
}

}
\seealso{
\code{\link[=cv_error_curve]{cv_error_curve()}} for selecting \code{K}, \code{\link[=dfspa]{dfspa()}} for the
underlying basis-hunting algorithm.
}
