Skip to main content
v2026.11,986 entries · CC-BY 4.0

maftools: Mutation Analysis and Oncoplots in R

Analyze Mutation Annotation Format (MAF) files in R with maftools. Learn installation, oncoplot visualization, somatic interactions and troubleshooting.

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.

  1. 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")
  2. Import data into a MAF object with read.maf: Parse the files into an S4 MAF object. 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)
  3. 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
    )
  4. 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
    )
  5. 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
    )
  6. 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@data for the variant table or [email protected] for phenotypic metadata) provides clean data.table structures 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, and Tumor_Sample_Barcode. If your variant calling pipeline outputs alternative headers (such as Gene, Sample_ID, or Consequence), rename them in your data frame prior to calling read.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, and Nonstop_Mutation. If you wish to treat custom classifications as non-synonymous damaging events, pass them explicitly using the vc_nonSyn parameter:
    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.hg38 or BSgenome.Hsapiens.UCSC.hg19) is installed via BiocManager::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 = FALSE in read.maf() to retain only non-synonymous variants in memory, or use command-line pre-filtering tools (such as awk or grep) 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).

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about maftools: Mutation Analysis and Oncoplots in R

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →