% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/prepare.visualise.R
\name{prepare.visualise}
\alias{prepare.visualise}
\title{Prepare Gene and Receptor Settings for NeighbourNet Visualisation}
\usage{
prepare.visualise(
  seurat.obj,
  n.clu = 4,
  central.genes = NULL,
  check.gr.evidence = TRUE,
  t = 2,
  p = NULL,
  as.g2 = c("predictors", "responses"),
  g1 = NULL,
  g2 = NULL,
  receptors = 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{n.clu}{An integer specifying the maximum number of clusters used to
group genes based on their PC loadings when defining hub genes. Default is
\code{4}.}

\item{central.genes}{An optional list of central genes, typically the output
of \code{\link{select.central.genes}}, containing elements such as
\code{central.responses} and \code{central.predictors}. If provided and
\code{g1} / \code{g2} are \code{NULL}, these central genes are used to
initialise \code{g1} and \code{g2}.}

\item{check.gr.evidence}{A logical indicating whether prior GRN evidence
should be used to annotate and weight gene–gene relationships. If
\code{TRUE}, TF–target adjacency from \code{\link{get.gr.adj}} and a GRN
graph \code{gr.graph} (in the NeighbourNet namespace) are used to
distinguish supported and unsupported edges. Default is \code{TRUE}.}

\item{t}{A numeric value passed to \code{\link{get.gr.adj}} that controls
the depth or order of TF–target adjacency used as prior GRN evidence.
Default is \code{2}.}

\item{p}{A numeric value passed to \code{\link{get.prior.model}} specifying the quantile threshold
for pruning the PPR matrix. If \code{NULL}, the default threshold stored in \code{\link{receptor.ppr}$ltf}
is used. Default is \code{NULL}.}

\item{as.g2}{A character string indicating whether \code{g2} (the second
gene layer) should correspond to \code{"predictors"} or \code{"responses"}
in the NeighbourNet model. This choice determines which side of the
effect tensor is treated as the upstream or downstream gene set. Default
is \code{"predictors"}.}

\item{g1}{An optional character vector specifying the first gene layer to
visualise (e.g. responses if \code{as.g2 = "predictors"}). If \code{NULL},
it is derived from \code{central.genes} and intersected with the
corresponding default gene set in the NeighbourNet model.}

\item{g2}{An optional character vector specifying the second gene layer to
visualise (e.g. predictors if \code{as.g2 = "predictors"}). If \code{NULL},
it is derived from \code{central.genes} and intersected with the
corresponding default gene set in the NeighbourNet model.}

\item{receptors}{An optional character vector of receptors to visualise.
If \code{NULL}, use all receptors available in the prior knowledge model
obtained from \code{\link{get.prior.model}}.}
}
\value{
A \code{Seurat} object with an additional list named \code{NNet.visual.setting}
stored in its \code{misc} slot. This list contains:
\item{g1}{The ordered first-layer gene set used for visualisation.}
\item{g2}{The ordered second-layer gene set used for visualisation.}
\item{clu.g12}{A \code{hclust} object describing hierarchical clustering of
               selected genes based on PCs.}
\item{clu.g12}{A \code{hclust} object describing hierarchical clustering of
               \code{g2} genes based on PCs.}
\item{hubs}{A character vector of hub genes, one per cluster, selected to
            represent major loading patterns.}
\item{receptors}{The subset of receptors to visualise, if any.}
\item{ppr}{A receptor–gene prior model (receptors x \code{g2}
               set).}
\item{as.g2}{The role of \code{g2} in the NeighbourNet model
             (\code{"predictors"} or \code{"responses"}).}
\item{evidence}{A matrix encoding prior GRN evidence for gene–gene
                relationships between \code{g1} and the \code{g2}
                set, used for visual annotation.}
}
\description{
This function prepares gene sets, hub genes, receptor priors, and GRN-based
evidence required for visualising NeighbourNet co-expression networks. It
selects and orders central genes, identifies cluster-specific hub genes
based on PC loadings, constructs a receptor–gene prior matrix, and encodes
optional prior GRN evidence for edges. The resulting settings are stored in
the \code{misc} slot of the \code{Seurat} object for downstream plotting
and visualisation routines.
}
\details{
This function organises and annotates genes for visualising NeighbourNet
co-expression networks. Starting from either user-specified gene sets
(\code{g1}, \code{g2}) or central genes obtained from
\code{\link{select.central.genes}}, it defines two gene layers aligned with
the response and predictor sides of the NeighbourNet model, depending on
\code{as.g2}. These genes are projected into the PC space, and clustered via
hierarchical clustering on their PC correlations. Within each cluster,
a representative hub gene is selected, yielding one hub per cluster that captures
dominant variation patterns across PCs.

In parallel, a receptor–g2 prior model is extracted and stored as \code{ppr}. It receptors'
prior regulatory potential to the second gene layer and can be used to overlay
upstream receptor influence in downstream visualisation.

If \code{check.gr.evidence = TRUE}, GRN-based evidence is extrated from \code{\link{get.gr.adj}} 
to construct an \code{evidence} matrix that annotates co-expression between g1 and g2 as supported or
unsupported by prior regulatory knowledge (and optionally distinguishes
activation and inhibition). If \code{check.gr.evidence = FALSE}, all
co-expression edges are treated as stimulatory in the visualisation.
}
\examples{
# Select central genes from meta-networks
sel <- select.central.genes(seurat.obj)

# Prepare visualisation settings using central genes (predictors as g2)
seurat.obj <- prepare.visualise(
  seurat.obj,
  n.clu = 4,
  as.g2 = "predictors",
  central.genes = sel
)

# Access visual settings
vis.set <- Seurat::Misc(seurat.obj, "NNet.visual.setting")
str(vis.set)

}
\seealso{
\code{\link{select.central.genes}}, \code{\link{get.gr.adj}}
}
