% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/run.nn.reg.R
\name{run.nn.reg}
\alias{run.nn.reg}
\title{Run Nearest-Neighbor PC Regression for Gene Co-Expression Analysis}
\usage{
run.nn.reg(
  seurat.obj,
  responses = NULL,
  Y = NULL,
  predictors = NULL,
  t = 3,
  k = NULL,
  remove.self.loops = T,
  f = function(x) 2 * x^2,
  assay = c("effect", "p.val"),
  prune = TRUE,
  cutoff = 0.95,
  return.p.val = FALSE,
  return.smooth = TRUE,
  return.prune = FALSE
)
}
\arguments{
\item{seurat.obj}{A \code{Seurat} object on which \code{\link{prepare.graph}} and \code{\link{prepare.reg}} have been run.}

\item{responses}{A character vector of response gene names to return for the network ensemble. If \code{NULL}, uses all response genes from \code{NNet.setting}.}

\item{Y}{A custom response matrix (cells x responses). If provided, overrides \code{responses}.}

\item{predictors}{A character vector of predictor gene names to return for the network ensemble. If \code{NULL}, uses all predictor genes from \code{NNet.setting}.}

\item{t}{A numeric value indicating the power to scale the singular values of the Laplacian operator. Default is 3.}

\item{k}{An integer specifying the number of singular vectors to use in the Laplacian operator. Default is the number of nearest neighbors.}

\item{remove.self.loops}{A logical indicating whether to remove self-loops from networks for downstream analysis. Default is \code{TRUE}.}

\item{f}{A function to map the effect estimation to importance scores for downstream analysis. Default is \code{function(x) 2*x^2} that yields permutation feature importamce.}

\item{assay}{A character string indicating the co-expression measure to use in downstream analysis. Options are \code{"effect"} or \code{"p.val"}. Default is \code{"effect"}.}

\item{prune}{A logical indicating whether to prune networks based on p-values for downstream analysis. Default is \code{TRUE}.}

\item{cutoff}{A numeric value specifying the p-value threshold for pruning for downstream analysis.. Default is 0.95.}

\item{return.p.val}{A logical indicating whether to return p-values in addition to the effect tensor. Set to \code{FALSE} to save memory. Default is \code{FALSE}.}

\item{return.smooth}{A logical indicating whether to return the smoothed effect tensor.
If set to \code{TRUE}, networks will not be further smoothed in downstream analysis. Default is \code{TRUE}.}

\item{return.prune}{A logical indicating whether to return the pruned effect tensor.
If set to \code{TRUE}, networks will not be further pruned in downstream analysis. Default is \code{FALSE}.}
}
\value{
A \code{Seurat} object with a list named \code{NNet.mod} stored in its \code{misc} slot.
\code{NNet.mod} is a list containing:
\item{effect}{A tensor of effect sizes (responses x predictors x cells).}
\item{p.val}{A tensor of p-values (responses x predictors x cells) if \code{return.p.val = TRUE}.}
\item{meta.network}{Reserved for \code{\link{build.meta.network}}.}
\item{meta.response}{Reserved for \code{\link{build.meta.response}}.}
\item{mus}{A named vector of mean log-transformed noise distributions for each response.}
\item{sigmas}{A named vector of standard deviations for log-transformed noise distributions for each response.}
\item{subsampled}{A logical indicating whether cell subsampling was performed.}
\item{smoothed}{A logical indicating whether smoothed effects are returned.}
\item{pruned}{A logical indicating whether pruned effects are returned.}
\item{gene.sets}{A list of selected predictors, responses, and all genes used in the analysis. Includes TFs and targets subsets.}
\item{cells}{A vector of selected cell indices used in the analysis.}
\item{defaults}{Default settings used for network extraction, such as cutoff and pruning function.}
\item{custom.y}{A logical indicating whether a custom response matrix (\code{Y}) was provided.}
\item{w}{A list containing the Laplacian operator components (\code{u} and \code{vd}).}
}
\description{
This function performs nearest-neighbor regression on a Seurat object to measure
gene co-expression. It uses principal components (PCs) to smooth response
gene expression and calculates permutation feature importance as a co-expression measure.
The results are stored as a list named \code{NNet.mod} in the \code{misc}
slot of the Seurat object for downstream analysis.
}
\details{
This function performs nearest-neighbor PC regression to assess co-expression relationships between response
and predictor genes within a Seurat object. The co-expression measure is based on
permutation feature importance estimated by local gene variances,
enabling scalable analysis of transcriptional regulation. Parameters \code{remove.self.loops},
\code{f}, \code{assay}, \code{prune}, and \code{cutoff} define default settings for how networks will be
post-processed before downstream analysis, such as meta-network learning. However, these settings do not
immediately affect the regression analysis performed by this function. These defaults can be updated later
using \code{\link{set.defaults}}.
}
\examples{
# Assuming `seurat.obj` has been pre-processed with `prepare.reg`:
responses <- Seurat::Misc(seurat.obj, "NNet.setting")$responses \%>\%
             head(n =5)

# Run PC regression
seurat.obj <- run.nn.reg(
  seurat.obj,
  responses = responses,
)

# Check regression outcome settings
str(Seurat::Misc(seurat.obj, "NNet.mod"))

}
\seealso{
\code{\link{prepare.graph}}, \code{\link{prepare.reg}}, \code{\link{set.defaults}}
}
