R/runNTP.R

In xlucpu/MOVICS: Multi-Omics integration and VIsualization in Cancer Subtyping

#' @name runNTP
#' @title Run nearest template prediction
#' @description Using Nearest Template Prediction (NTP) based on predefined templates derived from current identified subtypes to assign potential subtype label on external cohort.
#' @param expr A numeric matrix with row features and sample columns; data is recommended to be z-scored.
#' @param templates A data frame with at least two columns; class (coerced to factor) and probe (coerced to character).
#' @param scaleFlag A logic value to indicate if the expression data should be further scaled. TRUE by default.
#' @param centerFlag A logic value to indicate if the expression data should be further centered. TRUE by default.
#' @param nPerm An integer value to indicate the permutations for p-value estimation.
#' @param distance A string value to indicate the distance measurement. Allowed values contain c('cosine', 'pearson', 'spearman', 'kendall'); "cosine" by default.
#' @param seed An integer value for p-value reproducibility.
#' @param verbose A logic value to indicate whether console messages are to be displayed; TRUE by default.
#' @param doPlot A logic value to indicate whether to produce prediction heatmap; FALSE by default.
#' @param fig.path A string value to indicate the output path for storing the nearest template prediction heatmap.
#' @param fig.name A string value to indicate the name of the nearest template prediction heatmap.
#' @param width A numeric value to indicate the width of output figure.
#' @param height A numeric value to indicate the height of output figure.
#' @return A figure of predictive heatmap by NTP (.pdf) and a list with the following components:
#'
#'         \code{ntp.res}    a data.frame storing the results of nearest template prediction (see \link[CMScaller]{ntp}).
#'
#'         \code{clust.res}  similar to `clust.res` returned by `getMOIC()` or `get%algorithm_name%` or `getConsensusMOIC()`.
#'
#'         \code{mo.method}  a string value indicating the method used for prediction.
#' @export
#' @importFrom CMScaller ntp subHeatmap
#' @importFrom grDevices dev.copy2pdf
#' @examples # There is no example and please refer to vignette.
#' @references Hoshida, Y. (2010). Nearest Template Prediction: A Single-Sample-Based Flexible Class Prediction with Confidence Assessment. PLoS ONE 5, e15543.
runNTP <- function(expr       = NULL,
                   templates  = NULL,
                   scaleFlag  = TRUE,
                   centerFlag = TRUE,
                   nPerm      = 1000,
                   distance   = "cosine",
                   seed       = 123456,
                   verbose    = TRUE,
                   doPlot     = FALSE,
                   fig.path   = getwd(),
                   fig.name   = "ntpheatmap",
                   width      = 5,
                   height     = 5) {

  # message("Using up- or down-regulated biomarkers (templates) are highly recommended.\n")

  if(!is.element(distance, c("cosine", "pearson", "spearman", "kendall"))) {
    stop("the argument of distance should be one of cosine, pearson, spearman, or kendall.")
  }

  com_feat <- intersect(rownames(expr), templates$probe)
  message(paste0("--original template has ",nrow(templates), " biomarkers and ", length(com_feat)," are matched in external expression profile."))
  expr <- expr[com_feat, , drop = FALSE]
  templates <- templates[which(templates$probe %in% com_feat), , drop = FALSE]

  if(is.element(0,as.numeric(table(templates$class)))) {
    stop("at least one class has no probes/genes matched in template file!")
  }

  emat <- t(scale(t(expr), scale = scaleFlag, center = centerFlag))
  if(doPlot) {
    outFig <- paste0(fig.name,".pdf")
    ntp.res <- ntp(emat      = emat,
                   templates = templates,
                   doPlot    = doPlot,
                   nPerm     = nPerm,
                   distance  = distance,
                   nCores    = 1,
                   seed      = seed,
                   verbose   = verbose)
    invisible(dev.copy2pdf(file = file.path(fig.path, outFig), width = width, height = height))

  } else {
    ntp.res <- ntp(emat      = emat,
                   templates = templates,
                   doPlot    = doPlot,
                   nPerm     = nPerm,
                   distance  = distance,
                   nCores    = 1,
                   seed      = seed,
                   verbose   = verbose)
  }

  ntp.res[,setdiff(colnames(ntp.res),"prediction")] <- round(ntp.res[,setdiff(colnames(ntp.res),"prediction")], 4)
  ex.moic.res <- data.frame(samID = rownames(ntp.res),
                            clust = gsub("CS","",ntp.res$prediction),
                            row.names = rownames(ntp.res),
                            stringsAsFactors = FALSE)

  return(list(ntp.res = ntp.res, clust.res = ex.moic.res, mo.method = "NTP"))
}