R/SummarizeMultiToolsMultiDatasets.R

In WuyangFF95/SynSigEval: Evaluate Results of Mutational Signature Analysis Software on Synthetic Spectra Created by Package SynSigGen

#' Summarize results for multiple datasets, by different computational approaches.
#'
#' Summarize results of mutational signature extraction and exposure inference
#' by multiple computational approaches on multiple datasets. Before running this
#' function, make sure the summary file for each single data set
#'  \code{toolSummaryPaths}/\code{OneToolSummary.Rda} exists.
#'
#' \code{OneToolSummary.Rda} is generated by \code{\link{SummarizeOneToolMultiDatasets}}).
#'
#' @param toolSummaryPaths Paths of top-level dataset directories trees you want
#' to investigate.
#' E.g. "./S.0.1.Rsq.0.1"
#'
#' Note: \code{OneToolSummary.RDa} are expected to be exist under
#' \code{toolSummaryPaths}.
#'
#' @param out.dir Path of the output directory.
#'
#' @param display.datasetName Whether to put the name of spectra datasets inside of
#' the csv outputs of summary tables.
#'
#' @param sort.by.composite.extraction.measure Whether to re-order the computational
#' approaches on violin plots, based on the mean of composite measure.
#'
#' \code{"descending"}: Put the computational approach with the highest mean composite
#' measure to the left, and arrange approaches in descending order.
#' \code{"ascending"}:  Put the computational approach with the lowest mean composite
#' measure to the left, and arrange approaches in ascending order.
#' Anything else: Keep the computational approaches in a smart alphabetical order embedded with numbers,
#' defined by \code{\link[gtools]{mixedsort}}.
#'
#' @param overwrite Whether to overwrite the contents in out.dir if
#' it already exists. (Default: FALSE)
#'
#' @importFrom rlang .data
#'
#' @importFrom utils write.csv
#'
#' @export
#'
SummarizeMultiToolsMultiDatasets <- function(
  toolSummaryPaths,
  out.dir,
  display.datasetName = FALSE,
  sort.by.composite.extraction.measure = "descending",
  overwrite = FALSE){

  # I. Create output directory ------------------------------------------------
  if (dir.exists(out.dir)) {
    if (!overwrite) stop(out.dir, " already exits")
  } else {
    dir.create(out.dir, recursive = T)
  }



  # II. Summarize extraction performance --------------------------------------
  FinalExtr <- SummarizeMultiToolsMultiDatasetsExtr(
    toolSummaryPaths,
    out.dir,
    display.datasetName = display.datasetName,
    sort.by.composite.extraction.measure = "descending",
    overwrite = FALSE)



  # III. Combine toolwise summary of exposure inference, if exists ------------
  #
  # Here toolwise summary object for exposure inference refers to
  # "OneToolSummary$AggManhattanDist".
  #
  flag_exposure_summary <- TRUE

  for(toolSummaryPath in toolSummaryPaths){
    ## Add OneToolSummary <- NULL to please R check
    OneToolSummary <- NULL
    load(paste0(toolSummaryPath,"/OneToolSummary.RDa"))
    if(is.null(OneToolSummary$AggManhattanDist)){
      #message("Skip summarizing scaled Manhattan distance...\n")
      flag_exposure_summary <- FALSE
      break
    }
  }

  if (flag_exposure_summary == TRUE) {
    FinalAttr <- SummarizeMultiToolsMultiDatasetsAttr(
      toolSummaryPaths,
      out.dir,
      display.datasetName = display.datasetName,
      sort.by.composite.extraction.measure = "descending",
      overwrite = FALSE)
  }



  # IV. Return the list "FinalSummary" ----------------------------------------
  FinalSummary <- list()
  FinalSummary$FinalExtr <- FinalExtr
  if(flag_exposure_summary == TRUE) {
    FinalSummary$FinalAttr <- FinalAttr
  }
  save(FinalSummary,file = paste0(out.dir,"/FinalSummary.RDa"))
  return(FinalSummary)
}