Package {ggvariant}

Title:	Tidy, 'ggplot2'-Native Visualization for Genomic Variants
Version:	0.2.0
Description:	A simple, opinionated toolkit for visualizing genomic variant data using a 'ggplot2'-native grammar. Accepts VCF files or plain data frames and produces lollipop plots, consequence summaries, mutational spectrum charts, and cohort-level comparisons as standard 'ggplot2' objects. Designed for both wet-lab biologists and experienced bioinformaticians.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	ggplot2 (≥ 3.4.0), cli (≥ 3.6.0), scales (≥ 1.3.0)
Suggests:	plotly (≥ 4.10.0), testthat (≥ 3.0.0), covr, knitr, rmarkdown, vdiffr
Config/testthat/edition:	3
Config/Needs/website:	pkgdown, rmarkdown
URL:	https://github.com/josh45-source/ggvariant, https://josh45-source.github.io/ggvariant/
BugReports:	https://github.com/josh45-source/ggvariant/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-08-20 11:21:56 UTC; Joshua
Author:	Joash Joshua Ayo [aut, cre]
Maintainer:	Joash Joshua Ayo <joashjoshua789@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-21 05:43:32 UTC

ggvariant: Tidy, ggplot2-Native Visualization for Genomic Variants

Description

A simple, opinionated toolkit for visualizing genomic variant data using a 'ggplot2'-native grammar. Accepts VCF files or plain data frames and produces lollipop plots, consequence summaries, mutational spectrum charts, and cohort-level comparisons as standard 'ggplot2' objects. Designed for both wet-lab biologists and experienced bioinformaticians.

Author(s)

Maintainer: Joash Joshua Ayo joashjoshua789@gmail.com (ORCID)

References

Danecek P, Auton A, Abecasis G, et al.; 1000 Genomes Project Analysis Group (2011). The variant call format and VCFtools. Bioinformatics, 27(15), 2156-2158. doi:10.1093/bioinformatics/btr330

Alexandrov LB, Kim J, Haradhvala NJ, et al.; PCAWG Consortium (2020). The repertoire of mutational signatures in human cancer. Nature, 578(7793), 94-101. doi:10.1038/s41586-020-1943-3

See Also

Useful links:

• https://github.com/josh45-source/ggvariant

• https://josh45-source.github.io/ggvariant/

• Report bugs at https://github.com/josh45-source/ggvariant/issues

Coerce a plain data frame to a gvf object

Description

If you already have variant data in a data.frame (e.g. exported from Excel, a database, or another tool), use this function to prepare it for use with ggvariant plotting functions.

Usage

coerce_variants(
  x,
  chrom = "chrom",
  pos = "pos",
  ref = "ref",
  alt = "alt",
  consequence = "consequence",
  gene = "gene",
  sample = "sample"
)

Arguments

Value

A gvf object.

See Also

read_vcf()

Other ggvariant input: read_vcf()

Examples

df <- data.frame(
  chromosome = c("chr1", "chr1", "chr7"),
  position   = c(100200, 100350, 55249071),
  ref_allele = c("A", "G", "C"),
  alt_allele = c("T", "A", "T"),
  variant_class = c("missense_variant", "synonymous_variant", "missense_variant"),
  hugo_symbol = c("GENE1", "GENE1", "EGFR"),
  tumor_sample = c("S1", "S2", "S2")
)

variants <- coerce_variants(df,
  chrom       = "chromosome",
  pos         = "position",
  ref         = "ref_allele",
  alt         = "alt_allele",
  consequence = "variant_class",
  gene        = "hugo_symbol",
  sample      = "tumor_sample"
)

ggvariant colour palettes

Description

Access the built-in colour palettes used by ggvariant plot functions.

Usage

gv_palette(type = c("consequence", "spectrum", "domain"), n = 8L)

Arguments

Details

The "consequence" palette covers the most common VEP/SnpEff/MAF consequence terms; any other term is standardised to an "Other" bucket (its own entry in this palette) by plot functions rather than being dropped.

Value

A named character vector of hex colour codes.

Examples

gv_palette("consequence")
gv_palette("spectrum")

Print and summarise gvf objects

Description

print.gvf() shows a compact header (variant / sample / chromosome / gene counts) followed by a truncated preview, rather than dumping the full underlying data.frame. summary.gvf() returns consequence, per-sample, and per-chromosome breakdowns as a summary.gvf object, printed via its own method.

Usage

## S3 method for class 'gvf'
print(x, ..., n = 6L)

## S3 method for class 'gvf'
summary(object, ...)

## S3 method for class 'summary.gvf'
print(x, ...)

Arguments

Value

print.gvf() returns x, invisibly. summary.gvf() returns a summary.gvf object.

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)
variants
summary(variants)

Consequence summary bar chart

Description

Summarises variant consequences (e.g. missense, frameshift, synonymous) across one or more samples, producing a stacked or grouped bar chart.

Usage

plot_consequence_summary(
  variants,
  samples = NULL,
  group_by = c("consequence", "gene"),
  top_n = 10L,
  position = c("stack", "fill", "dodge"),
  palette = NULL,
  flip = FALSE,
  interactive = FALSE
)

Arguments

Value

A ggplot object.

See Also

plot_lollipop(), plot_variant_spectrum(), gv_palette()

Other ggvariant plots: plot_lollipop(), plot_oncoprint(), plot_tmb(), plot_variant_spectrum()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)

# Consequence counts per sample
plot_consequence_summary(variants)

# Proportional bars
plot_consequence_summary(variants, position = "fill")

# Top 10 genes coloured by consequence
plot_consequence_summary(variants, group_by = "gene", top_n = 10)

Lollipop plot of variants along a gene

Description

Draws a lollipop (stem-and-dot) diagram showing variant positions along a gene, coloured by consequence. Optionally overlays protein domain annotations when domain boundaries are supplied.

Usage

plot_lollipop(
  variants,
  gene = NULL,
  domains = NULL,
  color_by = "consequence",
  palette = NULL,
  protein_length = NULL,
  stack_dots = TRUE,
  title = NULL,
  interactive = FALSE
)

Arguments

Details

domains accepts any protein domain boundaries you supply. Pfam (Paysan-Lafosse et al. 2025) is one source for real domain coordinates, rather than typing them by hand as in the ⁠@examples⁠ below.

Value

A ggplot object (or a plotly object when interactive = TRUE).

References

Paysan-Lafosse T, Andreeva A, Blum M, et al. (2025). The Pfam protein families database: embracing AI/ML. Nucleic Acids Research, 53(D1), D523-D534. doi:10.1093/nar/gkae997

See Also

plot_consequence_summary(), plot_variant_spectrum(), gv_palette()

Other ggvariant plots: plot_consequence_summary(), plot_oncoprint(), plot_tmb(), plot_variant_spectrum()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)

# Basic lollipop for the most-mutated gene
plot_lollipop(variants)

# Specific gene
plot_lollipop(variants, gene = "TP53")

# With domain annotation
tp53_domains <- data.frame(
  name  = c("Transactivation", "DNA-binding", "Tetramerization"),
  start = c(1, 102, 323),
  end   = c(67, 292, 356)
)
plot_lollipop(variants, gene = "TP53", domains = tp53_domains)

Oncoprint / waterfall plot of variants across samples

Description

Draws a gene-by-sample mutation matrix ("oncoprint" in the ComplexHeatmap/cBioPortal vocabulary, "waterfall plot" in the GenVisR/maftools vocabulary — the same visualisation under two names). plot_waterfall() is an alias for plot_oncoprint(); both produce identical output.

Usage

plot_oncoprint(
  variants,
  top_n = NULL,
  genes = NULL,
  samples = NULL,
  annotation = NULL,
  palette = NULL,
  interactive = FALSE
)

plot_waterfall(
  variants,
  top_n = NULL,
  genes = NULL,
  samples = NULL,
  annotation = NULL,
  palette = NULL,
  interactive = FALSE
)

Arguments

Details

Gene order. Genes are ranked by the number of distinct samples carrying at least one mutation in that gene (ties broken by total mutation count, then alphabetically), and the top_n most frequently altered genes are shown, most-altered at the top.

Sample order. Samples are ordered using the memo-sort ("cascade") algorithm: the displayed genes, already ranked most-to-least altered, are treated as bits of a binary number (the most-altered gene the most significant bit). Each sample's mutation pattern across the displayed genes is scored as that binary number, and samples are sorted by descending score (ties broken alphabetically by sample name). This greedily groups samples that share mutations in the top genes together, producing the characteristic left-to-right staircase pattern. Only the displayed genes contribute to the score; genes excluded by top_n/ genes have no effect on sample order.

Multi-hit cells. A gene mutated more than once in the same sample cannot be represented by a single consequence colour, so it is shown as a distinct "Multi_Hit" category instead of either consequence.

Value

A ggplot object (or a plotly object when interactive = TRUE).

References

Gao J, Aksoy BA, Dogrusoz U, et al. (2013). Integrative analysis of complex cancer genomics and clinical profiles using the cBioPortal. Science Signaling, 6(269), pl1. doi:10.1126/scisignal.2004088

Skidmore ZL, Wagner AH, Lesurf R, et al. (2016). GenVisR: Genomic Visualizations in R. Bioinformatics, 32(19), 3012-3014. doi:10.1093/bioinformatics/btw325

Gu Z, Eils R, Schlesner M (2016). Complex heatmaps reveal patterns and correlations in multidimensional genomic data. Bioinformatics, 32(18), 2847-2849. doi:10.1093/bioinformatics/btw313

Mayakonda A, Lin DC, Assenov Y, Plass C, Koeffler HP (2018). Maftools: efficient and comprehensive analysis of somatic variants in cancer. Genome Research, 28(11), 1747-1756. doi:10.1101/gr.239244.118

See Also

plot_tmb(), plot_consequence_summary(), gv_palette()

Other ggvariant plots: plot_consequence_summary(), plot_lollipop(), plot_tmb(), plot_variant_spectrum()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)

# Top 5 most-altered genes
plot_oncoprint(variants, top_n = 5)

# A specific gene panel instead of top_n
plot_oncoprint(variants, genes = c("TP53", "BRCA1", "BRCA2"))

# With a clinical annotation track
clinical <- data.frame(
  sample = c("TUMOR_S1", "TUMOR_S2"),
  stage  = c("III", "IV")
)
plot_oncoprint(variants, top_n = 5, annotation = clinical)

Tumour mutational burden bar chart

Description

Plots per-sample tumour mutational burden (TMB): the number of mutations carried by each sample, optionally normalised to mutations per megabase.

Usage

plot_tmb(
  variants,
  samples = NULL,
  mb_size = NULL,
  sample_order = NULL,
  palette = NULL,
  interactive = FALSE
)

Arguments

Details

The per-sample mutation count is computed by an internal helper shared with any future plot_oncoprint() TMB marginal, so the two always agree. Pass mb_size (the size, in megabases, of the sequenced region) to convert raw counts into mutations/Mb, the conventional TMB unit; leave it NULL to plot raw counts.

Value

A ggplot object (or a plotly object when interactive = TRUE).

References

Chalmers ZR, Connelly CF, Fabrizio D, et al. (2017). Analysis of 100,000 human cancer genomes reveals the landscape of tumor mutational burden. Genome Medicine, 9(1), 34. doi:10.1186/s13073-017-0424-2

See Also

plot_oncoprint(), gv_palette()

Other ggvariant plots: plot_consequence_summary(), plot_lollipop(), plot_oncoprint(), plot_variant_spectrum()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)

# Raw mutation counts, samples ordered by descending TMB
plot_tmb(variants)

# Normalised to mutations/Mb for a 38 Mb exome
plot_tmb(variants, mb_size = 38)

# Aligned to a specific sample order, e.g. from plot_oncoprint()
plot_tmb(variants, sample_order = c("TUMOR_S1", "TUMOR_S2"))

Mutational spectrum (SBS) bar chart

Description

Plots the single-base substitution (SBS) spectrum — the relative frequency of each of the 6 substitution classes (C>A, C>G, C>T, T>A, T>C, T>G) — optionally broken down by trinucleotide context.

Usage

plot_variant_spectrum(
  variants,
  sample = NULL,
  context = FALSE,
  genome = NULL,
  facet_by_sample = FALSE,
  palette = NULL,
  normalize = TRUE,
  interactive = FALSE
)

Arguments

Value

A ggplot object.

References

Alexandrov LB, Kim J, Haradhvala NJ, et al.; PCAWG Consortium (2020). The repertoire of mutational signatures in human cancer. Nature, 578(7793), 94-101. doi:10.1038/s41586-020-1943-3

Blokzijl F, Janssen R, van Boxtel R, Cuppen E (2018). MutationalPatterns: comprehensive genome-wide analysis of mutational processes. Genome Medicine, 10(1), 33. doi:10.1186/s13073-018-0539-0

See Also

plot_lollipop(), plot_consequence_summary(), gv_palette()

Other ggvariant plots: plot_consequence_summary(), plot_lollipop(), plot_oncoprint(), plot_tmb()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)

# Basic 6-class SBS spectrum
plot_variant_spectrum(variants)

# Faceted by sample
plot_variant_spectrum(variants, facet_by_sample = TRUE)

Read a VCF file into a tidy variant data frame

Description

Parses a standard VCF (v4.x) file and returns a tidy data.frame (a gvf object) that all ggvariant plotting functions accept. For users who already have variant data in a plain data.frame or tibble, see coerce_variants().

Usage

read_vcf(path, samples = NULL, pass_only = TRUE, info_fields = NULL)

Arguments

Value

A gvf (genomic variant frame) — a data.frame with columns:

chrom

Chromosome (character)

pos

Position (integer)

ref

Reference allele

alt

Alternate allele (multi-allelic sites are split into rows)

qual

QUAL score (numeric)

filter

FILTER field

sample

Sample name (NA for single-sample VCFs without GT field)

consequence

Variant consequence if ANN/CSQ INFO field is present

gene

Gene symbol if ANN/CSQ INFO field is present

References

Danecek P, Auton A, Abecasis G, et al.; 1000 Genomes Project Analysis Group (2011). The variant call format and VCFtools. Bioinformatics, 27(15), 2156-2158. doi:10.1093/bioinformatics/btr330

Cingolani P, Platts A, Wang LL, et al. (2012). A program for annotating and predicting the effects of single nucleotide polymorphisms, SnpEff: SNPs in the genome of Drosophila melanogaster strain w1118; iso-2; iso-3. Fly, 6(2), 80-92. doi:10.4161/fly.19695

McLaren W, Gil L, Hunt SE, et al. (2016). The Ensembl Variant Effect Predictor. Genome Biology, 17(1), 122. doi:10.1186/s13059-016-0974-4

See Also

coerce_variants(), plot_lollipop(), plot_consequence_summary()

Other ggvariant input: coerce_variants()

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants <- read_vcf(vcf_file)
head(variants)

ggvariant ggplot2 theme

Description

A clean, publication-ready theme based on theme_minimal. Applied automatically by all ggvariant plot functions; export it to customise further.

Usage

theme_ggvariant(base_size = 12, base_family = "")

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, wt)) + geom_point() + theme_ggvariant()