% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.signed.R
\name{nmfkc.signed}
\alias{nmfkc.signed}
\title{NMF-KC with signed covariate matrix}
\usage{
nmfkc.signed(
  Y,
  A,
  rank = NULL,
  epsilon = 1e-04,
  maxit = 5000,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{Y}{Real-valued \eqn{Q_{\mathrm{obs}} \times N} response matrix.
Unlike \code{\link{nmfkc}}, negative entries are allowed.}

\item{A}{Real-valued \eqn{D \times N} covariate matrix (signed).
A single matrix is passed; its positive and negative parts
\eqn{A_{+} = \max(A, 0)} and \eqn{A_{-} = \max(-A, 0)} are computed
internally.  When using Random Fourier Features (Rahimi & Recht
2007) as \eqn{A}, supply the RFF parameters via the hidden
\code{pars} argument so that \code{predict()} can regenerate
features for new data (see \code{pars} entry in \code{\dots} below).}

\item{rank}{Integer.  Number of latent components \eqn{Q} in \eqn{X}.}

\item{epsilon}{Relative convergence tolerance on the objective
(default \code{1e-4}).}

\item{maxit}{Maximum number of iterations (default \code{5000}).}

\item{verbose}{Logical.  Print dimensions at start (default \code{TRUE}).}

\item{...}{Additional arguments:
\itemize{
\item \code{Q}: alias for \code{rank}.
\item \code{X.restriction}: constraint applied to columns of
\eqn{X} after every update, with the scale absorbed into
\eqn{C_{+}, C_{-}}.  One of \code{"colSums"} (default,
\eqn{\mathrm{colSums}(X) = 1}), \code{"colSqSums"},
\code{"totalSum"}, \code{"none"}, \code{"fixed"}.
\item \code{X.init}: initialization strategy for the basis matrix
\eqn{X} (\eqn{Q_{\mathrm{obs}} \times Q}).  Accepts the same
menu as \code{\link{nmfkc}}: \code{"kmeans"} (default),
\code{"kmeansar"}, \code{"nndsvd"}, \code{"runif"}, or a
user-supplied \eqn{Q_{\mathrm{obs}} \times Q} non-negative
numeric matrix.  String methods delegate to the shared
internal helper \code{.init_X_method()} (see \code{\link{nmfkc}}
for the definitions of each method).  For signed \eqn{Y},
\code{"kmeans"} cluster centers may contain negative entries;
they are clipped to zero to satisfy \eqn{X \ge 0}, and any
column that collapses to all-zeros is re-filled with small
\eqn{\mathrm{Uniform}(0, 0.1)} noise.
\item \code{C.init}: explicit initial \eqn{Q \times D} coefficient
matrix \eqn{\Theta} (signed).  Split internally.
\item \code{warm.start}: logical (default \code{TRUE}).  If
\code{TRUE} \strong{and \eqn{Y \ge 0}}, runs
\code{nmfkc(Y, A = rbind(A_+, A_-), rank = Q)} internally to
seed \eqn{X, C_{+}, C_{-}}.  The user's \code{X.init},
\code{seed}, \code{nstart}, and \code{X.restriction} are
forwarded to the internal \code{\link{nmfkc}} call so that
initialization choices propagate consistently between the
warm-start and the signed MU loop.  Ignored when \eqn{Y} has
negative entries (warm-start is disabled; \code{X.init} is
used directly by the signed branch instead).
\item \code{seed}: RNG seed for random initialization (default 123).
\item \code{prefix}: name prefix for rows of \eqn{C} and columns
of \eqn{X} (default \code{"Basis"}).
\item \code{pars}: optional list \code{list(omega, b, D, beta)}
of Random Fourier Feature parameters (Rahimi & Recht 2007;
\code{omega}: frequency matrix, \code{b}: phase offset,
\code{D}: feature dimension, \code{beta}: bandwidth).  When
supplied, it is stored in the returned object so that
\code{summary()} can report \eqn{\beta} and downstream
\code{predict()} calls can regenerate RFF features for new
data.  If \code{A} is not RFF features, leave this \code{NULL}.
\item \code{Y.weights}: Optional non-negative weight matrix
(\eqn{Q_{\mathrm{obs}} \times N}) or vector (length \eqn{N}),
analogous to the \code{weights} argument of
\code{\link[stats]{lm}}.  Loss becomes
\eqn{\sum W_{ij} \, (Y_{ij} - (XCA)_{ij})^2}
(\code{lm()}-style, \strong{linear} in \eqn{W}).  Logical
matrices (\code{TRUE} / \code{FALSE}) are also accepted.
Typical usage by \code{\link{nmfkc.signed.cv}} /
\code{\link{nmfkc.signed.ecv}} passes a binary mask
\eqn{W \in \{0,1\}} to hold out test elements; real-valued
weights for observation-level importance weighting are also
supported.  Default \code{NULL}: if \code{Y} has \code{NA},
a binary mask is auto-constructed (0 for \code{NA}, 1
elsewhere); otherwise no weighting.
\item \code{nstart}: number of random restarts.  \strong{Signed
models have more local minima than non-negative ones} because
\eqn{\Theta = C_{+} - C_{-}} can take both positive and negative
values.  Since \code{nmfkc.signed()} itself does not loop over
restarts (callers control it), set the outer-loop size via e.g.
running the function several times with different \code{seed}
and keeping the fit with the smallest \code{$objfunc}.  A
restart budget of 10-50 is recommended for publication-grade
runs on signed data.
}}
}
\value{
An object of class \code{c("nmfkc.signed", "nmfkc")} with
\itemize{
\item \code{X}: \eqn{Q_{\mathrm{obs}} \times Q} basis matrix (non-negative,
column-normalized according to \code{X.restriction}).
\item \code{Cp}, \code{Cn}: \eqn{Q \times D} non-negative parts of
\eqn{\Theta}, so that \eqn{\Theta = C_{+} - C_{-}}.
\item \code{C}: \eqn{C_{+} - C_{-}} (= \eqn{\Theta}), signed.
\item \code{B}: \eqn{C \, A}, \eqn{Q \times N} (signed).
\item \code{objfunc.iter}: objective values per iteration.
\item \code{objfunc}: final objective.
\item \code{r.squared}: \eqn{\mathrm{cor}(Y, \widehat Y)^2} (Pearson; in \eqn{[0,1]}).
\item \code{r.squared.uncentered}: uncentered \eqn{R^2 = 1 - \|Y - \widehat Y\|_F^2 / \|Y\|_F^2} (baseline = zero matrix).
\item \code{r.squared.centered}: row-mean centered \eqn{1 - \|Y - \widehat Y\|_F^2 / \|Y - \bar Y_{p\cdot}\|_F^2}.
\item \code{mae}: mean absolute error.
\item \code{iter}: number of iterations performed.
\item \code{runtime}: elapsed seconds.
\item \code{Y.signed}: logical; whether \eqn{Y} contained negative
entries during fitting.
\item \code{pars}: RFF generating parameters, if supplied.
\item \code{call}: the matched call.
}
}
\description{
Solves
\deqn{Y \approx X\,\Theta\,A,\qquad X \ge 0,\;\Theta\in\R^{Q\times D},
  \;A\in\R^{D\times N},}
where the covariate matrix \eqn{A} and the coefficient matrix
\eqn{\Theta} may be \strong{signed}.  Internally \eqn{A = A_{+} - A_{-}}
and \eqn{\Theta = C_{+} - C_{-}} with \eqn{A_{\pm}, C_{\pm} \ge 0}
(sign-splitting trick, Ding et al. 2010), and the problem is solved
by a Direct Multiplicative Update algorithm whose iteration cost is
\eqn{O(Q D^2)}, independent of \eqn{N}.

Only \eqn{X} is structurally constrained to be non-negative (Semi-NMF
sense of Ding, Li, & Jordan 2010).  In particular, \strong{\eqn{Y} may
contain negative entries}, in which case the response is fit in the
least-squares sense without any non-negativity requirement on \eqn{Y}.

When \eqn{A \ge 0} (so \eqn{A_{-} = 0}), the result reduces to
\code{\link{nmfkc}}(Y, A, rank) with Euclidean loss, up to reordering.
}
\section{Lifecycle}{

This function is \strong{experimental}.  The interface may change in
future versions.
}

\examples{
\donttest{
set.seed(1)
## Example 1: signed A (e.g., hand-built RFF features), non-negative Y
## Build simple signed features Z = sqrt(2/D) * cos(omega^T U + b):
U     <- matrix(stats::rnorm(5 * 40), 5, 40)           # raw input
D     <- 20                                            # feature dim
omega <- matrix(stats::rnorm(5 * D), 5, D)             # random freqs
b     <- stats::runif(D, 0, 2 * pi)                    # phase
Z     <- sqrt(2 / D) *
           cos(t(omega) \%*\% U + matrix(b, D, 40))      # D x 40, signed
Y     <- matrix(abs(stats::rnorm(8 * 40)), 8, 40)
res1  <- nmfkc.signed(Y, A = Z, rank = 3, maxit = 200)

## Example 2: signed Y (regression)
Y2    <- matrix(stats::rnorm(8 * 40), 8, 40)           # signed response
res2  <- nmfkc.signed(Y2, A = Z, rank = 3, maxit = 200,
                       warm.start = FALSE)
}

}
\references{
Ding, C. H. Q., Li, T., & Jordan, M. I. (2010).  Convex and
semi-nonnegative matrix factorizations.  \emph{IEEE TPAMI}, 32(1), 45–55.

Rahimi, A., & Recht, B. (2007).  Random features for large-scale
kernel machines.  \emph{Advances in NIPS}, 20.
}
\seealso{
\code{\link{nmfkc}}, \code{\link{predict.nmfkc.signed}}
}
