% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.ard.R
\name{nmfkc.ard}
\alias{nmfkc.ard}
\title{Automatic relevance determination for NMF rank (experimental)}
\usage{
nmfkc.ard(Y, rank = NULL, nrun = 10, plot = FALSE, ...)
}
\arguments{
\item{Y}{Observation matrix (\eqn{F \times N}), non-negative.}

\item{rank}{Over-complete starting rank \eqn{K} (must exceed the true
rank).  \code{NULL} (default) uses \code{min(F, N, 20)}.}

\item{nrun}{Number of random-initialization restarts (default \code{10}).
ARD is a sensitive point estimate, so several restarts are advisable; the
reported rank is the \strong{mode} of the per-run estimates
(\code{rank.runs}), with a representative modal fit kept for
\code{plot}/\code{W}/\code{H}.}

\item{plot}{Logical; draw the relevance bar plot.}

\item{...}{Advanced options, rarely needed (defaults in parentheses):
\code{prior} (\code{"L2"}: half-normal / squared-energy group
shrinkage, \code{"L1"}: exponential / sparser); \code{seed} (\code{123},
random-initialization seed); \code{a} (\code{1}) and
\code{b} (\code{(F + N)/K * mean(Y)}), the inverse-gamma prior (a smaller
\code{b} over-prunes, a larger one prunes nothing); \code{maxit}
(\code{3000}) and \code{epsilon} (\code{1e-6}) for optimisation control;
\code{tol} (\code{1e-3}), the relevance threshold below which a component is
counted as pruned.}
}
\value{
An object of class \code{"nmfkc.ard"}: a list with
\code{rank} (estimated = mode over restarts), \code{rank.runs} (the
per-run estimates), \code{relevance} (representative run, descending),
\code{lambda}, \code{W}, \code{H} (ordered by relevance),
\code{rank.init}, \code{prior}, \code{nrun} and \code{objfunc}.
}
\description{
\strong{Prototype} of Tan & Fevotte's (2013) ARD-NMF (Euclidean /
\eqn{\beta = 2}).  Unlike the cross-validation (\code{\link{nmfkc.ecv}},
\code{\link{nmfkc.bicv}}) and stability (\code{\link{nmfkc.consensus}})
engines that \emph{scan} a range of ranks, ARD fits NMF \strong{once} at
an over-complete rank and prunes automatically: each component \eqn{k}
carries a relevance weight \eqn{\lambda_k} with an inverse-gamma prior;
the multiplicative updates gain a penalty \eqn{+ w_{fk}/\lambda_k} (L2 /
half-normal prior) or \eqn{+ 1/\lambda_k} (L1 / exponential), which
drives unsupported components to zero.  The number of surviving
components is the estimated rank.  Covariates are ignored (plain NMF).

This is a model-based point estimate: the result depends on the prior, the
starting rank and the random initialization, and can vary run to run.  Use
it as a complement to the CV / consensus engines, not a sole criterion.
}
\details{
\strong{Relation to Tan & Fevotte (2013).}  The update equations reproduce
the paper's \eqn{\ell_2} / \eqn{\ell_1} ARD-NMF for the \strong{Euclidean
(\eqn{\beta = 2})} case exactly: the multiplicative penalties, the
closed-form \eqn{\lambda_k} update \eqn{(f(w_k) + f(h_k) + b)/c} and the
constant \eqn{c} (their Eq. 33).  Two deliberate simplifications keep it
practical: only \eqn{\beta = 2} is implemented (the paper covers the general
\eqn{\beta}-divergence), and the default \code{b} is an \emph{empirical}
per-component energy scale \eqn{(F + N)/K \cdot \bar{Y}} that reliably avoids
the winner-take-all collapse, rather than the paper's method-of-moments value
(their Eq. 38).
}
\examples{
\donttest{
set.seed(1)
X <- matrix(abs(rnorm(40 * 3)), 40, 3)
B <- matrix(abs(rnorm(3 * 60)), 3, 60)
ar <- nmfkc.ard(X \%*\% B, rank = 10)   # over-complete start
ar$rank                                # ~ 3 surviving components
plot(ar)
}
}
\references{
V. Y. F. Tan and C. Fevotte (2013).  Automatic relevance
determination in nonnegative matrix factorization with the
beta-divergence.  \emph{IEEE TPAMI} 35(7):1592--1605.
\doi{10.1109/TPAMI.2012.240}.
}
\seealso{
\code{\link{nmfkc.ecv}}, \code{\link{nmfkc.bicv}},
\code{\link{nmfkc.consensus}}, \code{\link{nmfkc.rank}}
}
