% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.net.R
\name{nmfkc.net}
\alias{nmfkc.net}
\title{Symmetric NMF for networks (tri / bi / signed)}
\usage{
nmfkc.net(
  Y,
  rank = 2,
  type = c("tri", "bi", "signed"),
  epsilon = 1e-04,
  maxit = 5000,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{Y}{Symmetric (N x N) \strong{non-negative} adjacency matrix.
\code{NA} entries are automatically treated as masked edges
(equivalent to supplying \code{Y.weights} with 0 at those positions);
see the note on \code{Y.weights} below.}

\item{rank}{Integer Q.}

\item{type}{\code{"tri"} (default), \code{"bi"}, or \code{"signed"}.}

\item{epsilon, maxit, verbose}{Standard.}

\item{...}{Hidden options: \code{nstart} (default 1; see note below),
\code{seed} (default 123), \code{X.restriction}, \code{X.init},
\code{C.init} (tri only) or \code{Cp.init}/\code{Cn.init} (signed only),
\code{Y.weights}, \code{C.L1} (tri only), \code{X.L2.ortho}, \code{prefix}.

\strong{\code{Y.weights}} is an optional non-negative N x N weight
matrix (symmetric, same shape as \code{Y}).  When supplied, the loss
becomes \eqn{\sum W_{ij} \, (Y_{ij} - \hat Y_{ij})^2}
(\code{\link[stats]{lm}}()-style, \strong{linear} in \eqn{W}).
Logical matrices (\code{TRUE} / \code{FALSE}) are also accepted.
Typical usage by \code{\link{nmfkc.net.ecv}} is a binary mask
(\eqn{W \in \{0,1\}}) holding out test edges on the upper triangle;
real-valued weights for edge-level importance weighting are also
supported.  If \code{Y.weights} is \code{NULL} (default) and \code{Y}
contains \code{NA}, a binary mask is auto-generated (0 at \code{NA}
positions, 1 elsewhere), and the \code{NA} entries in \code{Y} are
replaced by 0 so the multiplicative updates can proceed.

\strong{\code{X.init}} controls the initialization of the N x Q basis
matrix \eqn{X}.  Accepted values:
\itemize{
\item \code{"kmeans"} (default): k-means on the rows of \eqn{Y}
(equivalently columns, since \eqn{Y} is symmetric); the Q
cluster centers become the columns of \eqn{X}.  Each node is
treated as an N-dimensional connectivity profile, so clusters
correspond to nodes with similar neighborhood structure --
essentially a fast proxy for spectral clustering (Kuang, Yun &
Park 2015, \emph{SymNMF}).  Scales well and is the recommended
default for network data.
\item \code{"kmeansar"}: \code{"kmeans"} followed by filling zero
entries of \eqn{X} with \eqn{\mathrm{Uniform}(0, \bar Y / 100)}
to escape trivial stationary points.
\item \code{"nndsvd"}: Non-negative Double SVD with additive
randomness (NNDSVDar).  Requires a full SVD of \eqn{Y}, so for
very large networks (N > a few thousand) \code{"kmeans"} is
preferable.
\item \code{"runif"}: Uniform random entries in \eqn{[0, 1]}.
\item \code{"random"}: Legacy default (pre-v0.6.8), equivalent to
\code{abs(rnorm(N * Q)) * 0.1}.  Kept for backward compatibility.
\item A numeric N x Q matrix supplied by the user (used as-is).
}
When \code{nstart > 1}, each restart uses a distinct seed so that
k-means / runif / NNDSVDar produce different candidate initial
values across the multi-start loop.

\strong{Multi-start recommendation.} For \code{type = "signed"} the
\eqn{C = C_{+} - C_{-}} bottleneck can take both positive and negative
values, so the objective has more local minima than for \code{"tri"}
or \code{"bi"}.  A larger \code{nstart} (e.g., 10-50) is recommended
during exploration to reduce the chance of being trapped at a
suboptimal stationary point.  The default 1 is intended for fast
development; raise for publication-grade runs.}
}
\value{
Object of class \code{c("nmfkc.net.<type>", "nmfkc.net", "nmfkc")}.
For \code{type = "signed"} the return also carries \code{$Cp, $Cn}.
}
\description{
Single entry point for symmetric NMF of network data with correct
multiplicative updates.  Three model types are supported via \code{type}:
\itemize{
\item \strong{tri} (\code{type="tri"}, default):
\eqn{Y \approx X C X^\top} with \eqn{X, C \ge 0} (both non-negative;
\eqn{C} symmetric by design).  Uses Frobenius-full bilateral gradient.
\item \strong{bi} (\code{type="bi"}):
\eqn{Y \approx X X^\top} (\eqn{C} fixed to \eqn{I_Q}),
cube-root damping (He et al. 2011).
\item \strong{signed} (\code{type="signed"}):
\eqn{Y \approx X (C_{+} - C_{-}) X^\top} with \eqn{X \ge 0} and signed
\eqn{C = C_{+} - C_{-}}.  Preserves the soft-clustering interpretation
of \eqn{X} while allowing negative off-diagonals of \eqn{C}
(inter-cluster \emph{repulsion}).
}

\strong{Non-negative adjacency matrix assumption.} All three types
assume \eqn{Y \ge 0} (a non-negative adjacency/affinity matrix).
The qualifier \dQuote{signed} in \code{type = "signed"} refers to the
middle coefficient \eqn{C}, not to \eqn{Y} itself.  The underlying
Ding, Li & Jordan (2010) sign-splitting updates require \eqn{Y \ge 0}
to guarantee monotone descent; supplying a signed \eqn{Y} triggers an
error.  For a signed data matrix, see \code{\link{nmfkc.signed}}.
}
\section{Lifecycle}{

This function is \strong{experimental}. The interface may change in
future versions; details are to be described in an upcoming paper.
}

\seealso{
\code{\link{nmfkc.net.ecv}}, \code{\link{nmfkc.net.DOT}}
}
