# G3viz: an R package to interactively visualize genetic mutation data using a lollipop-diagram

#### Xin Guo <g3viz.group at gmail.com>

#### 2019-04-06

# 1 Introduction

Intuitively and effectively visualizing genetic mutation data can help researchers to better understand genomic data and validate findings. `G3viz` is an R package which provides an easy-to-use lollipop-diagram tool. It enables users to interactively visualize detailed translational effect of genetic mutations in RStudio or a web browser, without having to know any HTML5/JavaScript technologies.

The features of `g3viz` include

- Interactive (zoom & pan, tooltip, brush selection tool, and interactive legend)
- Highlight and label positional mutations
- 8 ready-to-use chart themes
- Highly customizable with over 50 chart options and over 35 color schemes
- Save charts in PNG or high-quality SVG format
- Built-in function to retrieve protein domain information and resolve gene isoforms
- Built-in function to map genetic mutation type (a.k.a, variant classification) to mutation class

↥ back to top

# 2 Install `g3viz`

Install from R repository

    # install package
    install.packages("g3viz", repos = "http://cran.us.r-project.org")

or install development version from github

    # Check if "devtools" installed
    if("devtools" %in% rownames(installed.packages()) == FALSE){
      install.packages("devtools")
    }

    # install from github
    devtools::install_github("g3viz/g3viz")

↥ back to top

# 3 Quick Start

## 3.1 Example 1: Visualize genetic mutation data from `MAF` file

Mutation Annotation Format (MAF) is a commonly-used tab-delimited text file for storing aggregated mutation information. It could be generated from VCF file using tools like vcf2maf. Translational effect of variant alleles in `MAF` files are usually in the column named `Variant_Classification` or `Mutation_Type` (i.e., `Frame_Shift_Del`, `Split_Site`). In this example, the somatic mutation data of the TCGA-BRCA study was originally downloaded from the GDC Data Portal.

    # System file
    maf.file <- system.file("extdata", "TCGA.BRCA.varscan.somatic.maf.gz", package = "g3viz")

    # ============================================
    # Read in MAF file
    #   In addition to read data in, g3viz::readMAF function does
    #     1. parse "Mutation_Class" information from the "Variant_Classification"
    #        column (also named "Mutation_Type" in some files)
    #     2. parse "AA_position" (amino-acid position) from the "HGVSp_Short" column
    #        (also named "amino_acid_change" in some files) (e.g., p.Q136P)
    # ============================================
    mutation.dat <- readMAF(maf.file)

    # ============================================
    # Chart 1
    # "default" chart theme
    # ============================================
    chart.options <- g3Lollipop.theme(theme.name = "default",
                                      title.text = "PIK3CA gene (default theme)")

    g3Lollipop(mutation.dat,
               gene.symbol = "PIK3CA",
               plot.options = chart.options,
               output.filename = "default_theme")
    #> Factor is set to Mutation_Class
    #> legend title is set to Mutation_Class

↥ back to top

## 3.2 Example 2: visualize genetic mutation data from `CSV` or `TSV` file

In this example, we read genetic mutation data from `CSV` or `TSV` files, and visualize it using some customized chart options. Note this is equivalent to dark chart theme.

    # load data
    mutation.csv <- system.file("extdata", "ccle.csv", package = "g3viz")

    # ============================================
    # read in data
    #   "gene.symbol.col"    : column of gene symbol
    #   "variant.class.col"  : column of variant class
    #   "protein.change.col" : colum of protein change column
    # ============================================
    mutation.dat <- readMAF(mutation.csv,
                            gene.symbol.col = "Hugo_Symbol",
                            variant.class.col = "Variant_Classification",
                            protein.change.col = "amino_acid_change",
                            sep = ",")  # column-separator of csv file

    # set up chart options
    plot.options <- g3Lollipop.options(
      # Chart settings
      chart.width = 600,
      chart.type = "pie",
      chart.margin = list(left = 30, right = 20, top = 20, bottom = 30),
      chart.background = "#d3d3d3",
      transition.time = 300,
      # Lollipop track settings
      lollipop.track.height = 200,
      lollipop.track.background = "#d3d3d3",
      lollipop.pop.min.size = 1,
      lollipop.pop.max.size = 8,
      lollipop.pop.info.limit = 5.5,
      lollipop.pop.info.dy = "0.24em",
      lollipop.pop.info.color = "white",
      lollipop.line.color = "#a9A9A9",
      lollipop.line.width = 3,
      lollipop.circle.color = "#ffdead",
      lollipop.circle.width = 0.4,
      lollipop.label.ratio = 2,
      lollipop.label.min.font.size = 12,
      lollipop.color.scheme = "dark2",
      highlight.text.angle = 60,
      # Domain annotation track settings
      anno.height = 16,
      anno.margin = list(top = 0, bottom = 0),
      anno.background = "#d3d3d3",
      anno.bar.fill = "#a9a9a9",
      anno.bar.margin = list(top = 4, bottom = 4),
      domain.color.scheme = "pie5",
      domain.margin = list(top = 2, bottom = 2),
      domain.text.color = "white",
      domain.text.font = "italic 8px Serif",
      # Y-axis label
      y.axis.label = "# of TP53 gene mutations",
      axis.label.color = "#303030",
      axis.label.alignment = "end",
      axis.label.font = "italic 12px Serif",
      axis.label.dy = "-1.5em",
      y.axis.line.color = "#303030",
      y.axis.line.width = 0.5,
      y.axis.line.style = "line",
      y.max.range.ratio = 1.1,
      # Chart title settings
      title.color = "#303030",
      title.text = "TP53 gene (customized chart options)",
      title.font = "bold 12px monospace",
      title.alignment = "start",
      # Chart legend settings
      legend = TRUE,
      legend.margin = list(left=20, right = 0, top = 10, bottom = 5),
      legend.interactive = TRUE,
      legend.title = "Variant classification",
      # Brush selection tool
      brush = TRUE,
      brush.selection.background = "#F8F8FF",
      brush.selection.opacity = 0.3,
      brush.border.color = "#a9a9a9",
      brush.border.width = 1,
      brush.handler.color = "#303030",
      # tooltip and zoom
      tooltip = TRUE,
      zoom = TRUE
    )

    g3Lollipop(mutation.dat,
               gene.symbol = "TP53",
               protein.change.col = "amino_acid_change",
               btn.style = "blue", # blue-style chart download buttons
               plot.options = plot.options,
               output.filename = "customized_plot")
    #> Factor is set to Mutation_Class

↥ back to top

## 3.3 Example 3: visualize genetic mutation data from `cBioPortal`

cBioPortal provides download for many cancer genomics data sets. `g3viz` has a convenient way to retrieve data directly from this portal.

In this example, we first retrieve genetic mutation data of `TP53` gene for the msk_impact_2017 study, and then visualize the data using the built-in `cbioportal` theme, to miminc cBioPortal’s mutation_mapper.

    # Retrieve mutation data of "msk_impact_2017" from cBioPortal
    mutation.dat <- getMutationsFromCbioportal("msk_impact_2017", "TP53")
    #> Found study msk_impact_2017
    #> Found mutation data set msk_impact_2017_mutations
    #> 10945 cases in this study

    # "cbioportal" chart theme
    plot.options <- g3Lollipop.theme(theme.name = "cbioportal",
                                     title.text = "TP53 gene (cbioportal theme)",
                                     y.axis.label = "# of TP53 Mutations")

    g3Lollipop(mutation.dat,
               gene.symbol = "TP53",
               btn.style = "gray", # gray-style chart download buttons
               plot.options = plot.options,
               output.filename = "cbioportal_theme")
    #> Factor is set to Mutation_Class
    #> legend title is set to Mutation_Class

#### 3.3.0.1 Note:

- Internet access is required to download data from cBioPortal. This may take more than 10 seconds, or sometimes it may fail.
- To check what studies are available on cBioPortal

    # Connect to CGDS (cancer Genomics Data Server)
    cgds <- cgdsr::CGDS("http://www.cbioportal.org/")

    # Test if connection is OK
    cgdsr::test(cgds)

    # To list all studies
    all.studies <- cgdsr::getCancerStudies(cgds)

    # Pick up a cancer study with mutation data
    mutation.dat <- g3viz::getMutationsFromCbioportal("all_stjude_2016", "TP53")

↥ back to top

# 4 Usage

## 4.1 Read data

In `g3viz`, annotated mutation data can be loaded in three ways

1. from MAF file, as in Example 1.

2. from `CSV` or `TSV` files, as in Example 2.

3. from cBioPortal (internet access required), as in Example 3.

↥ back to top

## 4.2 Map mutation type to mutation class

In addtion to reading mutation data, `readMAF` or `getMutationFromCbioportal` functions also map mutation type to mutation class and generate a `Mutation_Class` column by default. Mutation type is usually in the column of `Variant_Classification` or `Mutation_Type`. The default mapping table is,

Mutation_Type | Mutation_Class | Short_Name
--- | --- | ---
Inframe
In_Frame_Del | Inframe | IF del
In_Frame_Ins | Inframe | IF ins
Silent | Inframe | Silent
Targeted_Region | Inframe | IF
Missense
Missense_Mutation | Missense | Missense
Truncating
Frame_Shift | Truncating | FS
Frame_Shift_Del | Truncating | FS del
Frame_Shift_Ins | Truncating | FS ins
Nonsense_Mutation | Truncating | Nonsense
Nonstop_Mutation | Truncating | Nonstop
Splice_Region | Truncating | Splice
Splice_Site | Truncating | Splice
Other
3’Flank | Other | 3’Flank
3’UTR | Other | 3’UTR
5’Flank | Other | 5’Flank
5’UTR | Other | 5’UTR
De_novo_Start_InFrame | Other | de_novo_start_inframe
De_novo_Start_OutOfFrame | Other | de_novo_start_outofframe
Fusion | Other | Fusion
IGR | Other | IGR
Intron | Other | Intron
lincRNA | Other | lincRNA
RNA | Other | RNA
Start_Codon_Del | Other | Nonstart
Start_Codon_Ins | Other | start_codon_ins
Start_Codon_SNP | Other | Nonstart
Translation_Start_Site | Other | TSS
Unknown | Other | Unknown

↥ back to top

## 4.3 Retrieve Pfam domain inforamtion

Given a HUGO gene symbol, users can either use `hgnc2pfam` function to retrieve Pfam protein domain information first or use all-in-one `g3Lollipop` function to directly create lollipop-diagram. In case that the given gene has multiple isoforms, `hgnc2pfam` returns all UniProt entries, and users can specify one using the corresponding `UniProt` entry. If attribute `guess` is `TRUE`, the Pfam domain information of the longest UniProt entry is returned.

    # Example 1: TP53 has single UniProt entry
    hgnc2pfam("TP53", output.format = "list")
    #> $symbol
    #> [1] "TP53"
    #>
    #> $uniprot
    #> [1] "P04637"
    #>
    #> $length
    #> [1] 393
    #>
    #> $pfam
    #>       hmm.acc     hmm.name start end   type
    #> 37815 PF08563      P53_TAD     5  29  Motif
    #> 37816 PF00870          P53    95 289 Domain
    #> 37817 PF07710 P53_tetramer   319 358  Motif

    # Example 2: GNAS has multiple UniProt entries
    #   `guess = TRUE`: the Pfam domain information of the longest
    #                   UniProt protein is returned
    hgnc2pfam("GNAS", guess = TRUE)
    #> GNAS maps to multiple UniProt entries:
    #>  symbol uniprot length
    #>    GNAS  O95467    245
    #>    GNAS  P63092    394
    #>    GNAS  P84996    626
    #>    GNAS  Q5JWF2   1037
    #> Warning in hgnc2pfam("GNAS", guess = TRUE): Pick: Q5JWF2
    #> {"symbol":"GNAS","uniprot":"Q5JWF2","length":1037,"pfam":[{"hmm.acc":"PF00503","hmm.name":"G-alpha","start":663,"end":1026,"type":"Domain"}]}

↥ back to top

## 4.4 Chart themes

The `g3viz` package contains 8 ready-to-use chart schemes: default, blue, simple, cbioportal, nature, nature2, ggplot2, and dark. Check this tutorial for examples and usage.

↥ back to top

## 4.5 Color schemes

Figure 1 demonstrates all color schemes that `g3viz` supports for lollipop-pops and Pfam domains. More demos are available at demo 1, demo 2, and demo 3.

Figure 1. List of color schemes supported by `g3viz`

↥ back to top

## 4.6 Chart options

Chart options can be specified using `g3Lollipop.options()` function (see example 2). Here is the full list of chart options,

Chart options of `g3viz`
Option | Description
--- | ---
Chart settings
chart.width | chart width in px. Default `800`.
chart.type | pop type, `pie` or `circle`. Default `pie`.
chart.margin | specify chart margin in list format. Default `list(left = 40, right = 20, top = 15, bottom = 25)`.
chart.background | chart background. Default `transparent`.
transition.time | chart animation transition time in millisecond. Default `600`.
Lollipop track settings
lollipop.track.height | height of lollipop track. Default `420`.
lollipop.track.background | background of lollipop track. Default `rgb(244,244,244)`.
lollipop.pop.min.size | lollipop pop minimal size in px. Default `2`.
lollipop.pop.max.size | lollipop pop maximal size in px. Default `12`.
lollipop.pop.info.limit | threshold of lollipop pop size to show count information in middle of pop. Default `8`.
lollipop.pop.info.color | lollipop pop information text color. Default `#EEE`.
lollipop.pop.info.dy | y-axis direction text adjustment of lollipop pop information. Default `-0.35em`.
lollipop.line.color | lollipop line color. Default `rgb(42,42,42)`.
lollipop.line.width | lollipop line width. Default `0.5`.
lollipop.circle.color | lollipop circle border color. Default `wheat`.
lollipop.circle.width | lollipop circle border width. Default `0.5`.
lollipop.label.ratio | lollipop click-out label font size to circle size ratio. Default `1.4`.
lollipop.label.min.font.size | lollipop click-out label minimal font size. Default `10`.
lollipop.color.scheme | color scheme to fill lollipop pops. Default `accent`. Check color schemes for details.
highlight.text.angle | the rotation angle of on-click highlight text in degree. Default `90`.
Domain annotation track settings
anno.height | height of protein structure annotation track. Default `30`.
anno.margin | margin of protein structure annotation track. Default `list(top = 4, bottom = 0)`.
anno.background | background of protein structure annotation track. Default `transparent`.
anno.bar.fill | background of protein bar in protein structure annotation track. Default `#E5E3E1`.
anno.bar.margin | margin of protein bar in protein structure annotation track. Default `list(top = 2, bottom = 2)`.
domain.color.scheme | color scheme of protein domains. Default `category10`. Check color schemes for details.
domain.margin | margin of protein domains. Default `list(top = 0, bottom = 0)`.
domain.text.font | domain label text font in shorthand format. Default `normal 11px Arial`.
domain.text.color | domain label text color. Default `#F2F2F2`.
Y-axis settings
y.axis.label | Y-axis label text. Default `# of mutations`.
axis.label.font | css font style shorthand (font-style font-variant font-weight font-size/line-height font-family). Default `normal 12px Arial`.
axis.label.color | axis label text color. Default `#4f4f4f`.
axis.label.alignment | axis label text alignment (start/end/middle). Default `middle`
axis.label.dy | text adjustment of axis label text. Default `-2em`.
y.axis.line.color | color of y-axis in-chart lines (ticks). Default `#c4c8ca`.
y.axis.line.style | style of y-axis in-chart lines (ticks), `dash` or `line`. Default `dash`.
y.axis.line.width | width of y-axis in-chart lines (ticks). Default `1`.
y.max.range.ratio | ratio of y-axis range to data value range. Default `1.1`.
Chart title settings
title.text | title of chart. Default "".
title.font | font of chart title. Default `normal 16px Arial`.
title.color | color of chart title. Default `#424242`.
title.alignment | text alignment of chart title (start/middle/end). Default `middle`.
title.dy | text adjustment of chart title. Default `0.35em`.
Chart legend settings
legend | if show legend. Default `TRUE`.
legend.margin | legend margin in list format. Default `list(left = 10, right = 0, top = 5, bottom = 5)`.
legend.interactive | legend interactive mode. Default `TRUE`.
legend.title | legend title. If `NA`, use factor name as `factor.col`. Default is `NA`.
Brush selection tool settings
brush | if show brush. Default `TRUE`.
brush.selection.background | background color of selection brush. Default `#666`.
brush.selection.opacity | background opacity of selection brush. Default `0.2`.
brush.border.color | border color of selection brush. Default `#969696`.
brush.handler.color | color of left and right handlers of selection brush. Default `#333`.
brush.border.width | border width of selection brush. Default `1`.
Tooltip and zoom tools
tooltip | if show tooltip. Default `TRUE`.
zoom | if enable zoom feature. Default `TRUE`.

↥ back to top

## 4.7 Save chart as HTML

`g3Lollipop` also renders two buttons over the lollipop-diagram, allowing to save the resulting chart in PNG or vector-based SVG file. To save chart programmatically as HTML, you can use `htmlwidgets::saveWidget` function.

    chart <- g3Lollipop(mutation.dat,
                        gene.symbol = "TP53",
                        protein.change.col = "amino_acid_change",
                        plot.options = plot.options)
    htmlwidgets::saveWidget(chart, "g3lollipop_chart.html")

↥ back to top

# 5 Session Info

    sessionInfo()
    #> R version 3.5.3 (2019-03-11)
    #> Platform: x86_64-apple-darwin15.6.0 (64-bit)
    #> Running under: macOS Mojave 10.14.5
    #>
    #> Matrix products: default
    #> BLAS: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRlapack.dylib
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] kableExtra_1.1.0 knitr_1.22       cgdsr_1.2.10     g3viz_1.1.2
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] Rcpp_1.0.1        rstudioapi_0.10   xml2_1.2.0
    #>  [4] magrittr_1.5      hms_0.4.2         munsell_0.5.0
    #>  [7] rvest_0.3.3       viridisLite_0.3.0 colorspace_1.4-1
    #> [10] R6_2.4.0          rlang_0.3.4       highr_0.8
    #> [13] httr_1.4.0        stringr_1.4.0     tools_3.5.3
    #> [16] webshot_0.5.1     xfun_0.6          R.oo_1.22.0
    #> [19] htmltools_0.3.6   yaml_2.2.0        digest_0.6.18
    #> [22] tibble_2.1.1      crayon_1.3.4      readr_1.3.1
    #> [25] htmlwidgets_1.3   glue_1.3.1        evaluate_0.13
    #> [28] rmarkdown_1.12    stringi_1.4.3     pillar_1.3.1
    #> [31] compiler_3.5.3    scales_1.0.0      R.methodsS3_1.7.1
    #> [34] jsonlite_1.6      pkgconfig_2.0.2

↥ back to top