an R package to interactively visualize genetic mutation data using a lollipop-diagram (original) (raw)

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 features including zoom & pan, tooltips, brush selection, and interactive legends.
• Capability to highlight and label positional mutations.
• 8 ready-to-use chart themes.
• Highly customizable with over 50 chart options and more than 35 color schemes.
• Ability to save charts in PNG or high-quality SVG formats.
• Built-in functions 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.
• Integrated support for retrieving cancer mutation data from cBioPortal via API and visualizing it.

↥ back to top

Installg3viz

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

Quick Start

# load g3viz package
library(g3viz)

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 VCFfile using tools like vcf2maf. Translational effect of variant alleles in MAF files are usually in the column named Variant_Classification orMutation_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

Example 2: visualize genetic mutation data from CSV or TSVfile

In this example, we read genetic mutation data from CSVor TSV files, and visualize it using some customizable 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

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 ofTP53 gene for the msk_impact_2017study, and then visualize the data using the built-incbioportal theme, to mimic cBioPortal mutation_mapper.

# Retrieve mutation data of "msk_impact_2017" from cBioPortal
mutation.dat <- getMutationsFromCbioportal("msk_impact_2017", "TP53")
#> The Entrez Gene ID for TP53 is: 7157
#> Found mutation dataset for msk_impact_2017: msk_impact_2017_mutations

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

Note:

• Internet access is required to download mutation data from cBioPortal. This may take more than 10 seconds; sometimes it may fail.
• Check available studies on cBioPortal
• R packages of cBioPortalData or cBioPortalare not stable recently. Therefore, we query the mutation data fromcBioPortal directly using its API. This feature is subject to change in later versions.

↥ back to top

Usage

Read data

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

1. from MAFfile, 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

Map mutation type to mutation class

In addition to reading mutation data, readMAF orgetMutationFromCbioportal functions also map mutation type to mutation class and generate a Mutation_Class column by default. Mutation type is usually in the column ofVariant_Classification or Mutation_Type. The default mapping table is,

↥ back to top

Retrieve Pfam domain inforamtion

Given a HUGO gene symbol, users can use either hgnc2pfam function to retrieve Pfam protein domain information first or 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 a 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
#> 5350 PF08563      P53_TAD     6  30  Motif
#> 5349 PF18521         TAD2    35  59  Motif
#> 5351 PF00870          P53    99 289 Domain
#> 5348 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

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

Color schemes

Figure 1 demonstrates all color schemes that g3viz supports for lollipop-pops and Pfam domains.

{#color_scheme_fig1}

Figure 1. List of color schemes supported byg3viz

↥ back to top

Chart options

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

Chart options of g3viz

↥ back to top

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

Session Info

sessionInfo()
#> R version 4.2.1 (2022-06-23)
#> Platform: x86_64-apple-darwin17.0 (64-bit)
#> Running under: macOS 14.6.1
#> 
#> Matrix products: default
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
#> 
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#>  [1] cBioPortalData_2.8.2        MultiAssayExperiment_1.22.0 SummarizedExperiment_1.26.1 Biobase_2.56.0             
#>  [5] GenomicRanges_1.48.0        GenomeInfoDb_1.32.4         IRanges_2.30.1              S4Vectors_0.34.0           
#>  [9] BiocGenerics_0.42.0         MatrixGenerics_1.8.1        matrixStats_1.3.0           AnVIL_1.8.7                
#> [13] dplyr_1.1.4                 kableExtra_1.4.0            knitr_1.48                  rmarkdown_2.28             
#> [17] g3viz_1.2.0                
#> 
#> loaded via a namespace (and not attached):
#>   [1] bitops_1.0-8              bit64_4.0.5               progress_1.2.3            filelock_1.0.3            httr_1.4.7               
#>   [6] GenomicDataCommons_1.20.3 bslib_0.8.0               tools_4.2.1               utf8_1.2.4                R6_2.5.1                 
#>  [11] DBI_1.2.3                 colorspace_2.1-1          prettyunits_1.2.0         tidyselect_1.2.1          TCGAutils_1.16.1         
#>  [16] bit_4.0.5                 curl_5.2.1                compiler_4.2.1            rvest_1.0.4               httr2_1.0.3              
#>  [21] cli_3.6.3                 formatR_1.14              xml2_1.3.6                DelayedArray_0.22.0       sass_0.4.9               
#>  [26] rtracklayer_1.56.1        scales_1.3.0              readr_2.1.5               rappdirs_0.3.3            rapiclient_0.1.6         
#>  [31] RCircos_1.2.2             Rsamtools_2.12.0          systemfonts_1.1.0         stringr_1.5.1             digest_0.6.37            
#>  [36] svglite_2.1.3             XVector_0.36.0            pkgconfig_2.0.3           htmltools_0.5.8.1         highr_0.11               
#>  [41] dbplyr_2.5.0              fastmap_1.2.0             limma_3.52.4              htmlwidgets_1.6.4         rlang_1.1.2              
#>  [46] rstudioapi_0.16.0         RSQLite_2.3.7             jquerylib_0.1.4           BiocIO_1.6.0              generics_0.1.3           
#>  [51] jsonlite_1.8.8            BiocParallel_1.30.4       RCurl_1.98-1.13           magrittr_2.0.3            GenomeInfoDbData_1.2.8   
#>  [56] futile.logger_1.4.3       Matrix_1.5-4.1            Rcpp_1.0.13               munsell_0.5.1             fansi_1.0.6              
#>  [61] lifecycle_1.0.4           yaml_2.3.10               stringi_1.8.4             RaggedExperiment_1.20.1   RJSONIO_1.3-1.9          
#>  [66] zlibbioc_1.42.0           org.Hs.eg.db_3.15.0       BiocFileCache_2.4.0       grid_4.2.1                blob_1.2.4               
#>  [71] parallel_4.2.1            crayon_1.5.3              lattice_0.22-6            Biostrings_2.64.1         splines_4.2.1            
#>  [76] GenomicFeatures_1.48.4    hms_1.1.3                 KEGGREST_1.36.3           pillar_1.9.0              rjson_0.2.21             
#>  [81] codetools_0.2-20          biomaRt_2.52.0            futile.options_1.0.1      XML_3.99-0.16             glue_1.7.0               
#>  [86] evaluate_0.24.0           lambda.r_1.2.4            data.table_1.15.4         tzdb_0.4.0                png_0.1-8                
#>  [91] vctrs_0.6.5               purrr_1.0.2               tidyr_1.3.1               cachem_1.1.0              xfun_0.47                
#>  [96] restfulr_0.0.15           survival_3.7-0            viridisLite_0.4.2         tibble_3.2.1              RTCGAToolbox_2.26.1      
#> [101] GenomicAlignments_1.32.1  AnnotationDbi_1.58.0      memoise_2.0.1

↥ back to top