R/plotting.R

In angelesarzalluz/scfilters: A correlation-based method for quality filtering of single-cell RNAseq data

#' Plotting the results.
#'
#' This set of functions generate the summary plots that result from the correlation-based
#' analysis of your single-cell sequencing data.
#' 
#' Each plotting function is designed to plot the output data of another function in this
#' package. Associations are as follows:
#' 
#' \itemize{
#' 
#'      \item \code{plot_scatter} plots the output of the \code{\link{calculate_cvs}} 
#'      function, more specifically, only the \code{CV} and \code{mean} columns. However, 
#'      the plotting function selects these automatically, and the entire data frame 
#'      should be provided by the user when calling it. 
#'      
#'      If running \code{\link{all_calls}}, this can be done by subsetting the results 
#'      using \code{$cv}.
#'      
#'      \item \code{plot_bins} plots the output of the \code{\link{bin_scdata}} function.
#'      Similarly, the entire data frame should be provided, as the function will select 
#'      the \code{CV}, \code{mean} and \code{bin} columns automatically from it.
#'      
#'      Subset the appropriate results from \code{all_calls} using \code{$binned}.
#'      
#'       \item \code{plot_cor_dens} plots the output of the \code{\link{compute_density}} 
#'       function.It should be noted that this function outputs the density computations 
#'       for only one window, and therefore, the plotting function must be called again 
#'       after each computation. 
#'       
#'       Subset the appropriate results from \code{all_calls} using 
#'       \code{$densities[[window number]]}.
#'       
#'       \item \code{plot_histogram} plots the output of the \code{\link{compute_histogram}} 
#'       function. Subset \code{all_calls} results using \code{$histogram}.
#' }
#' 
#' For the \code{...} argument:
#' 
#' \itemize{
#' 
#'      \item \code{plot_scatter} and \code{plot_bins} pass on the arguments to the 
#'      \code{geom_point} function in \code{ggplot2}.
#'      
#'       \item \code{plot_cor_dens} passes arguments on to the \code{geom_line} function in
#'       \code{ggplot2}.
#'       
#'       \item \code{plot_histogram} passes arguments on to \code{geom_bar} function in 
#'       \code{ggplot2}.
#' }
#' 
#' For suitable aesthetics, please see documentation of these functions.
#' 
#' \strong{Important note:} calling the plotting functions doesn't enable visualization of
#' the plot. The plot list that is generated should be saved and then visualized by calling the
#' \code{plot} function on it.
#'
#' @param data A data frame containing the suitably formatted data for the specified plot.
#' 
#' @param save A logical. When \code{TRUE}, plots will be saved to the indicated path.
#' 
#' @param display A logical. When \code{TRUE}, plots will be displayed.
#' 
#' @param path A string indicating a path to save the plot to. 
#' 
#' @param filename A string indicating the name of the plot file.
#' 
#' @param format A string indicating the file format of the plot.
#' 
#' @param density Logical. Specifies whether the scatter plot will incorporate scatter
#' density lines.
#' 
#' @param shape, size, alpha Numbers specifying aesthetics of the scatter plots, passed on
#' to the \code{geom_point} function in the \code{ggplot2} package. Shape is an integer, 
#' size and alpha are doubles.
#' 
#' @param ... Other aesthetic specifications to be passed on to the \code{geom_point}, 
#' \code{geom_line} or \code{geom_bar} functions.
#' 
#' @param window An integer. Indicates the window for which the correlation density plot
#' is being generated by \code{plot_cor_dens}.
#' 
#' @param ribbon_col, ribbon_alpha Aesthetics for the error space in the correlation density
#' plot. Color indicated by a string, and alpha indicated by a double.
#' 
#' @param curve_cols A string vector. Specifies colours of the negative control and data 
#' curves in the correlation density plots, in that order.
#' 
#' @param title A string. Contains the title to be set on the histogram plot, normally an
#' informative title. Recommendation is to specify top window method of selection and size, 
#' number and size of bins, number of cells in the original dataset.
#' 
#' @param ylim A double. Sets the limit of the y axis.
#' 
#' @return A list, containing the information of the generated plot.

plot_scatter <- function(data, save = FALSE, display = TRUE, path = ".", filename = "scatter_plot", 
                         format = "png", density = FALSE, shape = 16, size = 0.5, alpha = 0.5, ...){
    
    # plot CV and mean columns from the CV object
    pl <- ggplot(data, aes(x = CV, y = mean + 1)) +
        # select point shape and specify aesthetics
        geom_point(shape = shape, size = size,
                   alpha = alpha, ...) +
        # set log10 scale in the y axis
        scale_y_log10() +
        # label plot
        ylab("Mean expression + 1") + xlab("Coefficient of variation")
    
    # add scatter density to plot
    if (density == TRUE){
        pl <- pl + geom_density_2d()
    }

    # save or display the plot
    if (save == TRUE){
        
        # save to path
        ggsave(paste0(filename, ".", format), path = path, device = format)
    } 
    if (display == TRUE){
        
        # display the plot
        message("See scatter plot displayed.")
        pl
    }
}

#' @rdname plot_scatter

plot_bins <- function(data, save = FALSE, display = TRUE, path = ".", filename = "bins_plot",
                      format = "png", shape = 16, alpha = 0.5, size = 0.5, ...){
    
    # plot data assigning colors by window
    pl <- ggplot(data, aes(x = CV, y = mean + 1, colour = factor(data$bin))) +
        # select point shape and specify aesthetics
        geom_point(shape = shape, alpha = alpha, size = size, ...) +
        # set log10 scale in the y axis
        scale_y_log10() +
        # label plot
        ylab("Mean expression + 1") + xlab("Coefficient of variation")
    
    # save or display the plot
    if (save == TRUE){
        
        # save to path
        ggsave(paste0(filename, ".", format), path = path, device = format)
        
    } 
    if (display == TRUE){
        
        # display the plot
        message("See bins plot displayed.")
        pl   
    }
}

#' @rdname plot_scatter

plot_cor_dens <- function(data, save = FALSE, display = TRUE, path = ".", filename = NULL, 
                          format = "png", window, ribbon_col = "grey", ribbon_alpha = 0.2, 
                          ..., curve_cols = c("black", "red")){
    
    # make label for the window that is being plotted
    window_label <- paste("Window", window)
    
    # create empty plot
    pl <- ggplot() +
        # plot error cruves as a ribbon
        geom_ribbon(aes(x = data$control_x, ymin = data$min_control_y,
                        ymax = data$max_control_y), color = ribbon_col, alpha = ribbon_alpha) +
        # plot random negative control curve
        geom_line(data = data, aes(x = control_x, y = control_y, color = "Control"), ...) +
        # plot data correlation density curve
        geom_line(data = data, aes(x = data_x, y = data_y, color = window_label), ...) +
        # label plot
        ylab("Density") + xlab("Absolute value of correlation") +
        # set colours and labels for the curves
        theme_bw() + scale_color_manual(values = curve_cols,
                                        labels = c("Control", window_label))
    
    # save or display the plot
    if (save == TRUE){
        
        if (is.null(filename)){
            
            # if filename is null, use window label
            ggsave(paste0(window_label, ".", format), path = path, device = format)
            
        } else {
            
            # if it is provided, use name
            ggsave(paste0(filename, ".", format), path = path, device = format)
        }
    } 
    if (display == TRUE){
        
        # display the plot
        message(paste("See density plot for", window_label, "displayed.", sep = " "))
        pl   
    }
}

#' @rdname plot_scatter

plot_histogram <- function(data, save = FALSE, display = TRUE, path = ".", filename = "histogram",
                           format = "png", title, ylim = 1, ...){
    
    # create plot with histogram values provided and set window numbers in the x axis
    pl <- ggplot(data, aes(x = factor(as.numeric(rownames(data))),
                                      y = hist_value, fill = "")) +
        geom_bar(position = position_dodge(), stat="identity", ...) + 
        # label plot
        ylab("Proportion of correlated genes") + xlab("Window number") +
        # set title and y axis limit
        ggtitle(title) + ylim(0, ylim) +
        # add error bars
        geom_errorbar(aes(ymax = error_up, ymin = error_down), width = 0.2)
    
    if (save == TRUE){
        
        # save to path
        ggsave(paste0(filename, ".", format), path = path, device = format)
        
    } 
    if (display == TRUE){
        
        # display the plot
        message("See histogram displayed.")
        pl   
    }
}