MAFDash: R package to easily create an HTML dashboard to summarize and visualize data from Mutation Annotation Format (MAF) file

  collapse = TRUE,
  echo = TRUE,
  message = FALSE,
  warning = FALSE


View examples on

How to get help for MAFDash

Please post all the questions or queries related to MAFDash package on Github Issues. This will help us to build an information repository which can be used by other users.

Getting started

Installation from CRAN


Installation from Github



Mutation Annotation Format (MAF) is a tabular data format used for storing genetic mutation data. For example, The Cancer Genome Atlas (TCGA) project has made MAF files from each project publicly available.

The package -- MAFDash -- contains a set of R tools to easily create an HTML dashboard to summarize and visualize data from MAF file.

The resulting HTML file serves as a self-contained report that can be used to explore the result. Currently, MAFDash produces mostly static plots powered by maftools, ComplexHeatmap and circlize, as well as interactive visualizations using canvasXpress and plotly. The report is generated with a parameterized R Markdown script that uses flexdashboard to arrange all the information.

This package is a companion to the Shiny app, MAFWiz. Instead of relying on a Shiny server, this dashboard is an attempt to try some of those things using client-side javascript functionality.

Make the dashboard

Mutation Annotation Format (MAF) is a tabular data format used for storing genetic mutation data. For example, The Cancer Genome Atlas (TCGA) project has made MAF files from each project publicly available. The main function of MAFDash (getMAFDashboard) creates an HTML dashboard to summarize and visualize data from MAF files. The resulting HTML file serves as a self-contained report that can be used to explore and share the results. The example below shows how we can create an HTML MAF dashboard file. The first argument of getMAFDashboard can be anything that's accepted by maftools's read.maf function (path to a file, or a MAF , data.frame, or data.table object)

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
getMAFDashboard(maf, outputFileName="output", outputFileTitle=paste0("MAF Dashboard - Test"),outputFilePath = tempdir())


Here are some example dashboards created using TCGA data: - TCGA-UVM - TCGA-BRCA

Downloading TCGA mutation data in MAF format

MAFDash also provides a wrapper function getMAFdataTCGA around the TCGABiolinks, which returns the mutation data of different cancers in MAF format from TCGA website. See this page for a list of TCGA codes.

# Download MAF data from TCGA
CancerCode <- c("ACC","UVM")
inputFolderPath <- tempdir() ## This folder will be created if it doesn't exist 
#maf <- getMAFdataTCGA(cancerCode = CancerCode, outputFolder = inputFolderPath)

Creating individual plots using the MAF dataset


The oncoplot shows the number and types of mutations in a set of genes across the samples. The function generateOncoPlot can be used to generate the oncoplot.

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
generateOncoPlot(read.maf(maf,verbose = FALSE))

Burden Plot

The burdenplot compares the total number of mutations between the samples using a dotplot. The figure also have a barplot showing the distribution of different type of mutations across the samples using a barplot.

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
generateBurdenPlot(read.maf(maf,verbose = FALSE), plotType="Dotplot")
generateBurdenPlot(read.maf(maf,verbose = FALSE), plotType="Barplot")

Mutation Type plot

This function generates silent and non-silent mutation plot using the MAF data.

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
generateMutationTypePlot(read.maf(maf,verbose = FALSE))

TiTv plot

This function plot the frequency of Transitions and Transversions of gene mutations

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
plots<-generateTiTvPlot(read.maf(maf,verbose = FALSE))
plotly::subplot(plotly::subplot(plots$tiTvPatterns,plots$TiTv, nrows = 1, widths = c(0.5, 0.25)),plots$barplot,nrows = 2)

TCGA Compare plot

This function plot the comparison of the mutation load against TCGA cohorts

maf <- system.file("extdata", "test.mutect2.maf.gz", package = "MAFDash")
maf <- read.maf(maf = maf,verbose = FALSE)
l<-generateTCGAComparePlot(maf = maf, cohortName = "test")

Adding Custom Plots

The getMAFDashboard() function will accept a named list for adding arbitrary objects to the dashboard. Each item in the list will be displayed in separate tabs, and the name of the element will be used as the title of the tab.

Elements of the list can be:

This functionality can be used with or without providing a MAF file. When MAF data is not provided, the "Variant Table" tab of the dashboard is automatically omitted.

Toy example with iris data



## Simple ggplot
myplot <- ggplot(iris) + geom_point(aes(x=Sepal.Length, y=Sepal.Width, color=Species))

## Save as PNG (provide absolute file path)
mycustomimage_png <- file.path(getwd(),"custom_ggplot.png")
ggsave(mycustomimage_png, plot=myplot, width=5, height=4)

## Save as PDF (provide absolute file path)
mycustomimage_pdf <- file.path(getwd(),"custom_ggplot.pdf")
ggsave(mycustomimage_pdf, plot=myplot, width=5, height=4)

## Convert ggplot to plotly
myplotly <- ggplotly(myplot)

## Make heatmap with ComplexHeatmap
hmdata <- t(iris[,1:4])
hmanno <- HeatmapAnnotation(df=data.frame(Species=iris[,5]))
myhm <- Heatmap(hmdata, bottom_annotation = hmanno)

## Customizable plotly from
custom_plotly <- make_customizable_plotly(iris)

## Put together objects/filepaths into a list
toyplotlist <- list("ggplot"= myplot,
                   "plotly"= myplotly,
                   "PNG"= mycustomimage_png,
                   "PDF"= mycustomimage_pdf,
                   "ComplexHeatmap"= myhm,
                   "Customizable"= custom_plotly

## Filename to output to

## Render dashboard
getMAFDashboard(plotList = toyplotlist,
                outputFileName = html_filename,
                outputFileTitle = "Iris")

Output The output can be seen here.

Advanced Example

Download TCGA data

Download MAF file using TCGABiolinks

MAFDash provides a wrapper function that tries to simplify retrieving data using TCGABiolinks. Valid project codes can be viewed by running TCGABiolinks::getGDCprojects() and checking the "tumor" column.


tcga_code <- c("ACC","UVM")
#inputFolderPath <- paste0(tempdir()) ## This folder will be created if it doesn't exist 
caller = "mutect2"
title_label = paste0("TCGA-",tcga_code)

#maf_files <- getMAFdataTCGA(tcga_code,outputFolder = tempdir(),variant_caller = caller)

Download clinical data using TCGABiolinks

# tcga_clinical <- getTCGAClinicalAnnotation#TCGAbiolinks::GDCquery_clinic(project = paste0("TCGA-",tcga_code), type = "clinical")
# tcga_clinical$Tumor_Sample_Barcode <- tcga_clinical$submitter_id
defaultW <- getOption("warn")
options(warn = -1)
tcga_clinical<-getTCGAClinicalAnnotation(cancerCodes = tcga_code)
options(warn = defaultW)

Make a customized oncoplot

Filter data

The filterMAF function can be used to filter the MAF data in various ways. Importantly, by default, it will remove commonly occurring mutations that are often considered to be false position ( FLAG genes )

#maf_files<- system.file("extdata", "tcga_laml.maf.gz", package = "maftools")
filtered_mafdata <-"rbind",lapply(maf_files, function(maf_file){filter_maf_chunked(maf_file)}))

Add clinical data

The easiest way to add clinical annotations to the oncoplot is to add clinical data to the slot of a MAF object before passing it to the generateOncoplot() function.

MAFDash also provides a function that defines reasonable colors for some common clinical annotations provided with TCGA datasets.

filtered_maf <- read.maf(filtered_mafdata, clinicalData = tcga_clinical$annodata,verbose = FALSE)
annotation_colors <- getTCGAClinicalColors(ageRange = range(tcga_clinical$annodata$age_at_diagnosis, na.rm=T))

Make an annotated oncoplot

The add_clinical_annotations argument can be:

custom_onco <- generateOncoPlot(filtered_maf, 
                                add_clinical_annotations = names(annotation_colors), 
                                clin_data_colors = annotation_colors)

Make some other figures

TCGA Comparison

A lot of maftools's plots are base graphics, so they're drawn to a device and not returned. But we can simply save them to a file and provide the file path.

tcgaComparePlot<-generateTCGAComparePlot(maf = filtered_maf, cohortName = "test")

Chord Diagram of mutation co-occurrence

This function is built on top of maftools's somaticInteractions() function. It's just a different way of visualizing co-occurence or mutual exclusivity between genes.

#ribbonplot_file <- file.path(getwd(),"ribbon.pdf")
generateRibbonPlot(filtered_maf,save_name = NULL)

Render the dashboard

customplotlist <- list("summary_plot"=T,
                       "TCGA Comparison"=tcgaComparePlot$tcga_compare_plot,
                       "Annotated Oncoplot"=custom_onco

## Filename to output to; if output directory doesn't exist, it will be created

## Render dashboard
getMAFDashboard(MAFfilePath = filtered_maf,
                plotList = customplotlist,
                outputFileName = html_filename, 
                outputFileTitle = "Customized Dashboard")


The output can be seen here.

Try the MAFDash package in your browser

Any scripts or data that you put into this service are public.

MAFDash documentation built on April 1, 2022, 9:05 a.m.