R/AllGenericsPlotting.R

In yavorska/TenXAnalysisPackage: Analysis of the 10x Genomics 1.3 Million Cells Data

#-------------------------------------------------------------------------------
#' TenXSubset object data summaries
#'
#' A function that plots the data summaries with the quantities of
#' interest defined by the user. See Details for the allowed combinations.
#'
#' The basic idea of this function is to provide an each interface which allows
#' one to visualise the data in different meaningful ways in order to locate
#' inconsistencies or possible problems which may arise.
#'
#' There are multiple combinations of parameters one can use, but obviously not
#' all will work well together. As a result, the function provides the user with
#' prompts:
#' \itemize{
#'     \item if necessary parameters are left out, the function suggests
#'     suitable values for these parameters
#'     \item if the parameters chosen are not compatible, the function suggests
#'     alternative parameter values based on the ones that have been chosen
#' }
#'
#' @param object A \code{TenXSubset} object.
#' @param x A \code{character} string indicating the values to appear on the x
#' axis.
#' @param y An optional \code{character} vector indicating the values to appear
#' on the y axis.
#' @param type An optional \code{character} string representing the type of
#' figure to plot. This is one of \code{histogram}, \code{density},
#' \code{boxplot}, \code{violin}, or \code{point}. If this is left blank, the
#' algorithm will output a list of suitable choices for the user  to choose
#' based on the \code{x} and \code{y} parameters.
#' @param colorByCells An optional parameter specifying either:
#' \itemize{
#'     \item the indices of the cells to be coloured differently (end up with
#'     two distinct groups)
#'     \item \code{"library"} or \code{"mouse"} as a shortcut to colour based on
#'     existing groups
#' }
#' @param colorByGenes An optional parameter specifying the \code{numeric}
#' indices of the genes to be coloured differently.
#' @param ... Any additional parameters compatible with \pkg{ggplot2}.
#'
#' @return A \pkg{ggplot2} object.
#'
#' @export plotTenX

setGeneric("plotTenX", function(object, x, y, type,
                                colorByCells = NULL, colorByGenes = NULL, ...){
  standardGeneric("plotTenX")})

#-------------------------------------------------------------------------------
# Analyse a single gene at a time

#' Plot gene summary for TenXSubset object
#'
#' @param object A \code{TenXSubset} object.
#' @param geneName A HGNC or ENSEMBL gene identifier. Note that only those nemes
#'        included in \code{geneNames(TenXSubset)} or
#'        \code{geneENSEMBL(TenXSubset)} can be used.
#'
#' @return Visualise how common the gene is compared to the others in the data
#' set. The returns a table of 4 values giving the:
#' \itemize{
#'     \item name of the gene
#'     \item number of transcripts of this gene in this dataset
#'     \item number of cells that express this gene in this dataset
#'     \item number of transcripts per cell expressing this gene
#' }
#'
#' @export
#'

setGeneric("plotTenXGene", function(object, geneName, ...){
  standardGeneric("plotTenXGene")})

#-------------------------------------------------------------------------------

#' Compare gene expression profiles for two genes
#'
#' @param object A \code{TenXSubset} object.
#' @param geneName1 A HGNC or ENSEMBL gene identifier.
#' @param geneName2 A HGNC or ENSEMBL gene identifier.
#'
#' @export
#'

setGeneric("plotTenXGenePair", function(object, geneName1, geneName2){
  standardGeneric("plotTenXGenePair")})

#-------------------------------------------------------------------------------

#' Plot GO summary for TenXSubset object
#'
#' @param object A \code{TenXSubset} object.
#' @param goId A valid GO id.
#' @param plotAll Whether the rankings should be plotted or not (if \code{TRUE}
#'        then this is the only output).
#'
#' @export
#'

setGeneric("plotTenXGO", function(object, goId, plotAll, ...){
  standardGeneric("plotTenXGO")})

#-------------------------------------------------------------------------------

#' Plot GO summary for specified gene set
#'
#' Given a set of gene indices, determine the top 10 functions associated with
#' these genes and plot them as a bar chart.
#'
#' @param object A \code{TenXSubset} object.
#' @param geneName A vector of HGNC or ENSEMBL gene names.
#'
#' @export
#'

setGeneric("plotTenXGeneGO", function(object, geneName){
  standardGeneric("plotTenXGeneGO")})

#-------------------------------------------------------------------------------

#' Plot how gene expression changes based on mouse
#'
#' Given a data.frame generated by \code{generateSummaryExpr}, illustrate how
#' gene expression changes across mice for a specific gene.
#'
#' @param summaryExpr A data.frame giving the cell index, library, mouse, and
#'        transcript counts associated with each of a group of cells.
#' @param geneName A HGNC or ENSEMBL gene name that corresponds to one of the
#'        column names of \code{summaryExpr}.
#' @param plot One of "all", "point", "hist", or "boxplot".
#'
#' @export

setGeneric("plotTenXMouseExpr", function(summaryExpr, geneName, plot){
  standardGeneric("plotTenXMouseExpr")})

#-------------------------------------------------------------------------------

#' Plot how gene expression changes based on library
#'
#' @param object A \code{TenXSubset} object.
#' @param geneName A vector of HGNC or ENSEMBL gene names.
#'
#' @export

setGeneric("plotTenXGroupExpr", function(object, geneName){
  standardGeneric("plotTenXGroupExpr")})

#-------------------------------------------------------------------------------

#' Compare gene expression across multiple genes
#'
#' @param object A \code{TenXSubset} object.
#' @param geneName A vector of HGNC or ENSEMBL gene names.
#'
#' @export

setGeneric("plotTenXGeneCor", function(object, geneName){
  standardGeneric("plotTenXGeneCor")})

#-------------------------------------------------------------------------------

#' Check how the mean of each gene changes according to library in the filtered
#' data set
#'
#' @param geneName A character string giving the name of the gene.
#'
#' @export

setGeneric("plotTenXMeans", function(geneName){
  standardGeneric("plotTenXMeans")})

#-------------------------------------------------------------------------------

#' Check how the variance of each gene changes according to library in the
#' filtered data set
#'
#' @param geneName A character string giving the name of the gene.
#'
#' @export

setGeneric("plotTenXVars", function(geneName){
  standardGeneric("plotTenXVars")})

#-------------------------------------------------------------------------------

#' Check how the coefficient of variation of each gene changes according to
#' library in the filtered data set
#'
#' @param geneName A character string giving the name of the gene.
#'
#' @export

setGeneric("plotTenXCVs", function(geneName){
  standardGeneric("plotTenXCVs")})