Title:	Tidy, 'ggplot2'-Native Visualization for Genomic Variants
Version:	0.1.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 publication-ready lollipop plots, consequence summaries, mutational spectrum charts, and cohort-level comparisons with minimal code. 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
Config/testthat/edition:	3
URL:	https://github.com/josh45-source/ggvariant
BugReports:	https://github.com/josh45-source/ggvariant/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-02-23 14:21:00 UTC; Joshua
Author:	Joash Joshua Ayo [aut, cre]
Maintainer:	Joash Joshua Ayo <joashjoshua789@gmail.com>
Repository:	CRAN
Date/Publication:	2026-02-27 20:40:02 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 publication-ready lollipop plots, consequence summaries, mutational spectrum charts, and cohort-level comparisons with minimal code. Designed for both wet-lab biologists and experienced bioinformaticians.

Author(s)

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

See Also

Useful links:

• https://github.com/josh45-source/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.

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

Value

A named character vector of hex colour codes.

Examples

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

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.

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

Value

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

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)

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.

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

See Also

coerce_variants(), plot_lollipop(), plot_consequence_summary()

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()