% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select.central.genes.R
\name{select.central.genes}
\alias{select.central.genes}
\title{Select Central Genes from Meta-Networks via Eigenvector Centrality}
\usage{
select.central.genes(
  seurat.obj = NULL,
  network = NULL,
  n.net = NULL,
  k = 1,
  n.per.component = 4,
  keep.responses = FALSE
)
}
\arguments{
\item{seurat.obj}{A \code{Seurat} object containing NeighbourNet results,
with both cell-specific networks and meta-networks stored in the
\code{NNet.mod} list within the \code{misc} slot. This list is generated
by \code{\link{run.nn.reg}} and subsequently updated by
\code{\link{build.meta.network}}.}

\item{network}{Optional 3D tensor of networks with dimension order
(responses x predictors x cells).}

\item{n.net}{A integer specifying the number of leading meta-networks from which
central genes are extracted}

\item{k}{A integer specifying the number of leading eigenvectors (components) to extract from
each meta-network when scoring central genes.}

\item{n.per.component}{Integer; number of top-scoring genes to select per
eigenvector and per meta-network. Default: \code{4}.}

\item{keep.responses}{A logical to control whether responses are also selected.
\itemize{
  \item If \code{FALSE} (default), both responses and predictors are
    selected based on eigenvector centrality scores.
  \item If \code{TRUE}, all responses are retained (no selection) and only
    predictors are selected as central genes.
}}
}
\value{
A list with elements:
  \itemize{
    \item \code{central.responses}: Character vector of selected central
      response genes. When \code{keep.responses = TRUE}, this may contain
      all responses.
    \item \code{central.predictors}: Character vector of selected central
      predictor genes.
    \item \code{response.module}: Factor giving the meta-network membership
      label (\code{"M1"}, \code{"M2"}, ...) for each unique
      \code{central.responses}.
      Set to \code{NULL} when all responses are kept without assignment.
    \item \code{predictor.module}: Factor giving the meta-network membership
      label for each unique \code{central.predictors}. Set to \code{NULL} when all predictors are
      kept without assignment.
  }
}
\description{
Identifies "central" response and predictor genes from NeighbourNet
meta-networks by decomposing each meta-network into principal components
(via singular value decomposition, SVD) and selecting genes with the
highest absolute loadings on leading singular vectors. These loadings
correspond to each gene’s eigenvector centrality within the meta-network,
capturing genes that are most influential in the overall co-expression
structure. The function optionally operates directly on a supplied
meta-network tensor or retrieves it from a \code{Seurat} object prepared by
the NeighbourNet workflow.
}
\details{
\strong{Eigenvector centrality interpretation}
\itemize{
  \item Each meta-network is treated as a weighted bipartite graph between
        response and predictor genes.
  \item The singular vectors from SVD represent the principal axes of
        variation in this bipartite graph. Genes with high absolute loadings
        on leading singular vectors have strong co-expression links with
        other highly connected genes. This is analogous to high
        \emph{eigenvector centrality} in network theory.
  \item Selecting top-loading genes across singular vectors therefore yields
        a set of “hub-like” genes that summarise the
        co-expression pattern of each meta-network.
}

\strong{Selection strategy}
\itemize{
  \item For each meta-network, a truncated SVD is applied to the
        weighted adjancency matrix. 
  \item Absolute singular vector loadings are used as eigenvector centrality
        scores.
  \item Genes with the highest loadings per component (up to
        \code{n.per.component}) are selected.
  \item Previously selected genes are zeroed out before selecting additional
        components, ensuring diverse representation across meta-networks.
}
}
\examples{
# From a Seurat object with NNet meta-networks
sel <- select.central.genes(seurat.obj,
                            n.net = 5,
                            k = 2,
                            n.per.component = 3)

# View top eigen-central genes
head(sel$central.predictors)

}
\seealso{
\code{\link{build.meta.network}}
}
