# waterfall: function introduction

Zachary Skidmore

#### 2019-04-04

# 1 Overview

Small variants within the genome (single nucleotide variants/insertions/deletions) are a critical component in the basis for genetic diseases. The identification and summary of these types of variants is often a first step for the development of hypothesis regarding the role of these events in disease genesis and progression. The `waterfall` funtion is designed to effeciently summarize “small variant” (SNVs/indels) information at a cohort level. It is usefull for obtaining a broad sense of the type of variants observed in a cohort. Further `waterfall` will give a sense of the mutation burden, reccurently mutated genes, the mutually or co exclusivity between genes and the relation of variants to clinical data.

The purpose of this vignette is to display the many features of the `waterfall` function in order to give an in depth view of it’s parameters and functionality. For these examples the data frame `brcaMAf` originating from a truncated .maf file from TCGA and available within `GenVisR` will be used unless otherwise stated. Further for reproducability the seed for all examples has been set to == 426.

## 1.1 Functionality

### 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).

MAF | MGI
--- | ---
Nonsense_Mutation | nonsense
Frame_Shift_Ins | frame_shift_del
Frame_Shift_Del | frame_shift_ins
Translation_Start_Site | splice_site_del
Splice_Site | splice_site_ins
Nonstop_Mutation | splice_site
In_Frame_Ins | nonstop
In_Frame_Del | in_frame_del
Missense_Mutation | in_frame_ins
5’Flank | missense
3’Flank | splice_region_del
5’UTR | splice_region_ins
3’UTR | splice_region
RNA | 5_prime_flanking_region
Intron | 3_prime_flanking_region
IGR | 3_prime_untranslated_region
Silent | 5_prime_untranslated_region
Targeted_Region | rna
| intronic
| silent

### 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 Tips and hints

Parameters covered: `out`

### 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