% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get.network.R
\name{get.network}
\alias{get.network}
\title{Extract Per-Cell Gene Co-Expression Networks}
\usage{
get.network(
  seurat.obj,
  i = NULL,
  assay = NULL,
  remove.self.loops = NULL,
  responses = NULL,
  predictors = NULL,
  f = NULL,
  drop = TRUE,
  cutoff = NULL
)
}
\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}}.}

\item{i}{Cells for which to extract networks. Can be:
\itemize{
  \item \code{NULL} (default): use the cells stored in \code{NNet.mod$cells}.
  \item Integer indices matching \code{NNet.setting$all.cells}.
  \item A character vector of cell names matching \code{NNet.setting$all.cells}.
}}

\item{assay}{Which network to extract. One of \code{"effect"}, \code{"p.val"},
or \code{"meta.network"}. If \code{NULL}, uses \code{defaults$assay}.}

\item{remove.self.loops}{Logical; whether to zero out self-connections. If \code{NULL},
uses \code{defaults$remove.self.loops}.}

\item{responses}{A character vector of response genes to extract. If \code{NULL},
uses \code{defaults$responses}.}

\item{predictors}{A character vector of predictor genes to extract. If \code{NULL},
uses \code{defaults$predictors}.}

\item{f}{A function to transform effect values for downstream use (e.g.,
an importance score). If \code{NULL}, uses \code{defaults$f}. Ignored
when \code{assay = "p.val"} or \code{"meta.network"}.}

\item{drop}{Logical; if \code{TRUE} (default), drops the one slice arraies to
matrices for convenience.}

\item{cutoff}{Numeric p-value threshold in [0, 1] for pruning based on 
edge significance stored in \code{NNet.mod$p.val}.
If \code{NULL}, uses \code{defaults$cutoff}. The \code{p.val} tensor will 
be calculated instantly when it is not present in the \code{NNet.mod} list.}
}
\value{
A network for the requested \code{assay} with dimensions:
  \itemize{
    \item \strong{effect / p.val}: (responses × predictors × cells) array.
      If \code{drop = TRUE} and any dimension equals 1, a matrix is returned:
      (responses x predictors) (a single cell),
      (predictors x cells) (a single response),
      or  (responses x cells) (a single predictor).
    \item \strong{meta.network}: the corresponding slice(s) from
      \code{NNet.mod$meta.network$meta.network[responses, predictors, i]} with the
      same dropping behavior.
  }
}
\description{
Retrieves effect or p-value networks (or meta-networks) from a \code{Seurat}
object prepared by the NeighbourNet workflow. Supports optional pruning,
transformation, self-loop removal, and flexible cell indexing. By default,
argument values fall back to \code{NNet.mod$defaults} (\code{defaults}).
}
\details{
\strong{Assay behavior}
\itemize{
  \item \emph{effect}: If \code{NNet.mod$smoothed = TRUE}, returns the stored smoothed
        effects for the requested cells (cells not in \code{NNet.mod$cells} will cause an error). If \code{NNet.mod$smoothed = FALSE}, effects
        are projected to the requested cells by applying the stored Laplacian
        operator \code{NNet.mod$w}.
  \item \emph{p.val}: If \code{NNet.mod$p.val} exists and all requested cells are in
        \code{NNet.mod$cells}, returns the stored p-value tensor. Otherwise, p-values are
        computed from the (smoothed or projected) effects using per-response
        null distribution.
  \item \emph{meta.network}: Returns slices of \code{NNet.mod$meta.network$meta.network}.
}

\strong{Pruning}
\itemize{
  \item For \emph{effect} assay, pruning uses p-values. 
  Effects with corresponding p-values less than \code{cutoff} are zeroed.
  \item For \emph{p.val} assay, entries less than \code{cutoff} are set to zero.
}

\strong{Transformation}
\itemize{
  \item When \code{assay = "effect"}, the returned tensor/matrix is transformed
        by \code{f} (default \code{function(x) 2*x^2}) to yield an
        importance score. No transform is applied for \code{"p.val"} or
        \code{"meta.network"}.
}
}
\examples{
mod <- Seurat::Misc(seurat.obj, "NNet.mod")

# Default extraction (uses mod$defaults): smoothed effects, default cells
net <- get.network(seurat.obj)

# Effects for a specific set of cells (by name) and a gene panel
cells <- head(names(mod$cells), 3)
responses <- head(mod$gene.sets$responses$genes, 5)
predictors <- head(mod$gene.sets$predictors$genes, 10)
net.eff <- get.network(seurat.obj, i = cells,
                       assay = "effect", responses = responses, predictors = predictors)

# Extract P-values
net.p <- get.network(seurat.obj, assay = "p.val", cutoff = 0.9)

# Meta-network slices (3rd component) without dropping dimensions
net.meta <- get.network(seurat.obj, assay = "meta.network", i = 3, drop = FALSE)

# Effect network with pruning + custom transform, keeping self-loops
net.imp <- get.network(seurat.obj,
  assay = "effect", cutoff = 0.95,
  f = function(x) abs(x),
  remove.self.loops = FALSE
)

}
\seealso{
\code{\link{run.nn.reg}}, \code{\link{set.defaults}}
}
