| Title: | Proportional Venn and UpSet Diagrams for Gene Sets and Genomic Regions |
|---|---|
| Description: | Tools to compute and visualize overlaps between gene sets or genomic regions. Venn diagrams with proportional areas are provided, while UpSet plots are recommended for larger numbers of sets. The package supports GRanges and GRangesList inputs, and integrates with analysis workflows for ChIP-seq, ATAC-seq, and other genomic interval data. It generates clean, interpretable, and publication-ready figures. |
| Authors: | Christophe Tav [aut, cre] (ORCID: <https://orcid.org/0000-0001-8808-9617>) |
| Maintainer: | Christophe Tav <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.99.0 |
| Built: | 2026-09-28 07:14:22 UTC |
| Source: | https://github.com/bioc/gVenn |
Example consensus peak subsets for MED1, BRD4, and GR after dexamethasone
treatment in A549 cells. Each set has been restricted to peaks on
chr7 to keep the dataset small and suitable for examples and tests.
data(a549_chipseq_peaks)data(a549_chipseq_peaks)
A GRangesList with 3 named elements:
Consensus MED1 peaks (chr7 subset).
Consensus BRD4 peaks (chr7 subset).
Consensus GR peaks (chr7 subset).
The original full consensus peak sets are available as gzipped BED files in
inst/extdata/:
A549_MED1_Dex.stdchr.bed.gz
A549_BRD4_Dex.stdchr.bed.gz
A549_GR_Dex.stdchr.bed.gz
These are not trimmed, but for package efficiency the dataset here
(a549_chipseq_peaks) only includes the chr7 subsets.
Internal consensus peak sets processed in A549 cells after dexamethasone stimulation.
Tav C, Fournier É, Fournier M, Khadangi F, Baguette A, Côté MC, Silveira MAD, Bérubé-Simard F-A, Bourque G, Droit A, Bilodeau S (2023). "Glucocorticoid stimulation induces regionalized gene responses within topologically associating domains." Frontiers in Genetics. doi:10.3389/fgene.2023.1237092
# Load dataset data(a549_chipseq_peaks) a549_chipseq_peaks # Compute overlaps and plot ov <- computeOverlaps(a549_chipseq_peaks) plotVenn(ov)# Load dataset data(a549_chipseq_peaks) a549_chipseq_peaks # Compute overlaps and plot ov <- computeOverlaps(a549_chipseq_peaks) plotVenn(ov)
computeOverlaps() is the main entry point for overlap analysis. It accepts
either genomic region objects (GRanges/GRangesList) or ordinary sets
(character/numeric vectors) and computes a binary overlap matrix describing
the presence or absence of each element across sets.
computeOverlaps(x, mode = c("reduce", "disjoin"), ignore.strand = FALSE)computeOverlaps(x, mode = c("reduce", "disjoin"), ignore.strand = FALSE)
x |
Input sets. One of:
If the list is unnamed, sets are named |
mode |
Character string selecting where the boundaries of the partition fall. One of:
See Examples for a chained configuration under both modes. Ignored (with a warning) for non-genomic inputs. |
ignore.strand |
Logical, default |
When provided with genomic regions, the function builds a non-redundant
set of intervals (see mode), then determines which original sets each
region overlaps.
When provided with ordinary sets (e.g., gene symbols), it collects all unique elements and records which sets contain them.
The resulting object encodes both the overlap matrix and compact category
labels (e.g., "110") representing the overlap pattern of each element.
These results can be directly passed to visualization functions such as
plotVenn() or plotUpSet().
Internally, computeOverlaps() dispatches to either
computeGenomicOverlaps() (for genomic inputs) or
computeSetOverlaps() (for ordinary sets). Users are encouraged to call
only computeOverlaps().
gVenn does not harmonize chromosome names or coordinate systems across input
sets: genomic sets are expected to follow the same naming convention and to
come from the same genome assembly. As a safeguard, computeOverlaps() warns
whenever two input sets share no chromosome name at all, naming the offending
pairs. Such a mismatch usually signals incompatible naming conventions (e.g.
"chr1" vs "1") or different assemblies, cases in which overlaps between
those sets would otherwise be silently and permanently empty rather than
raising an error. Only chromosomes actually present in each set are compared.
Conflicting assemblies declared on a shared chromosome name (e.g. "chr1"
tagged hg38 in one set and hg19 in another) already raise an error in
GenomicRanges::GRangesList(), before any overlap is computed.
An S3 object encoding the overlap result whose class depends on the input type:
Returned when the input is genomic
(GRangesList or list of GRanges). A list with:
regions: A GRanges object containing the reduced
regions (mode = "reduce") or disjoint regions
(mode = "disjoin"). Each region is annotated with an
intersect_category column giving the binary code of its
overlap group.
overlap_matrix: A logical matrix indicating whether each
region overlaps each input set (rows = regions,
columns = sets).
mode: The mode used to build the regions.
Returned when the input is a list of atomic vectors. A list with:
unique_elements: Character vector of all unique elements
across the sets.
overlap_matrix: A logical matrix indicating whether each
element is present in each set (rows = elements, columns = sets).
intersect_category: Character vector giving the
binary code of the overlap group (e.g., "110") of each
element.
plotVenn, plotUpSet,
GRangesList,
reduce,
disjoin
# Example with gene sets (built-in dataset) data(gene_list) ov_sets <- computeOverlaps(gene_list) head(ov_sets$overlap_matrix) plotVenn(ov_sets) # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) ov_gr <- computeOverlaps(a549_chipseq_peaks) head(ov_gr$overlap_matrix) plotVenn(ov_gr) # Chained overlaps: A-B and B-C overlap, but A and C do not A <- GenomicRanges::GRanges("chr1", IRanges::IRanges(100, 200)) B <- GenomicRanges::GRanges("chr1", IRanges::IRanges(180, 300)) C <- GenomicRanges::GRanges("chr1", IRanges::IRanges(280, 400)) # "reduce" merges the chain into a single "111" region computeOverlaps(list(A = A, B = B, C = C))$regions # "disjoin" keeps A-B and B-C as separate two-way intersections computeOverlaps(list(A = A, B = B, C = C), mode = "disjoin")$regions # Overlapping regions on opposite strands: kept separate by default, # merged when ignore.strand = TRUE D <- GenomicRanges::GRanges("chr1", IRanges::IRanges(100, 200), strand = "+") E <- GenomicRanges::GRanges("chr1", IRanges::IRanges(150, 250), strand = "-") computeOverlaps(list(D = D, E = E))$regions computeOverlaps(list(D = D, E = E), ignore.strand = TRUE)$regions# Example with gene sets (built-in dataset) data(gene_list) ov_sets <- computeOverlaps(gene_list) head(ov_sets$overlap_matrix) plotVenn(ov_sets) # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) ov_gr <- computeOverlaps(a549_chipseq_peaks) head(ov_gr$overlap_matrix) plotVenn(ov_gr) # Chained overlaps: A-B and B-C overlap, but A and C do not A <- GenomicRanges::GRanges("chr1", IRanges::IRanges(100, 200)) B <- GenomicRanges::GRanges("chr1", IRanges::IRanges(180, 300)) C <- GenomicRanges::GRanges("chr1", IRanges::IRanges(280, 400)) # "reduce" merges the chain into a single "111" region computeOverlaps(list(A = A, B = B, C = C))$regions # "disjoin" keeps A-B and B-C as separate two-way intersections computeOverlaps(list(A = A, B = B, C = C), mode = "disjoin")$regions # Overlapping regions on opposite strands: kept separate by default, # merged when ignore.strand = TRUE D <- GenomicRanges::GRanges("chr1", IRanges::IRanges(100, 200), strand = "+") E <- GenomicRanges::GRanges("chr1", IRanges::IRanges(150, 250), strand = "-") computeOverlaps(list(D = D, E = E))$regions computeOverlaps(list(D = D, E = E), ignore.strand = TRUE)$regions
This function exports the output of extractOverlaps() to an Excel file,
creating one sheet per overlap group. Genomic overlaps (GRanges) are
converted to data frames before export.
exportOverlaps( grouped, output_dir = ".", output_file = "overlap_groups", with_date = TRUE, verbose = TRUE )exportOverlaps( grouped, output_dir = ".", output_file = "overlap_groups", with_date = TRUE, verbose = TRUE )
grouped |
Overlap groups from |
output_dir |
A string specifying the output directory. Defaults to |
output_file |
A string specifying the base filename (without extension).
Defaults to |
with_date |
Logical (default |
verbose |
Logical. If |
Overlap groups are saved to an Excel file on disk. Invisibly returns the full path to the saved file.
res <- computeOverlaps(list(A = letters[1:3], B = letters[2:4])) grouped <- extractOverlaps(res) exportOverlaps(grouped, output_dir = tempdir(), output_file = "overlap_groups")res <- computeOverlaps(list(A = letters[1:3], B = letters[2:4])) grouped <- extractOverlaps(res) exportOverlaps(grouped, output_dir = tempdir(), output_file = "overlap_groups")
This function exports genomic overlap groups from extractOverlaps() to
BED format files, creating one BED file per overlap group.
exportOverlapsToBed( grouped, output_dir = ".", output_prefix = "overlaps", with_date = TRUE, verbose = TRUE )exportOverlapsToBed( grouped, output_dir = ".", output_prefix = "overlaps", with_date = TRUE, verbose = TRUE )
grouped |
Genomic overlap groups from |
output_dir |
A string specifying the output directory. Defaults to |
output_prefix |
A string specifying the filename prefix.
Defaults to |
with_date |
Logical (default |
verbose |
Logical. If |
This function only works with genomic overlaps (i.e., when the input to
extractOverlaps() was a GenomicOverlapResult object, resulting in a
GRangesList). It does not work with set overlaps (character vectors).
Each overlap group will be saved as a separate BED file with the group
identifier included in the filename.
Invisibly returns a character vector of file paths created.
data(a549_chipseq_peaks) grouped <- extractOverlaps(computeOverlaps(a549_chipseq_peaks)) exportOverlapsToBed(grouped, output_dir = tempdir())data(a549_chipseq_peaks) grouped <- extractOverlaps(computeOverlaps(a549_chipseq_peaks)) exportOverlapsToBed(grouped, output_dir = tempdir())
This function extracts the elements of each overlap group, identified by
its binary code (e.g., "110"). For genomic overlaps, the elements are the
reduced or disjoint regions built by computeOverlaps, not the
input intervals.
For genomic overlaps, it returns a GRangesList; for set overlaps, it
returns a named list of character vectors.
extractOverlaps(overlap_object)extractOverlaps(overlap_object)
overlap_object |
A |
A named list with one entry per overlap group, named by its binary
code prefixed with "group_" (e.g., "group_110") and ordered by the
number of sets involved:
If input is a GenomicOverlapResult, a GRangesList split
by intersect_category.
If input is a SetOverlapResult, a named list of character vectors
grouped by intersect_category.
# Example with gene sets (built-in dataset) data(gene_list) res_sets <- computeOverlaps(gene_list) group_gene <- extractOverlaps(res_sets) group_gene # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) res_genomic <- computeOverlaps(a549_chipseq_peaks) group_genomic <- extractOverlaps(res_genomic) group_genomic# Example with gene sets (built-in dataset) data(gene_list) res_sets <- computeOverlaps(gene_list) group_gene <- extractOverlaps(res_sets) group_gene # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) res_genomic <- computeOverlaps(a549_chipseq_peaks) group_genomic <- extractOverlaps(res_genomic) group_genomic
A synthetic dataset of three gene lists, created from the first 250 human gene symbols in org.Hs.eg.db.
data(gene_list)data(gene_list)
A named list of length 3. Each element is a character vector
of gene symbols:
125 gene symbols.
115 gene symbols.
70 gene symbols.
Generated from org.Hs.eg.db (keys of type SYMBOL),
using a reproducible random seed.
data(gene_list) # Inspect the list str(gene_list) # Compute overlaps and plot ov <- computeOverlaps(gene_list) plotVenn(ov)data(gene_list) # Inspect the list str(gene_list) # Compute overlaps and plot ov <- computeOverlaps(gene_list) plotVenn(ov)
This function creates an UpSet plot using the ComplexHeatmap package to
visualize intersections across multiple sets.
Supports both GenomicOverlapResult and SetOverlapResult objects.
plotUpSet(overlap_object, customSetOrder = NULL, comb_col = "black")plotUpSet(overlap_object, customSetOrder = NULL, comb_col = "black")
overlap_object |
A |
customSetOrder |
Optional. A vector specifying the order of sets to
display on the UpSet diagram. The vector should contain either numeric
indices (corresponding to the sets in the overlap object) or character
names (matching the set names). If |
comb_col |
Optional. Color(s) for the combination matrix dots and connecting lines. Can be a single color or a vector of colors (recycled to match the number of intersections). Default is "black". |
An UpSet plot object generated by ComplexHeatmap::UpSet. The
right-hand annotation bars are labeled "Region size" for a
GenomicOverlapResult input (the number of reduced or disjoint regions
per set, not the number of original input peaks) and "Set size" for a
SetOverlapResult input (no such transformation applies to gene/identifier
sets).
# Example with gene sets (built-in dataset) data(gene_list) res_sets <- computeOverlaps(gene_list) # Default order (sets sorted by size) plotUpSet(res_sets) # Custom color plotUpSet(res_sets, comb_col = "darkblue") # Custom order by names plotUpSet(res_sets, customSetOrder = c("random_genes_C", "random_genes_A", "random_genes_B")) # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) res_genomic <- computeOverlaps(a549_chipseq_peaks) plotUpSet(res_genomic)# Example with gene sets (built-in dataset) data(gene_list) res_sets <- computeOverlaps(gene_list) # Default order (sets sorted by size) plotUpSet(res_sets) # Custom color plotUpSet(res_sets, comb_col = "darkblue") # Custom order by names plotUpSet(res_sets, customSetOrder = c("random_genes_C", "random_genes_A", "random_genes_B")) # Example with genomic regions (built-in dataset) data(a549_chipseq_peaks) res_genomic <- computeOverlaps(a549_chipseq_peaks) plotUpSet(res_genomic)
This function creates a Venn diagram using the eulerr package to visualize
intersections across multiple sets. Supports both
GenomicOverlapResult and SetOverlapResult objects. Diagrams are
recommended for two to four sets: beyond that, an area-proportional layout
is rarely attainable, and plotUpSet is the better choice.
plotVenn( overlap_object, fills = TRUE, edges = TRUE, labels = FALSE, quantities = list(type = "counts"), legend = "right", main = NULL, verbose = TRUE, ... )plotVenn( overlap_object, fills = TRUE, edges = TRUE, labels = FALSE, quantities = list(type = "counts"), legend = "right", main = NULL, verbose = TRUE, ... )
overlap_object |
A |
fills |
Controls the fill appearance of the diagram. Can be:
|
edges |
Controls the edge/border appearance. Can be:
|
labels |
Controls set labels. Can be:
|
quantities |
Controls intersection quantities display. Can be:
|
legend |
Controls the legend. Can be:
|
main |
Title for the plot. Can be character, expression, or list with
|
verbose |
Logical. If |
... |
Additional arguments passed to |
A Venn diagram plot generated by eulerr, with two
attributes:
"fit_diagnostics": a list with stress, diagError,
regionError (see euler) and
undrawnRegions, the populated regions given no area. diagError
is the largest difference, over all regions, between the share of
the diagram's area a region receives and the share its count
requires; Micallef and Rodgers (2014) consider a diagram accurate
when it is at most 1e-6.
"euler_fit": the eulerr fit itself.
plotVennError to see which regions the diagram
misrepresents and in which direction, plotUpSet.
# Example with gene sets data(gene_list) res_sets <- computeOverlaps(gene_list) # Basic plot plotVenn(res_sets) # Customize fills with transparency and custom colors plotVenn(res_sets, fills = list(fill = c("#FF6B6B", "#4ECDC4", "#45B7D1"), alpha = 0.6)) # Customize edges plotVenn(res_sets, edges = list(col = "darkgray", lwd = 2, lty = 2)) # Customize labels plotVenn(res_sets, labels = list(col = "white", font = 2, fontsize = 14)) # Show both counts and percentages plotVenn(res_sets, quantities = list(type = c("counts", "percent"), col = "black", fontsize = 10)) # Add a title plotVenn(res_sets, main = list(label = "Gene Set Overlaps", col = "navy", fontsize = 16, font = 2)) # Transparent fills with colored borders only plotVenn(res_sets, fills = "transparent", edges = list(col = c("red", "blue", "green"), lwd = 3)) # Custom legend plotVenn(res_sets, legend = list(side = "bottom", labels = c("Treatment A", "Treatment B", "Control"), fontsize = 12)) # Inspect eulerr's fit diagnostics (stress, diagError, regionError) venn <- plotVenn(res_sets) attr(venn, "fit_diagnostics")# Example with gene sets data(gene_list) res_sets <- computeOverlaps(gene_list) # Basic plot plotVenn(res_sets) # Customize fills with transparency and custom colors plotVenn(res_sets, fills = list(fill = c("#FF6B6B", "#4ECDC4", "#45B7D1"), alpha = 0.6)) # Customize edges plotVenn(res_sets, edges = list(col = "darkgray", lwd = 2, lty = 2)) # Customize labels plotVenn(res_sets, labels = list(col = "white", font = 2, fontsize = 14)) # Show both counts and percentages plotVenn(res_sets, quantities = list(type = c("counts", "percent"), col = "black", fontsize = 10)) # Add a title plotVenn(res_sets, main = list(label = "Gene Set Overlaps", col = "navy", fontsize = 16, font = 2)) # Transparent fills with colored borders only plotVenn(res_sets, fills = "transparent", edges = list(col = c("red", "blue", "green"), lwd = 3)) # Custom legend plotVenn(res_sets, legend = list(side = "bottom", labels = c("Treatment A", "Treatment B", "Control"), fontsize = 12)) # Inspect eulerr's fit diagnostics (stress, diagError, regionError) venn <- plotVenn(res_sets) attr(venn, "fit_diagnostics")
Redraws the Venn diagram produced by plotVenn, shaded by the
signed error of each region, so that the regions the diagram gets wrong can
be read off the picture rather than inferred from a single summary
statistic. This is a thin wrapper around error_plot.
plotVennError(venn, ...)plotVennError(venn, ...)
venn |
A plot returned by |
... |
Additional arguments passed to |
Where diagError reports how far off the worst region is, this plot shows
which regions are off and in which direction, with each region's
regionError printed inside it. Use it when diagError exceeds 1e-6.
The plot returned by error_plot, a gTree
that can be drawn, arranged with other grobs, or written out with
saveViz.
plotVenn for the diagram itself and its fit
diagnostics, plotUpSet for a representation that does not
approximate any count by an area.
data(gene_list) res_sets <- computeOverlaps(gene_list) # Where does the diagram misrepresent the counts? venn <- plotVenn(res_sets) plotVennError(venn)data(gene_list) res_sets <- computeOverlaps(gene_list) # Where does the diagram misrepresent the counts? venn <- plotVenn(res_sets) plotVennError(venn)
This function saves a visualization object to a file in the specified
format and directory. It supports visualizations generated by
plotVenn(), plotUpSet(), ggplot2, or any other plot object that
can be rendered using print() inside a graphics device. Optionally,
the current date (stored in the today variable) can be prepended to
the filename.
saveViz( viz, output_dir = ".", output_file = "figure_gVenn", format = "pdf", with_date = TRUE, width = 5, height = 5, resolution = 300, bg = "white", verbose = TRUE )saveViz( viz, output_dir = ".", output_file = "figure_gVenn", format = "pdf", with_date = TRUE, width = 5, height = 5, resolution = 300, bg = "white", verbose = TRUE )
viz |
A visualization object typically created by either
|
output_dir |
A string specifying the output directory. Defaults
to |
output_file |
A string specifying the base filename (without
extension). Defaults to |
format |
Output format. One of |
with_date |
Logical (default |
width |
Width of the output file in inches. Default is 5. |
height |
Height of the output file in inches. Default is 5. |
resolution |
Resolution in DPI (only used for PNG). Default is 300. |
bg |
Background color for the plot. Default is |
verbose |
Logical. If |
The visualization is saved to a file on disk. Invisibly returns the full path to the saved file.
# Example with a built-in set dataset data(gene_list) ov_sets <- computeOverlaps(gene_list) venn_plot <- plotVenn(ov_sets) saveViz(venn_plot, output_dir = tempdir(), output_file = "venn_sets") # Example with a built-in genomic dataset data(a549_chipseq_peaks) ov_genomic <- computeOverlaps(a549_chipseq_peaks) upset_plot <- plotUpSet(ov_genomic) saveViz(upset_plot, output_dir = tempdir(), output_file = "upset_genomic") # Save as PNG instead of PDF saveViz(upset_plot, format = "png", output_dir = tempdir(), output_file = "upset_example") # Save as SVG saveViz(venn_plot, format = "svg", output_dir = tempdir(), output_file = "venn_example") # Save with transparent background saveViz(venn_plot, format = "png", bg = "transparent", output_dir = tempdir(), output_file = "venn_transparent")# Example with a built-in set dataset data(gene_list) ov_sets <- computeOverlaps(gene_list) venn_plot <- plotVenn(ov_sets) saveViz(venn_plot, output_dir = tempdir(), output_file = "venn_sets") # Example with a built-in genomic dataset data(a549_chipseq_peaks) ov_genomic <- computeOverlaps(a549_chipseq_peaks) upset_plot <- plotUpSet(ov_genomic) saveViz(upset_plot, output_dir = tempdir(), output_file = "upset_genomic") # Save as PNG instead of PDF saveViz(upset_plot, format = "png", output_dir = tempdir(), output_file = "upset_example") # Save as SVG saveViz(venn_plot, format = "svg", output_dir = tempdir(), output_file = "venn_example") # Save with transparent background saveViz(venn_plot, format = "png", bg = "transparent", output_dir = tempdir(), output_file = "venn_transparent")
This variable stores the current date (in "yyyymmdd" format) at the time the
package is loaded. It is useful for reproducible filenames (e.g., in
saveViz()), and is automatically set when the package is attached.
todaytoday
A character string (e.g., "20250624").
# Print the date stored at package load library(gVenn) today # Use it in a filename paste0("venn_plot_", today, ".pdf")# Print the date stored at package load library(gVenn) today # Use it in a filename paste0("venn_plot_", today, ".pdf")