% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/prepare.reg.R
\name{prepare.reg}
\alias{prepare.reg}
\title{Prepare a Seurat Object for PC Regression Analysis}
\usage{
prepare.reg(
  seurat.obj,
  responses = NULL,
  predictors = NULL,
  cells = NULL,
  check.expressed = FALSE
)
}
\arguments{
\item{seurat.obj}{A \code{Seurat} object on which \code{\link{prepare.graph}} has been ran.}

\item{responses}{A character vector of response gene names. Response gene expression will be low-rank approximated.
If \code{NULL}, all genes of PC embedding are used. Default is \code{NULL}.}

\item{predictors}{A character vector of predictor gene names. Local variance will be calculated on the provided predictors.
If \code{NULL}, all genes of PC embedding are used. Default is \code{NULL}.}

\item{cells}{A vector of cell indices to include. If \code{NULL}, uses pre-selected cells by \code{\link{select.cell}} or all cells if no
pre-selection was done. Default is \code{NULL}.}

\item{check.expressed}{A logical value indicating whether to prune local variance by if genes are expressed in the selected cells. Default is \code{TRUE}.}
}
\value{
A \code{Seurat} object with the updated \code{NNet.setting} stored in the \code{misc} slot.
  The updated settings include:
  \item{responses}{A character vector of selected response genes.}
  \item{predictors}{A character vector of selected predictor genes.}
  \item{genes}{A character vector of all selected genes (responses and predictors).}
  \item{cells}{A vector of selected cell indices, named by cell barcodes.}
  \item{lra}{A low-rank approximation matrix representing the reconstructed expression of response genes based on PCs.}
  \item{scale.gene}{A numeric vector of global gene scales.}
  \item{nn.scale.gene}{A sparse matrix of local variances for the selected genes in each selected cell.}
  \item{nn.scale.pc}{A matrix of local variances for the PCs in each selected cell.}
  \item{n.eff}{A numeric vector of effective neighborhood sizes for each selected cell.}
}
\description{
This function prepares a \code{Seurat} object for PC regression analysis by selecting response and predictor genes,
as well as the cells to include in the analysis. It calculates local variances for the selected genes and PCs
based on the KNN graph, which will be used for estimating permutation feature importance as co-expression measure.
The results are stored in the \code{NNet.setting} field of  the \code{misc} slot of the Seurat object.
}
\details{
This function sets up the data and settings required for performing PC regression
on a Seurat object, with results stored in the \code{NNet.setting} field of the \code{misc} slot.
It supports the analysis of gene co-expression by calculating local variances
for genes and PCs, which are essential for estimating permutation feature importance.

The function allows users to specify response and predictor genes, as well as subsets of cells, for the analysis.
If no responses or predictors are provided, all genes in the PC loadings are used by default.
Local variances are computed using the KNN graph stored in \code{NNet.setting}, enabling downstream co-expression analysis.
}
\examples{
# Assuming `seurat.obj` is a Seurat object on which `prepare.graph` has been ran.

# seurat.obj <- select.cell(seurat.obj) # Optional if the number of cells is large

# Select genes for PC regression
gene.list <- select.gene(seurat.obj)

# Prepare regression setting, use transcriptional factors as responses and targets as predictors
seurat.obj <- prepare.reg(seurat.obj, responses = gene.list$tfs, predictors = gene.list$targets)

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

}
\seealso{
\code{\link{prepare.graph}}, \code{\link{run.nn.reg}}
}
