% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network.embedding.R
\name{build.meta.network}
\alias{build.meta.network}
\alias{build.meta.response}
\title{Build Meta-Networks (Meta-response) via Network Embeddings (PCA / Non-Negative PCA)}
\usage{
build.meta.network(
  seurat.obj = NULL,
  network = NULL,
  k = 100,
  cutoff = NULL,
  big.memory = FALSE,
  scale = TRUE,
  truncated = TRUE,
  n.net = 20,
  non.neg = TRUE,
  max.iter = 1000,
  tol = 1e-10,
  return.p.val = TRUE
)

build.meta.response(
  seurat.obj = NULL,
  network = NULL,
  k = 100,
  cutoff = NULL,
  big.memory = FALSE,
  scale = TRUE,
  truncated = TRUE,
  n.net = 20,
  non.neg = TRUE,
  max.iter = 1000,
  tol = 1e-10,
  return.p.val = TRUE
)
}
\arguments{
\item{seurat.obj}{A \code{Seurat} object with a \code{NNet.mod} list stored in the
\code{misc} slot. This list is created by \code{\link{run.nn.reg}}. 
If provided, \code{assay} and gene panels are taken from
\code{NNet.mod$defaults}. Ignored when \code{network} is supplied.}

\item{network}{Optional 3D tensor of networks with dimension order
(responses x predictors x cells).
If supplied, \code{return.p.val} is forced to \code{FALSE}.}

\item{k}{A integer specifying ranks to keep for the “long-and-tall” matrix of concatenated network vectors.
Limited to \code{min(k, n.response * n.predictor, n.cell)}. Default: \code{100}.}

\item{cutoff}{A numeric value specifying the p-value threshold (in \code{[0, 1]}) passed to
\code{\link{get.network}} when pulling per-cell networks. \code{NULL} uses
defaults from \code{NNet.mod$defaults$cutoff}.}

\item{big.memory}{A logical indicating whether to load the full network tensor internally to reduce repeated reads.
Default: \code{FALSE}.}

\item{scale}{A logical indicating whether to scale each single-cell network by its Frobenius
norm across edges before aggregation (per-cell normalization). Default: \code{TRUE}.}

\item{truncated}{A logical indicating whether to retain only significant edge embeddings
(spectral-gap heuristic) before running nPCA; otherwise, use exactly \code{k}
embeddings. Default: \code{TRUE}. If \code{k < 100}, this is set to \code{FALSE}.}

\item{n.net}{A integer specifying the number of meta-networks to output. Default: \code{20}.}

\item{non.neg}{A logical indicating whether to perform nPCA (iterative deflation with
non-negativity constraints) on the edge-embedded matrix, then embeds cell networks
with nPCA loadings. Otherwise, embeds with standard PCA loadings. Default: \code{TRUE}.}

\item{max.iter}{A integer specifying the maximum iterations for calculating each nPCA component.
Default: \code{1000}.}

\item{tol}{A numeric value specifying the convergence tolerance for nPCA iterations. Default: \code{1e-10}.}

\item{return.p.val}{Logical; if \code{TRUE} and \code{assay == "effect"}, also returns
per–meta-network p-values by embedding the p-value tensor (\code{NNet.mod$p.val})
with the nPCA loadings. Forced to \code{FALSE} when \code{network} is supplied or
when \code{non.neg = FALSE}. Default: \code{TRUE}.}
}
\value{
If Seurat object is provided, then update it with
  \code{NNet.mod$meta.network} populated, which is, a list containing:
  \itemize{
    \item \code{meta.network}: Array of size
      (responses x predictors x \code{n.net}).
    \item \code{p.val}: An Array (same size) if \code{return.p.val = TRUE}; else \code{NULL}.
    \item \code{pcs}: A matrix of PC scores learnt on per-cell networks; rows = cells, columns = components.
    \item \code{pca.loadings}: A matrix of PCA loadings learnt on per-cell networks.
    \item \code{pca.sd}: A numeric vector of singular values from network covariance.
    \item \code{npca.loadings}: A matrix of PC scores learnt on per-cell networks; 
                                if \code{non.neg = TRUE}; else \code{NULL}.
    \item \code{scale}, \code{non.neg}: Echo of the input flags.
    \item \code{setting}: Copy of \code{NNet.mod$defaults} if \code{seurat.obj} was provided.
  }
}
\description{
\code{build.meta.network} aggregates per-cell networks into a low-dimensional set of
meta-networks by network embedding (nPCA on vectorised networks). Concatenating
network vectors yields an edge-by-cell “long-and-tall” matrix. For efficiency,
the edge dimension is first embedded by SVD/PCA, and then nPCA is applied to
the embedded matrix. It accepts either a \code{Seurat} object prepared by the
NeighbourNet workflow or a precomputed 3D network tensor. Similarly, using
\code{build.meta.response}, meta-responses representing functional gene modules can
be built by nPCA embedding on vectorised response profiles (cell*predictors-by-response). 
The detailed arguments and usage of \code{build.meta.network} is documented, and that of
\code{build.meta.response} is alike.
}
\details{
\strong{Edge embedding}: If both \code{responses} and \code{predictors} have size > 1, a
cell-by-cell kernel that represents co-variation in network structure across cells is computed. 
Eigen-decomposition is ran to construct a edge-embedding x cell matrix.
If one axis is size 1, perform SVD directly on the (edges × cells) matrix.

\strong{Rank selection}: If \code{truncated = TRUE}, a simple spectral-gap rule over the
tail of singular-value differences selects the working rank of the edge emebdding before nPCA.

\strong{Meta-networks}: Project per-cell network onto the first
\code{n.net} directions (nPCA or PCA) to obtain meta-network slices.
}
\examples{
# From a Seurat object (built by run.nn.reg)
seurat.obj <- build.meta.network(seurat.obj, k = 100, n.net = 20, non.neg = TRUE)

}
\seealso{
\code{\link{run.nn.reg}}, \code{\link{get.network}}
}
