R/14-zinbwave.R

In duohongrui/simmethods: A collection of 40+ simulation methods for singlce-cell RNA seqencing data

#' Estimate Parameters From Real Datasets by zinbwave
#'
#' This function is used to estimate useful parameters from a real dataset by
#' using `zinbEstimate` function in Splatter package.
#'
#' @param ref_data A count matrix. Each row represents a gene and each column
#' represents a cell.
#' @param verbose Logical.
#' @param other_prior A list with names of certain parameters. Some methods need
#' extra parameters to execute the estimation step, so you must input them. In
#' simulation step, the number of cells, genes, groups, batches, the percent of
#' DEGs are usually customed, so before simulating a dataset you must point it out.
#' See `Details` below for more information.
#' @param seed An integer of a random seed.
#' @importFrom splatter zinbEstimate
#' @return A list contains the estimated parameters and the results of execution
#' detection.
#' @export
#' @details
#' In zinbwave, users do not input other extra information usually. If users want
#' to check the parameters, please see [splatter::zinbEstimate()] or [splatter::ZINBParams()].
#'
#' @references
#' Zappia L, Phipson B, Oshlack A. Splatter: simulation of single-cell RNA sequencing data. Genome biology, 2017, 18(1): 1-15. <https://doi.org/10.1186/s13059-017-1305-0>
#'
#' Bioconductor URL: <https://bioconductor.org/packages/release/bioc/html/splatter.html>
#'
#' Github URL: <https://github.com/Oshlack/splatter>
#'
#' @examples
#' \dontrun{
#' ref_data <- simmethods::data
#' ## maybe it will take a long time
#' estimate_result <- simmethods::zinbwave_estimation(ref_data = ref_data,
#'                                                    other_prior = NULL,
#'                                                    verbose = TRUE,
#'                                                    seed = 111)
#' }
#'
zinbwave_estimation <- function(ref_data,
                                verbose = FALSE,
                                other_prior = NULL,
                                seed
){
  ##############################################################################
  ####                               Check                                   ###
  ##############################################################################
  if(!is.matrix(ref_data)){
    ref_data <- as.matrix(ref_data)
  }
  other_prior[["counts"]] <- ref_data
  estimate_formals <- simutils::change_parameters(function_expr = "splatter::zinbEstimate",
                                                  other_prior = other_prior,
                                                  step = "estimation")
  ##############################################################################
  ####                            Estimation                                 ###
  ##############################################################################
  if(verbose){
    message("Estimating parameters using zinbwave")
  }
  # Seed
  set.seed(seed)
  # Estimation
  estimate_detection <- peakRAM::peakRAM(
    estimate_result <- splatter::zinbEstimate(counts = estimate_formals[["counts"]],
                                              design.samples = estimate_formals[["design.samples"]],
                                              design.genes = estimate_formals[["design.genes"]],
                                              common.disp = estimate_formals[["common.disp"]],
                                              iter.init = estimate_formals[["iter.init"]],
                                              iter.opt = estimate_formals[["iter.opt"]],
                                              params = splatter::newZINBParams(),
                                              verbose = verbose,
                                              BPPARAM = BiocParallel::SerialParam())
  )
  ##############################################################################
  ####                           Ouput                                       ###
  ##############################################################################
  estimate_output <- list(estimate_result = estimate_result,
                          estimate_detection = estimate_detection)
  return(estimate_output)
}



#' Simulate Datasets by zinbwave
#'
#' This function is used to simulate datasets from learned parameters by `zinbSimulate`
#' function in Splatter package.
#'
#' @param parameters A object generated by [splatter::zinbEstimate()]
#' @param return_format A character. Alternative choices: list, SingleCellExperiment,
#' Seurat, h5ad. If you select `h5ad`, you will get a path where the .h5ad file saves to.
#' @param verbose Logical. Whether to return messages or not.
#' @param seed A random seed.
#' @importFrom splatter zinbSimulate
#' @export
#' @references
#' Zappia L, Phipson B, Oshlack A. Splatter: simulation of single-cell RNA sequencing data. Genome biology, 2017, 18(1): 1-15. <https://doi.org/10.1186/s13059-017-1305-0>
#'
#' Bioconductor URL: <https://bioconductor.org/packages/release/bioc/html/splatter.html>
#'
#' Github URL: <https://github.com/Oshlack/splatter>
#' @examples
#' \dontrun{
#' ref_data <- simmethods::data
#'
#' estimate_result <- simmethods::zinbwave_estimation(ref_data = ref_data,
#'                                                    other_prior = NULL,
#'                                                    verbose = TRUE,
#'                                                    seed = 111)
#'
#' ## In zinbwave, users can not set the number of cells and genes.
#' simulate_result <- simmethods::zinbwave_simulation(
#'   parameters = estimate_result[["estimate_result"]],
#'   return_format = "list",
#'   verbose = TRUE,
#'   seed = 111
#' )
#' }
#'
zinbwave_simulation <- function(parameters,
                                return_format,
                                verbose = FALSE,
                                seed
){
  ##############################################################################
  ####                               Check                                   ###
  ##############################################################################
  assertthat::assert_that(class(parameters) == "ZINBParams")
  # Get params to check
  params_check <- splatter::getParams(parameters, c("nCells",
                                                    "nGenes"))

  # Return to users
  message(paste0("nCells: ", params_check[['nCells']]))
  message(paste0("nGenes: ", params_check[['nGenes']]))
  ##############################################################################
  ####                            Simulation                                 ###
  ##############################################################################
  if(verbose){
    message("Simulating datasets using zinbwave")
  }
  # Seed
  parameters <- splatter::setParam(parameters, name = "seed", value = seed)
  # Simulation
  simulate_detection <- peakRAM::peakRAM(
    simulate_result <- splatter::zinbSimulate(parameters,
                                              verbose = verbose))
  ##############################################################################
  ####                        Format Conversion                              ###
  ##############################################################################
  simulate_result <- simutils::data_conversion(SCE_object = simulate_result,
                                               return_format = return_format)

  ##############################################################################
  ####                           Ouput                                       ###
  ##############################################################################
  simulate_output <- list(simulate_result = simulate_result,
                          simulate_detection = simulate_detection)
  return(simulate_output)
}