% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/receptor.activity.R
\name{receptor.activity}
\alias{receptor.activity}
\title{Infer Receptor Activity from NeighbourNet TF–Target Networks}
\usage{
receptor.activity(
  seurat.obj,
  i = NULL,
  meta.network = FALSE,
  cutoff = NULL,
  check.receptor.expression = TRUE,
  check.gr.evidence = TRUE,
  t = 2,
  p = NULL,
  scale.ppr = TRUE,
  scale.network = TRUE,
  as.tfs = c("predictors", "responses"),
  receptors = NULL,
  tfs = NULL,
  targets = NULL,
  receptor.activity = c("cprod", "dist")
)
}
\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}}.
To optionally infer receptor activity on meta-networks (set \code{meta.network = TRUE}), the \code{NNet.mod}
should be updated by a subsequent run of \code{\link{build.meta.network}}.}

\item{i}{Optional index of cells or meta-network components for which to
compute receptor activity. If \code{NULL}, uses \code{NNet.mod$cells} for
per-cell networks or all meta-network components when
\code{meta.network = TRUE}.}

\item{meta.network}{A logical indicating whether to compute activity on
NeighbourNet meta-networks instead of per-cell networks. If \code{TRUE},
the \code{"meta.network"} assay is used and each component is treated as a
meta-cell. Default is \code{FALSE}.}

\item{cutoff}{A numeric value specifying the p-value threshold to prune insignificant
co-expression values. If \code{NULL}, the default value is taken from \code{NNet.mod$defaults}.}

\item{check.receptor.expression}{A logical indicating whether receptor
activity should be down-weighted by receptor expression. Default is
\code{TRUE}.}

\item{check.gr.evidence}{A logical indicating whether TF–target edges should
be filtered by prior GRN evidence from
\code{\link{get.gr.adj}}. 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{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 TF–target 
co-expression network by target-wise norms before computing activity. Default is
\code{TRUE}.}

\item{as.tfs}{A character string indicating whether TFs are encoded as
\code{"predictors"} (columns) or \code{"responses"} (rows) in the
NeighbourNet networks. Default is \code{"predictors"}.}

\item{receptors}{A character vector of receptor genes to include. If
\code{NULL}, all receptors present in the prior model returned by
\code{\link{get.prior.model}} are used.}

\item{tfs}{A character vector of TFs to include. If \code{NULL},
TFs are taken from the default gene set stored in \code{NNet.mod$defaults}.}

\item{targets}{A character vector of target genes to include. If \code{NULL},
targets are taken from the default gene set stored in \code{NNet.mod$defaults}.}

\item{receptor.activity}{A character string specifying how receptor–TF and
TF–target information should be combined. Options are \code{"cprod"}
(cross-product aggregration that measures cosine similarity, default)
and \code{"dist"} (max-over-path aggregation).}
}
\value{
If multiple cells or meta-network components are requested (\code{length(i) > 1}
or \code{i = NULL}), the function returns a list with:
\item{receptor.act}{A matrix of receptor activity scores
                    (receptors x cells/components).}
\item{tf.act}{A matrix of TF activity scores (TFs x cells/components).}
\item{target.act}{A matrix of target activity scores
                  (targets x cells/components).}

If a single cell or component is requested, the function returns a list with:
\item{act.mat}{A receptor–target activity matrix (receptors x targets).}
\item{ppr}{The receptor–TF prior used after any scaling and expression
           weighting.}
\item{network}{The TF–target network used for activity computation.}
}
\description{
This function infers receptor, transcription factor (TF), and target activity
by combining a receptor–TF prior model (personalised PageRank) with NeighbourNet
TF–target co-expression networks. Activity can be evaluated at the per-cell level
or on meta-networks, and can be optionally filtered by receptor expression and 
prior gene regulatory network (GRN) evidence.
}
\details{
This function integrates three hierarchical components to infer receptor activity:
(i) a receptor–TF prior model obtained from \code{\link{get.prior.model}},
(ii) TF–target co-expression networks derived from NeighbourNet, and
(iii) optional TF–target adjacency matrices from \code{\link{get.gr.adj}} as
prior gene regulatory network (GRN) evidence. Together, these components
define a receptor–TF–target signalling cascade that quantifies how upstream
receptors potentially influence downstream target genes through TFs.

For each cell or meta-network component, the receptor–TF prior model encodes
the probability of regulatory transmission from receptors to TF, 
while the TF–target network represents local co-expression
relationships inferred by NeighbourNet. Receptor activity is computed by
aggregating these two layers to estimate receptor influence on downstream
targets, mediated by TFs. The resulting matrices describe receptor-, TF-, and
target-level activity for each cell or component, providing an interpretable
summary of upstream signalling dynamics.

Activity can be inferred from per-cell networks (default) or from
meta-networks when \code{meta.network = TRUE}. The arguments \code{scale.ppr} and
\code{scale.network} apply L2-normalisation to the prior model and
co-expression network respectively, reducing the influence of highly connected
nodes and ensuring comparable contribution across genes. The options
\code{check.receptor.expression} and \code{check.gr.evidence} introduce two
filters on receptor activity : the first enforces that receptors must be transcriptionally
detected, while the second prunes TF–target co-expression to those 
supported by prior GRN knowledge.

The argument \code{receptor.activity} controls how the two layers are
combined: \code{"cprod"} performs a cross-product aggregation equivalent to
measuring cosine similarity between receptor–TF and TF–target profiles,
while \code{"dist"} applies a max-over-path operation that highlights the
strongest possible receptor–target link through any intermediate TF.
}
\examples{
# Per-cell receptor activity using default settings
act <- receptor.activity(seurat.obj)

# Meta-network receptor activity for the first three components
act <- receptor.activity(
  seurat.obj,
  meta.network = TRUE,
  i = 1:3
)


}
\seealso{
\code{get.prior.model}, \code{get.gr.adj}
}
