% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfae.signed.R
\name{nmfae.signed}
\alias{nmfae.signed}
\title{Signed-Bottleneck NMF-AE: Three-Layer NMF-AE with Signed Bottleneck}
\usage{
nmfae.signed(
  Y1,
  Y2 = Y1,
  rank = 2,
  rank.encoder = rank,
  epsilon = 1e-04,
  maxit = 5000,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{Y1}{Output matrix \eqn{Y_1} (P1 x N).  Negative entries allowed
(\code{Y.signed = TRUE} is auto-detected).}

\item{Y2}{Input matrix \eqn{Y_2} (P2 x N).  Must be non-negative.
Default \code{Y1} (autoencoder).}

\item{rank}{Integer.  Decoder rank Q.  Default 2.
Alias \code{Q} accepted via \code{...}.}

\item{rank.encoder}{Integer.  Encoder rank R.  Default \code{rank}.
Alias \code{R} accepted via \code{...}.}

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

\item{maxit}{Maximum iterations.  Default 5000.}

\item{verbose}{Logical.  Print progress.  Default \code{FALSE}.}

\item{...}{Additional arguments:
\describe{
\item{\code{warm.start}}{One of \code{TRUE} (default, \strong{hybrid}:
warm-start \eqn{X_1, X_2} from \code{\link{nmfae}} but initialize
\eqn{C_{+}, C_{-}} randomly), \code{"full"} (warm-start everything
including \eqn{C_{+} = C_{\mathrm{tri}}}, \eqn{C_{-} = \delta}),
or \code{FALSE} (random for all blocks).  The hybrid default avoids
the \eqn{C_{-} = 0} local-minimum trap inherited from tri-NMF-AE
while still benefiting from good \eqn{X_1, X_2} initialization.
Ignored when \eqn{Y_1} has negative entries.}
\item{\code{nstart}}{Integer, default 1 (cf. \code{\link{kmeans}}).
Number of random restarts for \eqn{C_{+}, C_{-}}.  Each restart
uses seed \code{seed + 7919 * (s-1)}.  Returns the best run by
final objective.  \strong{Signed models have more local minima
than non-negative ones} because the bottleneck
\eqn{\Theta = C_{+} - C_{-}} can take both positive and negative
values; during exploration a larger \code{nstart} (e.g., 10-50)
reduces the chance of being trapped at an inferior stationary
point (particularly the \eqn{C_{-} = 0} trap from warm-start
from non-negative tri-NMF-AE).  Use the default 1 for fast
development and raise for publication-grade runs.}
\item{\code{Y1.weights}}{Optional non-negative weight matrix
(P1 x N) or vector (length N) for \eqn{Y_1}, analogous to the
\code{weights} argument of \code{\link[stats]{lm}}.  Loss
becomes \eqn{\sum W_{ij} \, (Y_{1,ij} - \hat Y_{1,ij})^2}
(\code{lm()}-style, \strong{linear} in \eqn{W}).  Logical
matrices (\code{TRUE} / \code{FALSE}) are also accepted.
Used by \code{\link{nmfae.signed.ecv}} to hold out test
elements via a binary mask \eqn{W \in \{0,1\}}; real-valued
weights for importance weighting are also supported.  Default:
if \code{Y1} has \code{NA}, a binary mask is auto-generated
(0 for \code{NA}, 1 elsewhere).}
\item{\code{Cp.init}, \code{Cn.init}}{Explicit \eqn{Q \times R}
non-negative matrices for initialization.  Overrides warm.start.}
\item{\code{C.init}}{Explicit signed \eqn{Q \times R} matrix,
internally split into \eqn{(C_{+}, C_{-})}.}
\item{\code{X1.init}, \code{X2.init}}{Explicit basis matrices.}
\item{\code{seed}}{RNG seed.  Default 123.}
\item{\code{print.trace}}{Logical.  Print iteration trace.
Default \code{FALSE}.}
\item{\code{prefix.dec}, \code{prefix.enc}}{Label prefixes for
decoder/encoder factors.  Default \code{"Dec"}, \code{"Enc"}.}
}}
}
\value{
An object of class \code{c("nmfae.signed", "nmfae", "nmf")} with:
\item{X1}{Decoder basis (P1 x Q), column sum 1.}
\item{Cp, Cn}{Non-negative parts of \eqn{\Theta} (each Q x R).}
\item{C}{Signed bottleneck \eqn{\Theta = C_{+} - C_{-}} (Q x R).}
\item{X2}{Encoder basis (R x P2), row sum 1.}
\item{Y1hat}{Fitted values \eqn{X_1 (C_{+} - C_{-}) X_2 Y_2}.}
\item{H}{Encoding \eqn{(C_{+} - C_{-}) X_2 Y_2} (Q x N, signed).}
\item{rank}{\code{c(Q = Q, R = R)}.}
\item{dims}{\code{c(P1, P2, N)}.}
\item{objfunc, objfunc.iter}{Final and per-iteration objective values.}
\item{r.squared}{\eqn{\mathrm{cor}(Y_1, \widehat Y_1)^2} (Pearson; in \eqn{[0,1]}).}
\item{r.squared.uncentered}{Uncentered \eqn{R^2 = 1 - \|Y_1 - \widehat Y_1\|_F^2 / \|Y_1\|_F^2} (baseline = zero matrix).}
\item{r.squared.centered}{Row-mean centered \eqn{1 - \|Y_1 - \widehat Y_1\|_F^2 / \|Y_1 - \bar Y_{p\cdot}\|_F^2}.}
\item{sigma, mae}{Residual SE and mean absolute error.}
\item{niter, runtime}{Iterations and elapsed seconds.}
\item{Y.signed}{Logical; whether \eqn{Y_1} contained negative entries.}
\item{call}{Matched call.}
}
\description{
\code{nmfae.signed} fits a three-layer non-negative matrix factorization
autoencoder with a \strong{signed} bottleneck, solving
\deqn{Y_1 \approx X_1 (C_{+} - C_{-}) X_2 Y_2,
  \quad X_1 \ge 0,\; C_{+} \ge 0,\; C_{-} \ge 0,\; X_2 \ge 0,}
where \eqn{\Theta = C_{+} - C_{-}} is the signed bottleneck.  The basis
matrices \eqn{X_1} (columns sum to 1) and \eqn{X_2} (rows sum to 1) retain
their non-negative "parts-based" interpretability, while \eqn{\Theta} can
express anti-correlations (e.g., refractive index up vs. Abbe number down).

The algorithm uses \strong{Direct Multiplicative Updates} derived from
Ding et al. (2010) sign-splitting technique, applied block-wise to the
four non-negative blocks \eqn{(C_{+}, C_{-}, X_1, X_2)}.  Each block update
monotonically decreases the true objective
\eqn{\|Y_1 - X_1(C_{+} - C_{-})X_2 Y_2\|_F^2} (Lee-Seung auxiliary
function method).

\strong{Relation to \code{\link{nmfae}}:} When \eqn{\Theta \ge 0} suffices
(the \code{nmfae} case), \code{nmfae.signed} reduces to \code{nmfae} up to
the \eqn{C_{+} - C_{-}} parameterization.  Use \code{nmfae.signed} when the
data exhibit negative cross-property correlations that tri-NMF-AE cannot
express (e.g., high refractive index <-> low Abbe number trade-off).
}
\section{Lifecycle}{

This function is \strong{experimental}; interface may change.
}

\examples{
\donttest{
set.seed(1)
Y1 <- matrix(abs(rnorm(12)), 3, 4)
Y2 <- matrix(abs(rnorm(20)), 5, 4)
res <- nmfae.signed(Y1, Y2, rank = 2, rank.encoder = 2, maxit = 500)
summary(res)
}
}
\references{
Ding, C.H.Q., Li, T., and Jordan, M.I. (2010).  Convex and
Semi-Nonnegative Matrix Factorizations.
\emph{IEEE TPAMI}, 32(1), 45-55.

Satoh, K. (2026).  Signed-Bottleneck NMF-AE: Signed-Bottleneck 3-Layer NMF
(research memo, 2026-04-18).

Ding, C. H. Q., Li, T., & Jordan, M. I. (2010). Convex and
semi-nonnegative matrix factorizations. \emph{IEEE Transactions on
Pattern Analysis and Machine Intelligence}, 32(1), 45--55.
}
\seealso{
\code{\link{nmfae}}, \code{\link{predict.nmfae.signed}},
\code{\link{summary.nmfae.signed}}, \code{\link{nmfae.signed.rename}}
}
