# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# Exported
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
#' Personalized PageRank Results for Signaling Network
#'
#' A list containing the results of running the personalized PageRank (PPR) algorithm
#' on \code{sig.graph}. The PPR algorithm evaluates the regulatory potential of
#' receptors on target genes within an intra-cellular signaling network. This list
#' provides a prior model and the necessary parameters for refining the PPR matrix.
#'
#' @format A list with three elements:
#' \describe{
#'   \item{\code{ppr}}{A numeric matrix representing the personalized PageRank results.
#'   Rows correspond to receptors (source nodes), and columns correspond to targets.
#'   Each entry reflects the regulatory potential of a receptor on a target gene.}
#'   \item{\code{ltf}}{A numeric value representing the quantile threshold learned
#'   via NicheNet integration. Entries in the \code{ppr} matrix with regulatory
#'   potential below this quantile are set to zero, effectively pruning low-confidence interactions.}
#'   \item{\code{tfs}}{A character vector of transcription factor (TF) gene names
#'   available in the \code{ppr} matrix. These TFs are potential targets of receptors in the regulatory network.}
#' }
#'
#' @details
#' The \code{ppr} matrix provides a prior model of receptor-target regulatory potential,
#' where the regulatory effect of each receptor is evaluated using personalized PageRank
#' with receptors as source nodes. The \code{ltf} threshold is used to prune low-confidence
#' interactions, ensuring only high-confidence regulatory potentials are retained.
#'
#' This object is a key output of the NicheNet integration pipeline implemented by Ominipath, supporting downstream
#' analyses such as upstream signaling pathway (USP) inference and regulatory network refinement.
#'
#' @examples
#' # Access the PPR matrix
#' head(receptor.ppr$ppr)
#'
#' # View the learned threshold
#' receptor.ppr$ltf
#'
#' # Access the list of transcription factors
#' head(receptor.ppr$tfs)
#'
#' # Prune the PPR matrix based on the learned threshold
#' pruned_ppr <- receptor.ppr$ppr
#' pruned_ppr[pruned_ppr < quantile(pruned_ppr, receptor.ppr$ltf)] <- 0
#'
#' @seealso \code{\link{sig.graph}}, \code{\link{gr.graph}}
#'
#' @source Applying \code{igraph}'s \code{\link[igraph]{page_rank}} function on \code{\link{sig.graph}}.
#'
"receptor.ppr"
