% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/visualise.network.R
\name{visualise.network}
\alias{visualise.network}
\title{Visualise Receptor–TF–Target Pathways on NeighbourNet Cell-Specific Networks.}
\usage{
visualise.network(
  seurat.obj,
  i,
  meta.network = FALSE,
  fix.cluster = TRUE,
  hubs = NULL,
  n.clu = 4,
  cutoff = NULL,
  show.pathways = TRUE,
  change.receptors = TRUE,
  receptor.activity = c("cprod", "dist"),
  check.receptor.expression = TRUE,
  scale.ppr = FALSE,
  scale.network = FALSE,
  scale.signifiance = FALSE,
  swap.layers = FALSE,
  k = 2,
  n.per.component = 10,
  radius = NULL,
  pie.radius = 0.05,
  text.size = 4
)
}
\arguments{
\item{seurat.obj}{A \code{Seurat} object with a \code{NNet.visualise.setting}
list stored in the \code{misc} slot. This list is created by \code{\link{prepare.visualise}}.}

\item{i}{Index of the cell or meta-network component to visualise.}

\item{meta.network}{A logical indicating whether to visualise a NeighbourNet
meta-network component instead of a per-cell network. If \code{TRUE}, the
\code{"meta.network"} assay is used. Default is \code{FALSE}.}

\item{fix.cluster}{A logical indicating whether to reuse the gene clustering
from \code{NNet.visualise.setting} when assigning clusters to the second
gene layer (\code{g2}). If \code{FALSE}, clusters are re-estimated from the
current network. Default is \code{TRUE}.}

\item{hubs}{An optional character vector of hub genes in \code{g2}. If
supplied and \code{fix.cluster = FALSE}, clusters are inferred by assigning
each \code{g2} gene to the closest hub. If \code{NULL}, hubs are not used
for clustering.}

\item{n.clu}{An integer specifying the maximum number of clusters for
\code{g2} genes. Default is \code{4}. The effective number of clusters is
truncated when few genes are available.}

\item{cutoff}{A numeric value specifying the p-value threshold used to define
significant co-expression for edge evidence. If \code{NULL}, the default is
taken from \code{NNet.mod$defaults$cutoff} stored in the \code{misc} of the Seurat object.
Values less than 0 are clamped to 0.}

\item{show.pathways}{A logical indicating whether receptor layers and
intermediate signalling paths (via a prior signalling graph) should be
included in the visualisation. If \code{FALSE}, only the two gene layers
(\code{g1} and \code{g2}) are plotted. Default is \code{TRUE}.}

\item{change.receptors}{A logical indicating whether to select a subset of
receptors for plotting based on activity (e.g., eigen-like centrality on
inferred receptor–target activity). If \code{FALSE}, receptors supplied in
\code{NNet.visualise.setting} are used as is. Default is \code{TRUE}.}

\item{receptor.activity}{A character string specifying how the prior model of 
receptor–TF interaction and TF–target (\code{g1}–\code{g2}) co-exression network are
combined when computing receptor–g1 activity. Options are \code{"cprod"}
(cross-product aggregation) and \code{"dist"} (max-over-path aggregation).
Default is \code{"cprod"}.}

\item{check.receptor.expression}{A logical indicating whether receptor
activity should be weighted by receptor expression in the selected cell or
component. Default is \code{TRUE}.}

\item{scale.ppr}{A logical indicating whether to normalise the receptor–TF
prior model (PageRank matrix) by receptor-wise norms. Default is \code{TRUE}.}

\item{scale.network}{A logical indicating whether to normalise the 
co-expression network by \code{g1}-wise norms before computing activity. Default is
\code{TRUE}.}

\item{scale.signifiance}{A logical indicating whether node and edge weights
should be scaled by their maximum significance (derived from p-values),
rather than raw co-expression magnitudes. Default is \code{FALSE}.}

\item{swap.layers}{A logical indicating whether to reverse the order of
\code{g1} and \code{g2} in the concentric layout (inner vs outer ring).
Default is \code{FALSE}.}

\item{k}{An integer controlling the number of singular vectors used when
selecting active receptors (layer \code{g4}) based on receptor–target
activity, analogous to an eigenvector centrality based selection in 
\code{\link{select.central.genes}} Default is \code{2}.}

\item{n.per.component}{An integer indicating the number of top receptors per
component (or singular vector) to consider when selecting candidate
receptors. Default is \code{10}.}

\item{radius}{Optional numeric vector control the radii of concentric layers.}

\item{pie.radius}{A numeric value giving the base radius of node pies in
the scatterpie representation. Default is \code{0.05}.}

\item{text.size}{A numeric value giving the size of gene labels in the
plotted network. Default is \code{4}.}
}
\value{
A \code{ggplot} object (built with \pkg{ggraph} and
  \pkg{ggplot2}) representing a layered receptor–TF–target network. The plot
  includes:
\itemize{
  \item concentric layers for \code{g1} and \code{g2}, and optionally
        intermediate signalling nodes (\code{g3}) and receptors (\code{g4});
  \item edge arrows and line types encoding prior evidence and direction;
  \item node pies summarising cluster assignments and activity contributions.
}
The underlying graph structure is built internally using \pkg{igraph}, but
only the final \code{ggplot} object is returned.
}
\description{
This function visualises NeighbourNet co-expression networks as a layered
receptor–TF–target signalling diagram. It takes pre-computed visualisation
settings from \code{\link{prepare.visualise}} and, for a given cell or
meta-network component, builds a multi-layer graph linking upstream receptors
to downstream gene modules. Edges are weighted by co-expression strength and
annotated by prior GRN evidence, and node shapes are represented as
cluster-level pie charts.
\cr
\cr
\strong{Interpretation}
When NeighbourNet is used to build TF–target co-expression networks
(for example, targets as responses and TFs as predictors), this function
provides prior knowledge enriched visualisation of networks as four concentric
layers. From the innermost to the outermost layer, these are:
\itemize{
  \item \code{g1} (targets): target genes, placed at the centre of the plot.
  \item \code{g2} (TFs): transcription factors surrounding the targets.
        TFs are grouped by expression-based clustering (node colour), and
        each TF is assigned a significance profile summarised as a pie chart
        (the fraction of the pie filled reflects the likelihood of
        co-expression with the \code{g1} targets).
  \item \code{g3} (intermediate signalling nodes): optional intermediate
        signalling molecules placed between TFs and receptors. These nodes
        represent the shortest signalling paths that connect receptors to
        TFs in a prior signalling graph.
  \item \code{g4} (receptors): the most active upstream receptors on the
        outermost layer. Each receptor is linked to a TF that is inferred to
        mediate its influence on the targets. Receptors are coloured in
        accordance with TF clusters, and the proportion of colour fill
        reflects their relative activity or expression.
}
The connections between \code{g1} and \code{g2} encode TF–target
co-expression annotated by prior gene-regulatory evidence. Edges represent
three levels of support: no edge (no significant relationship), dashed edges
for significant co-expression only, and solid edges when significant
co-expression is also supported by prior GRN evidence (with different
arrow styles indicating activation versus repression). The \code{g3} and
\code{g4} layers summarise upstream signalling pathways that exert strong
influence on the observed TF–target co-expression patterns.
}
\details{
This function visualises a single NeighbourNet network (either a cell-level
network or a meta-network component) using gene sets and priors prepared by
\code{\link{prepare.visualise}}. The first two layers (\code{g1} and
\code{g2}) correspond to response and predictor gene sets. Co-expression between
\code{g1} and \code{g2} is extracted from the selected NeighbourNet assay
(effect, p-value, or meta-network) via \code{\link{get.network}}, with
associated p-values used to define an edge-specific significance measure.

Node weights for \code{g1} and \code{g2} are derived from the maximum
significance of their incident edges and can be optionally rescaled by
\code{scale.signifiance}. Edge weights are then aggregated into cluster-level
pies, showing how strongly each layer contributes to different \code{g2}
modules. The \code{evidence} matrix from \code{NNet.visual.setting} encodes prior GRN evidence
for \code{g1}–\code{g2} pairs and is used to annotate edges as stimulatory
or inhibitory where such information is available.

When \code{show.pathways = TRUE}, the function also incorporates a
receptor–\code{g2} prior (generated by \code{\link{get.prior.model}}) and a signalling graph
(generated by \code{\link{get.gr.adj}}) to construct upstream receptor layers. 
Receptor-to-\code{g1} activity is first inferred by combining the receptor–\code{g2} prior model with the
pruned \code{g1}–\code{g2} co-expression network, and
weighted by receptor expression in the selected cell or component
(\code{check.receptor.expression}). A subset of receptors (\code{g4}) and
intermediate signalling nodes (\code{g3}) is then chosen based on activity
and shortest paths in \code{sig.graph}, and added as outer layers in the
layout.

Finally, the multi-layer graph is laid out using a concentric layout, with
the order of layers controlled by \code{swap.layers} and \code{radius}, and
rendered via \pkg{ggraph}. Pies from \pkg{ggforce::geom_scatterpie} summarise
cluster-level contributions for each node, while edge arrows and line types
encode directionality and prior evidence.
}
\examples{
# Assume NeighbourNet has been fitted and visual settings prepared:
# seurat.obj <- prepare.graph(...)
# seurat.obj <- prepare.reg(seurat.obj, ...)
# seurat.obj <- run.nn.reg(seurat.obj, ...)
# seurat.obj <- build.meta.network(seurat.obj, ...)
# seurat.obj <- prepare.visualise(seurat.obj)

# Visualise the network for a single cell
p <- visualise.network(seurat.obj, i = 1)
print(p)

# Visualise a meta-network component with receptor pathways
p.meta <- visualise.network(
  seurat.obj,
  i = 1,
  meta.network = TRUE,
)
print(p.meta)

}
\seealso{
\code{\link{prepare.visualise}}, \code{\link{receptor.activity}}
}
