% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfae.R
\name{nmfae}
\alias{nmfae}
\title{Three-Layer Non-negative Matrix Factorization (NMF-AE)}
\source{
Satoh, K. (2025). Applying Non-negative Matrix Factorization with Covariates
to Multivariate Time Series. \emph{Japanese Journal of Statistics and Data Science}.
}
\usage{
nmfae(
  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). Non-negative. May contain \code{NA}s
(handled via \code{Y1.weights}).}

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

\item{rank}{Integer. Rank of the decoder basis \eqn{X_1} (P1 x Q). Default is 2.
For backward compatibility, \code{Q} is accepted via \code{...}.}

\item{rank.encoder}{Integer. Rank of the encoder basis \eqn{X_2} (R x P2).
Default is \code{rank}. For backward compatibility, \code{R} is accepted via \code{...}.}

\item{epsilon}{Positive convergence tolerance. Default is \code{1e-4}.}

\item{maxit}{Maximum number of multiplicative update iterations. Default is 5000.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages during fitting. Default is \code{FALSE}.}

\item{...}{Additional arguments:
\describe{
\item{\code{Y1.weights}}{Optional non-negative weight matrix
(P1 x N) or vector 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.
Typical ECV / CV usage passes a binary mask
\eqn{W \in \{0,1\}} for held-out elements; 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{C.L1}}{L1 regularization parameter for \eqn{C}. Default is 0.}
\item{\code{X1.L2.ortho}}{L2 orthogonality regularization for \eqn{X_1} columns. Default is 0.}
\item{\code{X2.L2.ortho}}{L2 orthogonality regularization for \eqn{X_2} rows. Default is 0.}
\item{\code{seed}}{Integer seed for reproducibility. Default is 123.}
\item{\code{print.trace}}{Logical. If \code{TRUE}, prints progress. Default is \code{FALSE}.}
}}
}
\value{
An object of class \code{"nmfae"}, a list with components:
\item{X1}{Decoder basis matrix (P1 x Q), column sum 1.}
\item{C}{Parameter matrix (Q x R).}
\item{X2}{Encoder basis matrix (R x P2), row sum 1.}
\item{Y1hat}{Fitted values \eqn{X_1 \Theta X_2 Y_2} (P1 x N).}
\item{rank}{Named integer vector \code{c(Q, R)}.}
\item{objfunc}{Final objective value.}
\item{objfunc.iter}{Objective values by iteration.}
\item{r.squared}{\eqn{\mathrm{cor}(Y, \widehat Y)^2} (Pearson; in \eqn{[0,1]}).}
\item{r.squared.uncentered}{Uncentered \eqn{R^2 = 1 - \|Y - \widehat Y\|_F^2 / \|Y\|_F^2} (baseline = zero matrix).}
\item{r.squared.centered}{Row-mean centered \eqn{1 - \|Y - \widehat Y\|_F^2 / \|Y - \bar Y_{p\cdot}\|_F^2}.}
\item{niter}{Number of iterations performed.}
\item{runtime}{Elapsed time as a \code{difftime} object.}
\item{n.missing}{Number of missing (or zero-weighted) elements in \eqn{Y_1}.}
\item{n.total}{Total number of elements in \eqn{Y_1} (P1 x N).}
}
\description{
\code{nmfae} fits a three-layer nonnegative matrix factorization model
\eqn{Y_1 \approx X_1 \Theta X_2 Y_2}, where \eqn{X_1} is a decoder basis
(column sum 1), \eqn{\Theta} is a bottleneck parameter matrix,
\eqn{X_2} is an encoder basis (row sum 1), and \eqn{Y_2} is the input matrix.

When \code{Y2 = Y1}, the model acts as a non-negative autoencoder.
When \code{Y1 != Y2}, it acts as a heteroencoder.

Initialization uses a three-step NMF procedure via \code{\link{nmfkc}}:
(1) \code{nmfkc(Y1, rank=Q)} to obtain \eqn{X_1},
(2) \code{nmfkc(Y1, A=Y2, rank=Q)} with fixed \eqn{X_1} to obtain \eqn{C = \Theta X_2},
(3) \code{nmfkc(Y2, rank=R)} to factor \eqn{C} into \eqn{\Theta} and \eqn{X_2}.
}
\section{Lifecycle}{

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

\examples{
# Autoencoder example
Y <- matrix(c(1,0,1,0, 0,1,0,1, 1,1,0,0), nrow=3, byrow=TRUE)
res <- nmfae(Y, rank=2, rank.encoder=2)
res$r.squared

# Heteroencoder example
Y1 <- matrix(c(1,0,0,1), nrow=2)
Y2 <- matrix(runif(8), nrow=4)
res2 <- nmfae(Y1, Y2, rank=2, rank.encoder=2)

}
\references{
Lee, D. D. and Seung, H. S. (2001). Algorithms for Non-negative Matrix Factorization.
\emph{Advances in Neural Information Processing Systems}, 13.

Saha, S. et al. (2022). Hierarchical Deep Learning Neural Network (HiDeNN):
An Artificial Intelligence (AI) Framework for Computational Science and Engineering.
\emph{Computer Methods in Applied Mechanics and Engineering}, 399.
}
\seealso{
\code{\link{nmfae.inference}}, \code{\link{predict.nmfae}}, \code{\link{nmfae.ecv}}, \code{\link{nmfae.DOT}}, \code{\link{nmfkc}}
}
