1.1.1 Loading primary input

Parameters covered: fileType, variant_class_order

For basic use a user will only need to read a file of the proper type into R as a data frame and then supply this data frame to the waterfall function as the argument given to x. By default the data frame supplied is expected to correspond to a file in .maf (version 2.4) format (see below for additional supported formats). This data frame should have at a minimum the following column names “Tumor_Sample_Barcode”, “Hugo_Symbol”, “Variant_Classification”, and contain rows corresponding to mutation events. Further while any value is permissible for the “Tumor_Sample_Barcode” and “Hugo_Symbol” columns which correspond to a sample name and gene name respectively, specific values are expected for the “Variant_Classification” column (see table below). This is because waterfall is only capable of displaying a single variant type in the main plot for a cell (i.e. gene/sample). To achieve this waterfall will choose to plot the most deleterious variant based on a hierarchy predefined for a .maf file. This heiararchy follows the order from top to bottom of the legend output with the plot.

# Load the GenVisR package
library("GenVisR")
set.seed(426)

# Plot with the MAF file type specified (default) The mainRecurCutoff
# parameter is described in the next section
waterfall(brcaMAF, fileType = "MAF", mainRecurCutoff = 0.05)

The user is capable of supplying additional file types to waterfall, if desireable. This is achievable via the fileType parameter. For example if it were to desireable to plot an annotation file from the Genome Modeling System the user would simply change the fileType to equal “MGI” and supply the corresponding file as the argument x. As with the .maf file a predefined heirarchy has been defined to plot the most deleterious mutations in cases where there are multiple mutations in the same gene/sample (see table below).

# read in a file from the genome modeling system
file <- read.delim("file.anno.tsv")

# Plot the variant information via waterfall
waterfall(file, fileType="MGI")

waterfall is also capable of plotting small variant information via a non-standard or unsupported file type. To do this the user should set the fileType parameter to “Custom”, and supply to as an argument to x a data frame with the columns “sample”, “gene”, “variant_class” corresponding to the “sample”, “gene”, and “variant type” respectively. Further the user is required to define which variants are considered most deleterious via the parameter variant_class_order for cases where there are multiple mutations in the same gene/sample. This should take the form of a character vector with values corresponding to the unique values in the column “variant_class” in order of most to least deleterious. As with the previous two examples the most deleterious mutation will be plotted. The “variant_class_order” parameter can be used to change the mutational heirarchy in the previous file types as well.

# make sure seed is set to 426 to reproduce!
set.seed(426)

# Create a data frame of random elements to plot
inputData <- data.frame(sample = sample(letters[1:5], 20, replace = TRUE), gene = sample(letters[1:5], 
    20, replace = TRUE), variant_class = sample(c("x", "y", "z"), 20, replace = TRUE))

# choose the most deleterious to plot with y being defined as the most
# deleterious
most_deleterious <- c("y", "z", "x")

# plot the data with waterfall using the 'Custom' parameter
waterfall(inputData, fileType = "Custom", variant_class_order = most_deleterious, 
    mainXlabel = TRUE)

# change the most deleterious order
waterfall(inputData, fileType = "Custom", variant_class_order = rev(most_deleterious), 
    mainXlabel = TRUE)

Figure 1: In cell e/e (second row/first column) two variants are present ‘z’ and ‘x’
In the first plot variant ‘z’ is considered more deleterious (top panel), In the second plot variant ‘x’ is considered more deleterious (bottom panel).

1.1.2 Filtering options

Parameters covered: mainRecurCutoff, plotGenes, plotSamples, maxGenes, rmvSilent

Often it is the case that the input supplied to the waterfall function will contain thousands of genes and hundreds of samples. While waterfall can handle such scenarios the graphics device waterfall would neeed to output to would have to be enlarged to such a degree that the visualization may become unwieldy (see tips). To alleviate such issues waterfall provides a suite of filtering parameters to visualize the data of the most interest to the user. The first of these mainRecurCutoff accepts a numeric value between 0 and 1, and will only plot genes with mutations in x proportion of samples.

# Plot the genes with mutatations in >= 20% of samples
waterfall(brcaMAF, fileType = "MAF", mainRecurCutoff = 0.2)

Alternatively if there are specific genes of interest those can be specified directly via the plotGenes parameter. Input to plotGenes should be a character vector of a list of genes that are desireable to be shown and is case sensitive. If a gene is supplied to this parameter and it is not within the data frame supplied to waterfall that specific gene will be ignored.

# Define specific genes to plot
genes_to_plot <- c("ERBB2", "MAPK1", "CDKN1B", "PIK3CA")

# Plot the genes defined above
waterfall(brcaMAF, plotGenes = genes_to_plot)

Occassionaly it may be desireable to plot only specific samples. This can be achieved via the parameter plotSamples and works in much the same way as the plotGenes parameter taking a character vector of samples. An important difference between the two is supplying a sample to plotSamples not within the data frame given to waterfall will add the sample to the data frame instead of ignoring it.

# Define specific genes to plot
samples_to_plot <- c("TCGA-A1-A0SO-01A-22D-A099-09", "TCGA-A2-A0EU-01A-22W-A071-09", 
    "TCGA-A2-A0ER-01A-21W-A050-09", "TCGA-A1-A0SI-01A-11D-A142-09", "TCGA-A2-A0D0-01A-11W-A019-09")

# Plot the samples defined above
waterfall(brcaMAF, plotSamples = samples_to_plot, mainRecurCutoff = 0.25)

Two additinonal filtering options exist that have not yet been mentioned. the maxGenes parameter will only plot the top x genes and takes an integer value. This is usefull for example if when using the mainRecurCutoff parameter a vector of genes have values at x cutoff and all of them are not desired. the rmvSilent parameter will remove all silent mutations from the data.

# plotting all genes with a mutation recurrence above 5%, limit to plot only
# the top 25 and remove silent mutations
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 25, rmvSilent = TRUE)

It is important to note that none of these subsets will affect the mutation burden calculation or plot (i.e. nothing is filtered until after that calculation is performed.)

1.1.3 The Mutation Burden

Parameters covered: mutBurden, plotMutBurden, coverageSpace

As can be seen in the prior examples waterfall we calculate an estimate of the mutation burden seen within the data given. This calculation follows the formula \(mutations\ in\ sample/coverage\ space * 1,000,000\). This is one of the first things waterfall does and is unaffected by any filtering options employed. In this calcluation the coverage space used is critically important to an accurate calculation. By default the theoretical coverage space of the exome reagent “SeqCap EZ Human Exome Library v2.0” is used, however the coverage space should be adjusted to fit you’re data! This can be achieved via the coverageSpace parameter and expects an intger specifying the number of base pairs from which a mutation could have been expected to be called.

# Alter the coverage space to whole genome space
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 25, coverageSpace = 3.2e+09)

Figure 2: Altering the coverage space dramatically affects the mutation burden calculation

Altering the coverageSpace will only give an aproximation of the mutation burden as it is infeasible to expect all samples to have identical coverage space. To remedy this the option exists to supply a data frame to the parameter mutBurden for user defined mutation burdens corresponding to each sample. Input to this argument should be a data frame with columns “sample” and “mut_burden”. If supplied values in this data frame will be plotted instead of aproximated as mentioned above. If used, the data frame supplied to mutBurden should have a row for each unique sample in the data frame supplied to parameter x.

# Create a data frame specifying the mutation burden for each sample
tumor_sample <- unique(brcaMAF$Tumor_Sample_Barcode)
mutation_burden <- sample(1:10, length(tumor_sample), replace = TRUE)
mutation_rate <- data.frame(sample = tumor_sample, mut_burden = mutation_burden)

# Alter the coverage space to whole genome space
waterfall(brcaMAF, mutBurden = mutation_rate, mainRecurCutoff = 0.05, maxGenes = 25)

If plotting the mutation burden is not of interest the user has the option to turn this behavior off via the parameter plotMutBurden which accepts a boolean value.

# Turn off plotting of the mutation burden subplot
waterfall(brcaMAF, plotMutBurden = FALSE, mainRecurCutoff = 0.05, maxGenes = 25)

1.1.4 Adding Clinical Data

Parameters covered: clinData, clinLegCol, clinVarOrder, clinVarCol

It is often informative to view patterns within the waterfall plot in the context of clinical features. This can be achieved by supplying a data frame to the clinData parameter. Input to this parameter should contain the columns “sample”, “variable”, “value” with rows representing clinical data. The data supplied should be in “Long format” with each id variable (i.e. sample) having a corresponding variable and a value for that variable. It is reccommended to use the function melt from the package reshape2 to coerce data into this format.

# Create clinical data
subtype <- c("lumA", "lumB", "her2", "basal", "normal")
subtype <- sample(subtype, 50, replace = TRUE)
age <- c("20-30", "31-50", "51-60", "61+")
age <- sample(age, 50, replace = TRUE)
sample <- as.character(unique(brcaMAF$Tumor_Sample_Barcode))
clinical <- as.data.frame(cbind(sample, subtype, age))

# Melt the clinical data into 'long' format.
library(reshape2)
clinical <- melt(clinical, id.vars = c("sample"))

# create the waterfall plot with the corresponding clinical data
waterfall(brcaMAF, clinDat = clinical, mainRecurCutoff = 0.05, maxGenes = 25)

A number of options exist to alter the aesthetic properties of the clinical data subplot if the defaults produce an undesireable result. Briefly these parameters are clinLegCol which will alter the number of columns in the clinical legend, clinVarOrder which will alter the order of the clinical variables in the clinical legend subplot, and clinVarCol which allows a user to alter the mapping of colours to variables.

# Create clinical data
subtype <- c("lumA", "lumB", "her2", "basal", "normal")
subtype <- sample(subtype, 50, replace = TRUE)
age <- c("20-30", "31-50", "51-60", "61+")
age <- sample(age, 50, replace = TRUE)
sample <- as.character(unique(brcaMAF$Tumor_Sample_Barcode))
clinical <- as.data.frame(cbind(sample, subtype, age))

# Melt the clinical data into 'long' format.
library(reshape2)
clinical <- melt(clinical, id.vars = c("sample"))

# create the waterfall plot altering various aesthetics in the clinical data
waterfall(brcaMAF, clinDat = clinical, clinVarCol = c(lumA = "blue4", lumB = "deepskyblue", 
    her2 = "hotpink2", basal = "firebrick2", normal = "green4", `20-30` = "#ddd1e7", 
    `31-50` = "#bba3d0", `51-60` = "#9975b9", `61+` = "#7647a2"), mainRecurCutoff = 0.05, 
    maxGenes = 25, clinLegCol = 2, clinVarOrder = c("lumA", "lumB", "her2", "basal", 
        "normal", "20-30", "31-50", "51-60", "61+"))

1.1.5 Adding Proportion sub-plots

Parameters covered: plot_proportions, proportions_type, proportions_layer

In addition to the clinical subplot users have the ability to display the proportion of mutations observed in the cohort. This is achieved by setting the argument to plot_proportions to TRUE and will by default calculate and display the proportion of Mutation Types before any subsetting occurs.

# plot the proportion of mutation types oserved
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, plot_proportions = TRUE)

It is also possible to calculate and display the transition/transversion rate observed by setting the proportion_type to the string “TvTi” while the plot_propotions switch is set to TRUE. This will make a call to the primary GenVisR function TvTi and display the results as a subplot.

# plot the proportion of mutation types oserved
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, plot_proportions = TRUE, 
    proportions_type = "TvTi")

1.1.6 Adding cell labels

Parameters covered: mainLabelCol, mainLabelSize, mainLabelAngle

waterfall allows the addition of cell labels to the waterfall plot via the parameter mainLabelCol. This will look for a column in the argument supplied to the parameter x and label the plotted cell with the value in that column.

# Use the chromosome column in brcaMAF to label cells
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainLabelCol = "Chromosome")

Care should be taken when using the mainLabelCol parameter as the text plotted is always centered on the corresponding cell but not automatically sized. The parameters mainLabelSize and mainLabelAngle can help with text spilling into other cells by re-sizing and rotating text respectively.

# Use the amino_acid change column in brcaMAF to label cells
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainLabelCol = "amino_acid_change_WU", 
    mainLabelAngle = 90, mainLabelSize = 3)

1.1.7 Altering Plot Aesthetics

Parameters covered: mainGrid, mainXlabel, main_geneLabSize, mainDropMut, mainPalette, mainLayer, mutBurdenLayer, clinLayer, proportions_layer, section_heights

In order to give the user maximum control with minimal effort a variety of parameters exist to alter the visual aesthetics of the waterfall plot. The mainGrid parameter will overlay a grid ontop of the main plot to visually line up cells. The mainXlabel parameter will label the x axis with samples. The main_geneLabSize parameter will alter the text sizes of the gene labels. mainDropMut will remove from the main legend those variables which are not present in the main plot. Finally the mainPalette allows for the mapping of a custom colour pallete to mutation types. These parameters are illustrated below.

# Label the x-axis
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainXlabel = TRUE)

# Drop unused mutation types from the legend
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainDropMut = TRUE)

# Increase the gene label size
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainDropMut = TRUE, 
    main_geneLabSize = 14)

# make a custom colour pallete
custom_pallete <- c("#A069C7", "#9CD05B", "#C46839", "#97BDBD", "#513C4D", "#6B7644", 
    "#C6587F")

# provide a custom colour pallete
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainDropMut = TRUE, 
    mainPalette = custom_pallete)

It may be desireable to emphasize different aspects of the waterfall plot for exploratory or publication purposes. A use parameter for this is section_heights which will alter the heights of any plot vertically aligned to the main plot. Input to this parameter is a numeric vector the same length as the number of plots aligned. As an example a waterfall plot having a proportion, main, and mutation burden plot would expect a vector of length 3.

# Increase the subplot size to be equal with the main plot
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainDropMut = TRUE, 
    section_heights = c(1, 1))

For users with a familiarity with ggplot2 the option exists to add a single layer to all subplots in waterfall giving control over virtually all aesthetic aspects of the plot. The parameters for this control are mainLayer, mutBurdenLayer, clinLayer, proportions_layer and will add a ggplot2 layer to the main, mutation burden and clinical plot respectively. This parameter is recommended only for advance use as it may have unintential consequences (see ggplot2 docs for help).

# load ggplot2
library(ggplot2)

# suppress the y axis labels in the mutation burden plot
mut_burden_layer <- theme(axis.ticks.y = element_blank(), axis.text.y = element_blank(), 
    axis.title.y = element_blank())

# change the ggplot theme back to default in the main plot
main_layer <- theme_grey()

# Run waterfall with the new layer
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, mainDropMut = TRUE, 
    mainLayer = main_layer, mutBurdenLayer = mut_burden_layer)

Figure 3: As can be seen we have changed the theme via ggplot2 however this has overwritten the previously defined theme which had suppressed the x-axis labels and removed the rotation

1.1.8 Rearranging cells

Parameters covered: sampOrder, geneOrder

In the interest of giving the user full control over the plot the waterfall gives the option of rearranging the axis to suit the display purpose of the graphic. As an example by default waterfall arrages samples via a hierarchical sort in order to effeciently display mutually exclusive or co-occuring events, however it may be desireable to arrange samples via a clinical variable instead. This is achieved via the sampOrder parameter.

# Create clinical data
subtype <- c("lumA", "lumB", "her2", "basal", "normal")
subtype <- sample(subtype, 50, replace = TRUE)
age <- c("20-30", "31-50", "51-60", "61+")
age <- sample(age, 50, replace = TRUE)
sample <- as.character(unique(brcaMAF$Tumor_Sample_Barcode))
clinical <- as.data.frame(cbind(sample, subtype, age))

# Melt the clinical data into 'long' format.
library(reshape2)
clinical <- melt(clinical, id.vars = c("sample"))

# Obtain a sample order corresponding to the clinical data
new_samp_order <- as.character(unique(clinical[order(clinical$variable, clinical$value), 
    ]$sample))

# create the waterfall plot with the corresponding clinical data
waterfall(brcaMAF, clinDat = clinical, mainRecurCutoff = 0.05, maxGenes = 25, 
    sampOrder = new_samp_order)

Similarly, in order to display the mutual exclusivity or co-occurence between two genes of interest it may be desireable for these genes to be plotted together. Genes can be re-arraged via the geneOrder parameter.

# Define a custom gene order
new_gene_order <- c("MUC16", "MUC17", "MUC12", "RYR2", "PIK3CA", "TP53", "USH2A", 
    "MLL3", "TTN", "LRP2")

# Increase the gene label size
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10, geneOrder = new_gene_order)

1.2.1 Types of output

In the interest of visibility and debugging purposes GenVisR gives the option of outputing a grob or the data that would be input to the internal plotting function instead of drawing the plot. This is achievable via the out parameter.

1.2.2 Saving plots

It is recommended to open a new graphics device, draw the plots GenVisR produces, and close the graphics In order to save a GenVisR plot.

# Save a GenVisR plot
pdf(file="myplot.pdf", height=10, width=15)
waterfall(brcaMAF, mainRecurCutoff=.05, maxGenes=10)
dev.off()

1.2.3 Grob collisions

Due to the way plots are constructed users are encouraged to allow for adequate room for the plot to render, if something doesn’t look right it may be due to individual grobs within the plot colliding. The plot can always be re-sized after it has been drawn and saved to a file!

# A GenVisR plot on a small graphics device
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10)

Figure 4: A small graphics device may cause grob collisions, here the device size is 5 by 5

# A GenVisR plot on a small graphics device
waterfall(brcaMAF, mainRecurCutoff = 0.05, maxGenes = 10)

Figure 5: Increasing the size of the graphic device will alleviate this issue, here the device size is 10 by 7