This function creates a coverage track visualization from various input types. It provides a flexible interface with support for grouping and multiple tracks.
Usage
ez_coverage(
input,
region = NULL,
gene = NULL,
gene_db = NULL,
org_db = NULL,
extend = 0.1,
extend_type = c("proportion", "bp"),
track_labels = NULL,
type = c("area", "line", "heatmap"),
group_var = NULL,
color_by = c("group", "track"),
colors = NULL,
y_axis_style = c("none", "simple", "minmax", "full"),
y_range = NULL,
alpha = 0.5,
bin_width = NULL,
area_border = TRUE,
facet_label_position = c("top", "left"),
border = FALSE,
show_legend = FALSE,
label_chr = TRUE,
verbose = FALSE,
average = FALSE,
summary_fun = c("mean", "median", "max", "min", "sum"),
n_bins = 2000L,
strand = c("None", "F", "R"),
...
)Arguments
- input
A GRanges object, data frame, character vector of file paths, or named list of data sources.
- region
Genomic region to display (e.g., "chr1:1000000-2000000"). Either
regionorgene(withgene_db) must be provided.- gene
Gene name/symbol to look up (e.g., "PTPRC", "TP53"). When provided, the region is automatically determined from the gene coordinates. If
gene_dbis not specified, uses a data frame frominputif available (recommended). Eitherregionorgenemust be provided.- gene_db
Optional. TxDb object, GTF/GFF file path, or data frame for gene coordinate lookup when using
geneparameter. If NULL (default) andinputis a data frame, usesinputfor lookup. Only required ifinputis not a data frame annotation.- org_db
Optional OrgDb object for gene symbol mapping. If NULL (default), auto-detects available OrgDb packages.
- extend
Numeric. Amount to extend the region beyond the gene body when using
geneparameter. Default: 0.1 (10% of gene length on each side).- extend_type
How to interpret
extend: "proportion" (relative to gene length) or "bp" (absolute base pairs). Default: "proportion".- track_labels
Optional vector of track labels (used for character vector input)
- type
Type of signal visualization: "line", "area", or "heatmap" (default: "area")
- group_var
Column name for grouping data within a single data frame (default: NULL)
- color_by
Whether colors distinguish "group" or "track" (default: "group")
- colors
Color(s) for the coverage track. Can be a single color or a vector of colors for multiple tracks/groups (e.g., c("blue", "orange", "green")). If fewer colors than tracks/groups are provided, colors will be recycled. When NULL (default), uses vibeColors palette if available, otherwise "steelblue". For multiple tracks with a single color, automatically uses a colorblind-safe palette.
- y_axis_style
Y-axis style: "none", "simple", "minmax", or "full" (default: "none")
"none": No y-axis displayed
"simple": Shows y-range as [min - max] label at top-left
"minmax": Shows only min and max values on y-axis with ticks
"full": Full y-axis with all ticks and labels
- y_range
Y-axis range limits. When NULL (default), uses the global maximum across all tracks so all tracks share the same y-scale.
- alpha
Transparency (default: 0.5)
- bin_width
Width of bins in base pairs (default: NULL)
- area_border
Logical; if
TRUE(default), draws thin borders on area rectangles to eliminate white-line rendering artifacts. Only affectstype = "area".- facet_label_position
Position of facet labels: "top" or "left" (default: "top")
- border
Logical. If
TRUE, adds a black border around the plotting panel (default: FALSE)- show_legend
Logical. If
TRUE, displays the legend (default: FALSE)- label_chr
Logical. If
TRUE(default), labels the x-axis with the chromosome name (e.g., "Chr1"). Set toFALSEto suppress the x-axis label.- verbose
Logical. If
TRUE, print megadepth progress output for BigWig imports. IfFALSE(default), suppress routine messages.- average
Logical. If
TRUE, averages overlapping tracks into a single track before plotting. Applies wheninputis a character vector of multiple file paths (overlapping tracks), or wheninputis a named list whose elements are character vectors with multiple files (averages within each list element separately, keeping tracks independent). Usesaverage_coverage()internally. (default: FALSE)- summary_fun
Summary function used when
average = TRUE. One of"mean","median","max","min","sum". (default:"mean")- n_bins
Maximum number of bins used when reading BigWig files via megadepth (default: 2000). Increase for finer detail, decrease for faster plotting.
- strand
Strand to display:
"None"(default, no operation),"F"(forward, no operation), or"R"(reverse — negates the coverage signal so it plots below zero). Useful for creating paired forward/reverse strand tracks.- ...
Additional arguments passed to geom_coverage
Examples
# From a GRanges object
library(GenomicRanges)
gr <- GRanges(
seqnames = "chr1",
ranges = IRanges(start = 1:100, end = 1:100),
score = rnorm(100)
)
ez_coverage(gr, "chr1:1-100")
# Single data frame with grouping
df <- data.frame(
seqnames = "chr1", start = 1:100, end = 1:100,
score = rnorm(100), sample = rep(c("A", "B"), 50)
)
ez_coverage(df, "chr1:1-100", group_var = "sample", colors = c("blue", "orange"))
if (FALSE) { # \dontrun{
# Using gene name instead of coordinates
library(TxDb.Hsapiens.UCSC.hg38.knownGene)
ez_coverage(signal_data, gene = "PTPRC", gene_db = TxDb.Hsapiens.UCSC.hg38.knownGene)
} # }