R/plotPlate.R

In lujunyan1118/DrugScreenExplorer_dev: A pipeline for processing drug sensitivity screen data

#' Plot the layout or measurements on each screening plate
#'
#' This function generates a heatmap or a series of heatmaps showing the plate layout, raw intensity or normalized intensity for each plate in the screen dataset.
#'
#' @param screenData a data frame containing screen data generated by \code{readScreen()} function
#' @param plotPlate a character string or a vector of character strings specifying the file name of the plates. If all plates should be included, 'all' can be used. Default value is 'all'
#' @param plotType a character string specifying the type of the plot, one of 'layout', 'zscore' and 'viability'.
#' If 'layout' is specified, the plate layout will be plotted in a heatmap according to the information in the 'wellType' column.
#' If 'zscore' is chosen, the zscore of each well on a plate will be plotted in the heatmaps.
#' If 'viability' is used, the normalized intensity or viability values on each plate will be plotted.
#' This choice is only valid when plate normalization is performed by \code{readScreen()} function or \code{normalizePlate()} function. Default is 'layout'
#' @param ifCorrected a logical value, whether to plot values after edge effect correction. The default value is FALSE, plot the original value.
#' @param limits a numeric vector indicates the lower and upper limits of the value shown in the heatmap.
#' The default values is \code{[0,2]} for \code{plotType = "viability"} and \code{[-3,3]} for \code{plotType = 'zscore'}.
#' @param pdfName a character string specifying the output pdf file name. If not specified, a list containing the ggplot objects of plate plots will be returned. Default is NULL.
#' @param ncol the number of columns in a pdf page. Default number is 2.
#' @param nrow the number of rows in a pdf page. Default number is 3.
#' @param width the width of the page, in points
#' @param height the height of the page, in points
#' @import ggplot2 dplyr
#' @export
#' @return If the argument \code{pdfName = NULL}, this function returns a list of ggplot objects and each object is a heatmap for each plate. If a file name is specified \
#' for the \code{pdfName} argument, a pdf file with the specified name and layout will be created in the working directory.
#' @examples
#' # load processed data
#' data('screenData_normalized')
#'
#' # plot the cell viability heatmap on all plates
#' plotPlate(screenData_normalized, plotPlate = 'all', plotType = 'viability')
#' # Please see the vignette for more information.

plotPlate <- function(screenData, plotPlate = "all", plotType = "layout", ifCorrected = FALSE,
                      limits = NULL, pdfName = NULL, ncol = 2, nrow = 3, width = 16, height = 16) {

  # Get a list of plates for plotting, either all plates in the drug screen
  # data or a user-specified list
  if (all(plotPlate == "all")) {
    plateList <- unique(screenData$fileName)
  } else {
    plateList <- intersect(unique(screenData$fileName), plotPlate)
  }
  if (length(plateList) == 0)
    stop("No plate found")

  # generate table with correct odering of column and rows for plotting.
  nCol <- length(unique(screenData$colID))
  nRow <- length(unique(screenData$rowID))
  rowSeq <- genRowIDs(nRow)
  colSeq <- genColIDs(nCol)

  matPlate <- screenData %>%
    dplyr::mutate(rowID = factor(rowID, levels = rev(rowSeq))) %>%
    dplyr::mutate(colID = factor(colID, levels = colSeq))

  if (plotType == "layout") {
    # only plot the layout on the plate, based on the wellType annotation
    plotList <- lapply(plateList, function(plateName) {
      p <- dplyr::filter(matPlate, fileName == plateName) %>%
        ggplot(aes(x = colID, y = rowID, fill = wellType)) + geom_tile(color = "grey80") +
        xlab("") + ylab("") + theme_void() + ggtitle(plateName) + theme(axis.text = element_text(size = 6),
                                                                        axis.ticks = element_blank(), plot.title = element_text(hjust = 0.5),
                                                                        plot.margin = margin(5, 5, 5, 5))
    })

  } else if (plotType == "viability") {
    plotList <- plotViability(matPlate, plateList, limits, ifCorrected)

  } else if (plotType == "zscore") {
    plotList <- plotZscore(matPlate, plateList, limits)

  } else if (plotType == "edgeEffect") {
    plotList <- plotEdgeEffect(matPlate, plateList, limits)

  } else stop("Not a valid option for plotType")

  if (is.null(pdfName)) {
    return(plotList)
  } else {
    makepdf(plotList, pdfName, ncol, nrow, width, height)
  }
}