% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.R
\name{nmfkc.kernel.beta.nearest.med}
\alias{nmfkc.kernel.beta.nearest.med}
\title{Estimate Gaussian/RBF kernel parameter beta from covariates (supports landmarks)}
\usage{
nmfkc.kernel.beta.nearest.med(
  U,
  Uk = NULL,
  block.size = 1000,
  block.size.Uk = 2000,
  sample.size = NULL,
  ...
)
}
\arguments{
\item{U}{A numeric matrix of covariates (\code{K x N}); columns are samples.}

\item{Uk}{An optional numeric matrix of landmarks (\code{K x M}); columns are landmark points.
If provided, distances are computed from samples in \code{U} to landmarks in \code{Uk}.}

\item{block.size}{Integer. Number of columns of \code{U} processed per block when computing
distances (controls memory usage). If \code{N <= 1000}, it is automatically set to \code{N}.}

\item{block.size.Uk}{Integer. Number of columns of \code{Uk} processed per block when \code{Uk}
is not \code{NULL} (controls memory usage). If \code{M <= 2000}, it is automatically set to \code{M}.}

\item{sample.size}{Integer or \code{NULL}. If not \code{NULL}, randomly subsamples this many columns
of \code{U} (without replacement) before computing distances, to reduce computational cost.}

\item{...}{Additional arguments.  Hidden option \code{candidates} controls
the candidate grid: one of \code{"7points"} (default), \code{"4points"},
or a numeric vector of \eqn{t} values.  See Details.}
}
\value{
A list with elements:
\itemize{
\item \code{beta}: Estimated kernel parameter \eqn{\beta_0 = 1/(2\sigma_0^2)}.
\item \code{beta_candidates}: Numeric vector of candidate \eqn{\beta} values (logarithmic grid)
intended for cross-validation.
\item \code{dist_median}: The estimated distance scale \eqn{\sigma_0} (median of nearest-neighbor
or nearest-landmark distances).
\item \code{block.size.used}: The effective block size(s) used. Either a scalar (no \code{Uk}) or
a named vector \code{c(U=..., Uk=...)} when \code{Uk} is provided.
\item \code{sample.size.used}: The number of columns of \code{U} actually used (after subsampling).
\item \code{uk_is_u}: Logical flag indicating whether \code{Uk} was detected as identical to \code{U}
(only returned when \code{Uk} is provided).
}
}
\description{
Computes a data-driven reference scale for the Gaussian/RBF kernel from covariates
using a robust "median nearest-neighbor (or nearest-landmark) distance" heuristic,
and returns the corresponding kernel parameter \eqn{\beta}.

The Gaussian/RBF kernel is assumed to be written in the form
\deqn{k(u,v) = \exp\{-\beta \|u-v\|^2\} = \exp\{-\|u-v\|^2/(2\sigma^2)\},}
hence \eqn{\beta = 1/(2\sigma^2)}. This function first estimates a typical distance
scale \eqn{\sigma_0} by the median of distances, then sets \eqn{\beta_0 = 1/(2\sigma_0^2)}.

If \code{Uk} is \code{NULL}, \eqn{\sigma_0} is estimated as the median of
nearest-neighbor distances within \code{U} (excluding self-distance).
If \code{Uk} is provided, \eqn{\sigma_0} is estimated as the median of
nearest-landmark distances from each sample in \code{U} to its closest landmark in \code{Uk}.

To control memory usage for large \code{N} (and \code{M}), distances are computed in blocks.
Optionally, columns of \code{U} can be randomly subsampled via \code{sample.size} to reduce cost.
}
\details{
\strong{Candidate grid:}
Along with \code{beta}, the function returns \code{beta_candidates}, a
logarithmic grid suitable for cross-validation.  The grid is symmetric on
the bandwidth scale \eqn{\sigma} around \eqn{\sigma_0}:
\deqn{\sigma = \sigma_0 \times 10^{t},}
and since \eqn{\beta = 1/(2\sigma^2)}, this corresponds to
\eqn{\beta = \beta_0 \times 10^{-2t}}.

The grid of \eqn{t} values can be customized through the hidden argument
\code{candidates} (passed via \code{...}):
\itemize{
\item \code{"7points"} (default): \eqn{t \in \{-1,-2/3,-1/3,0,1/3,2/3,1\}}
(7 candidates spanning one decade, matches the grid used in the
RFF-NMF research memo).
\item \code{"4points"}: \eqn{t \in \{-1/2, 0, 1/2, 1\}} yielding
\eqn{\beta_0 \times 10^{(1,0,-1,-2)}} (the legacy short grid).
\item A numeric vector: user-specified \eqn{t} values.  The grid returned
is \eqn{\beta_0 \times 10^{-2t}}.
}

Prior to version 0.6.8, the grid depended on whether \code{Uk} was
supplied (4 candidates for \code{Uk = NULL}, 7 for supplied \code{Uk}).
The current implementation unifies both branches via \code{candidates}.

\strong{Notes:}
\itemize{
\item When \code{Uk} is identical to \code{U}, the function detects this case and excludes
self-distances (distance 0) to avoid \eqn{\sigma_0=0}.
\item \code{sample.size} performs random subsampling without setting a seed. For reproducible
results, set \code{set.seed()} before calling this function.
}
}
\examples{
# Basic (nearest-neighbor within U)
U <- matrix(runif(20), nrow = 2)
beta_info <- nmfkc.kernel.beta.nearest.med(U)
beta0 <- beta_info$beta
betas <- beta_info$beta_candidates

# With landmarks (nearest-landmark distances)
Uk <- matrix(runif(10), nrow = 2)
\donttest{
beta_info2 <- nmfkc.kernel.beta.nearest.med(U, Uk)
}

}
\seealso{
\code{\link{nmfkc.kernel.gaussian}}, \code{\link{nmfkc.kernel.beta.cv}}
}
