Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
In cancer genomics and molecular oncology, maftools is an R/Bioconductor software package designed for the comprehensive exploration, summarization, and visualization of somatic variants stored in Mutation Annotation Format (MAF). Developed by Anand Mayakonda and colleagues (Genome Research, 2018), the package provides bioinformaticians and translational researchers with an integrated toolkit to transform raw variant call tables into publication-ready oncoplots, driver gene predictions, mutational signature profiles, and pathway analyses.
What it is used for in research
In large-scale sequencing initiatives such as The Cancer Genome Atlas (TCGA) and studies hosted on the Genomic Data Commons (GDC), somatic single nucleotide variants (SNVs) and small insertions/deletions (indels) are standardized as MAF files. Researchers utilize maftools for several core analytical tasks:
- Mutational Landscape Visualization: Generating oncoplots (waterfall matrices) that display mutation frequencies, variant types, and sample-level distributions across cancer cohorts.
- Protein Domain Mapping: Constructing lollipop plots that position amino acid changes along annotated protein functional domains sourced from databases such as Ensembl.
- Somatic Interactions Analysis: Performing pairwise Fisher’s exact tests to identify mutually exclusive gene alterations (often pointing to shared biological pathways) and co-occurring mutations.
- Tumor Mutation Burden (TMB) Estimation: Quantifying somatic mutation burden per megabase (mutations/Mb) and benchmarking cohort burdens against reference TCGA cohorts.
- Driver Gene and Signature Extraction: Applying positional clustering algorithms (OncodriveCLUST) to predict oncogenic driver candidates and extracting de novo mutational signatures using non-negative matrix factorization (NMF) mapped against COSMIC signatures.
- Clinical Survival Integration: Evaluating prognostic associations by correlating specific gene mutation statuses with overall survival (OS) or disease-free survival (DFS) curves.
How to install or access it
The official, peer-reviewed release of maftools is distributed through the Bioconductor package repository (project page: https://bioconductor.org/packages/release/bioc/html/maftools.html). It requires an active R installation (R ≥ 4.0.0 is recommended).
To install maftools via the official Bioconductor package manager in your R console, execute:
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("maftools")
To load the package in an R session or automated script:
library(maftools)
In institutional high-performance computing (HPC) clusters or containerized workflow managers like Snakemake or Nextflow, maftools can also be integrated via standard Bioconda channels (package: bioconductor-maftools) or container recipes.
Step-by-step task
The following step-by-step procedure demonstrates an end-to-end somatic analysis workflow using the acute myeloid leukemia (TCGA LAML) dataset bundled directly within the maftools installation.
-
Locate and inspect bundled input data: Retrieve the absolute file paths to the bundled compressed MAF file and its corresponding clinical annotation file using
system.file:library(maftools) # Locate example MAF and clinical metadata files laml_maf <- system.file("extdata", "tcga_laml.maf.gz", package = "maftools") laml_clin <- system.file("extdata", "tcga_laml_annot.tsv", package = "maftools") -
Import data into a MAF object with
read.maf: Parse the files into an S4MAFobject. The function validates mandatory columns, aggregates variant counts, and attaches clinical covariates:# Read MAF data and attach clinical covariates laml <- read.maf(maf = laml_maf, clinicalData = laml_clin) # Display cohort-level summary statistics print(laml) -
Generate a cohort summary dashboard: Produce a multi-panel overview illustrating variant classifications, variant types, single nucleotide variant (SNV) class distribution, and per-sample mutation counts:
plotmafSummary( maf = laml, rmOutlier = TRUE, addStat = "median", dashboard = TRUE, titvRaw = FALSE ) -
Visualize top mutated genes with an oncoplot: Draw a publication-standard waterfall plot displaying somatic alterations for the top 10 most frequently mutated genes, alongside selected clinical annotations:
oncoplot( maf = laml, top = 10, clinicalFeatures = c("FAB_classification", "Overall_Survival_Status"), sortByAnnotation = TRUE, removeNonMutated = TRUE, fontSize = 0.8 ) -
Map mutation hotspots on protein domains: Generate a lollipop plot highlighting amino acid substitution sites and functional protein domains for a specific recurrently mutated driver (e.g., DNMT3A):
lollipopPlot( maf = laml, gene = "DNMT3A", AACol = "Protein_Change", showMutationRate = TRUE, labelPos = 882 ) -
Test somatic interactions (mutual exclusivity and co-occurrence): Perform pairwise Fisher’s exact tests across the top 20 mutated genes to uncover significant associations:
# Evaluate pairwise somatic interactions interactions <- somaticInteractions( maf = laml, top = 20, pvalue = c(0.05, 0.01) )
Output and how to read it
Working with maftools produces both structured R data objects and graphical visual outputs:
- The S4 MAF Data Object: Inspecting the object via
print(laml)displays total number of samples, total variants detected, and summary breakdowns of coding non-synonymous mutations. Accessing slots directly (e.g.,laml@datafor the variant table or[email protected]for phenotypic metadata) provides cleandata.tablestructures for custom downstream computing. - Oncoplot (Waterfall Plot): Rows represent genes ordered by mutation frequency across the cohort, while columns represent individual tumor specimens. Distinct color tiles indicate mutation categories (e.g., Missense_Mutation, Frame_Shift_Del, Nonsense_Mutation, Splice_Site). Right-side bar plots display the percentage and absolute count of altered samples per gene, while top annotations show sample mutation load and clinical attributes.
- Lollipop Plot: The horizontal axis represents the primary amino acid sequence of the target transcript, with colored geometric blocks indicating Pfam functional protein domains. Vertical pins (“lollipops”) denote specific amino acid residues where mutations occur, with pin height indicating mutation frequency within the cohort to highlight recurring hotspot alterations (such as R882 in DNMT3A).
- Somatic Interactions Matrix: The output heat matrix displays pairwise odds ratios and p-values. Pairs displaying significant co-occurrence are typically shaded in blue, whereas mutually exclusive gene pairs (such as mutually exclusive mutations in pathway components) are shaded in brown or dark orange.
Troubleshooting
Bioinformaticians frequently encounter standard data formatting and execution challenges when running maftools. The following solutions resolve the most common issues:
- Error: Missing mandatory MAF columns:
read.maf()requires 9 standard column headers:Hugo_Symbol,Chromosome,Start_Position,End_Position,Reference_Allele,Tumor_Seq_Allele2,Variant_Classification,Variant_Type, andTumor_Sample_Barcode. If your variant calling pipeline outputs alternative headers (such asGene,Sample_ID, orConsequence), rename them in your data frame prior to callingread.maf():colnames(my_variants)[colnames(my_variants) == "Sample_ID"] <- "Tumor_Sample_Barcode" colnames(my_variants)[colnames(my_variants) == "Gene"] <- "Hugo_Symbol" - Warning: “Non MAF specific values in Variant_Classification column”: This warning occurs when input files contain variant effect annotations from Ensembl VEP, ANNOVAR, or SnpEff that do not match standard TCGA classification terms. Standard values include
Missense_Mutation,Nonsense_Mutation,Frame_Shift_Del,Frame_Shift_Ins,In_Frame_Del,In_Frame_Ins,Splice_Site,Translation_Start_Site, andNonstop_Mutation. If you wish to treat custom classifications as non-synonymous damaging events, pass them explicitly using thevc_nonSynparameter:laml <- read.maf(maf = "custom_variants.maf", vc_nonSyn = c("Missense_Mutation", "Stop_Gained", "Frameshift")) - Error: Biostrings or BSgenome dependency errors during signature analysis: Functions such as
trinucleotideMatrix()extract sequence contexts from genomic reference packages. Ensure the matching BSgenome assembly (e.g.,BSgenome.Hsapiens.UCSC.hg38orBSgenome.Hsapiens.UCSC.hg19) is installed viaBiocManager::install()and loaded prior to signature extraction. - Memory allocation limits with large whole-genome sequencing (WGS) cohorts: When loading multi-gigabyte MAF files containing millions of non-coding or synonymous variants, set
useAll = FALSEinread.maf()to retain only non-synonymous variants in memory, or use command-line pre-filtering tools (such asawkorgrep) to subset target cohorts.
Free alternatives
Researchers evaluating cancer variant visualization and somatic analysis software can choose from several open-source tools across R, Python, and web environments:
| Tool | Environment / Language | Primary Focus and Key Capabilities | Software License |
|---|---|---|---|
| maftools | R / Bioconductor | Comprehensive end-to-end somatic analysis: oncoplots, lollipop plots, signature analysis, driver discovery, and clinical survival integration. | MIT License |
| ComplexHeatmap (oncoPrint) | R / Bioconductor | Fine-grained heatmap and oncoplot rendering; allows complex multi-omics layering (mutations, expressions, copy numbers) with custom grid styling. | MIT License |
| MutScape | Python | Cohort-level somatic mutation analysis pipeline supporting both VCF and MAF files, false-positive filtering, and mutational signatures. | MIT License |
| CoMut | Python | Minimalist, publication-grade plotting library for creating integrated co-plots of mutations, continuous clinical variables, and categorical metadata in bioinformatics Python workflows. | MIT License |
| cBioPortal | Web / Java / TypeScript | Open-access web platform for interactive cohort exploration, survival analysis, mutual exclusivity calculation, and 3D protein structure mapping without coding. | GNU AGPLv3 |
FAQ
What file formats can be converted into MAF for analysis in maftools?
The standard format accepted by maftools is Mutation Annotation Format (MAF), a tab-delimited text format. Variant Call Format (VCF) files produced by standard variant callers (such as GATK Mutect2, Strelka2, or VarScan2) can be converted into MAF using the open-source vcf2maf utility, which runs Ensembl Variant Effect Predictor (VEP) to annotate consequence types and populate gene symbols.
What are the mandatory columns required in a custom MAF file?
According to the official maftools documentation, a custom MAF file must contain nine specific column headers: Hugo_Symbol, Chromosome, Start_Position, End_Position, Reference_Allele, Tumor_Seq_Allele2, Variant_Classification, Variant_Type, and Tumor_Sample_Barcode. Files lacking any of these columns will trigger an error during read.maf().
How does maftools detect mutually exclusive and co-occurring gene mutations?
The somaticInteractions() function creates a 2×2 contingency table for every pair of genes within the specified gene set (defaulting to the top 25 mutated genes). It executes pairwise Fisher’s exact tests to evaluate whether mutations in gene A and gene B occur together more frequently than expected by chance (co-occurrence) or avoid co-occurring (mutual exclusivity).
Can maftools integrate copy number alteration (CNA) data?
Yes. read.maf() accepts copy-number data via the copyNumberData parameter or through dedicated GISTIC module functions (readGistic()). When GISTIC output files (such as all_lesions.conf_XX.txt and amp_genes.conf_XX.txt) are provided, maftools integrates focal amplifications and deletions directly into cohort oncoplots alongside somatic mutations.
Sources
Primary documentation, software repositories, and peer-reviewed literature referenced for this guide:
- Bioconductor Project:
maftools: Summarize, Analyze and Visualize MAF Files. Official Bioconductor Package Repository. Available at:https://bioconductor.org/packages/release/bioc/html/maftools.html(checked 2026-11-08). - Mayakonda, A., Lin, D. C., Assenov, Y., Plass, C., and Koeffler, H. P. (2018). “Maftools: efficient and comprehensive analysis of somatic variants in cancer.” Genome Research, 28(11), 1747–1756. DOI:
https://doi.org/10.1101/gr.239244.118(checked 2026-11-08). - Bioconductor Vignette:
Maftools: Summarize, Analyze and Visualize MAF Files. Official Vignette Documentation. Available at:https://bioconductor.org/packages/release/bioc/vignettes/maftools/inst/doc/maftools.html(checked 2026-11-08). - GitHub Repository:
PoisonAlien/maftools. Official Source Code and Issue Tracker. Available at:https://github.com/PoisonAlien/maftools(checked 2026-11-08).







