Gene GRangesList to ggplot2 grob

Gene GRangesList to ggplot2 grob

gene2gg(
  gene = NULL,
  tx = NULL,
  flatExonsByGene = NULL,
  flatExonsByTx = NULL,
  geneColor = "dodgerblue",
  labelExons = TRUE,
  exonLabelAngle = 90,
  exonLabelSize = 8,
  geneSymbolColname = "gene_name",
  newValues = list(feature_type = "gap", subclass = "gap", gene_nameExon = "gap"),
  gene_order = c("first", "last"),
  return_type = c("grob", "df"),
  ref2c = NULL,
  hjust = -0.2,
  vjust = 0.5,
  direction = c("both", "x", "y"),
  compressGaps = TRUE,
  tx2geneDF = NULL,
  label_coords = NULL,
  verbose = FALSE,
  ...
)

Arguments

gene	character string of the gene to plot, compared with names(flatExonsByGene) and values(flatExonsByTx)$gene_name.
tx	character vector of the transcripts to plot, useful when specifying specific transcripts. Values are matched with names(flatExonsByTx).
flatExonsByGene, flatExonsByTx	GRangesList objects, named by "gene_name" or "transcript_id" respectively, containing disjoint (non-overlapping) exons within each GRangesList element. The data is expected to be in the form provided by flattenExonsBy().
geneColor	character color used as the base color for exons, where the color is varied for each feature type or subclass.
labelExons	logical indicating whether to print text labels beneath each exon, using the values in colname "gene_nameExon". Typically the gene and transcripts are named using consistent names, in which case one exon label is placed at the bottom of the lowest transcript for each unique exon label.
exonLabelAngle	numeric angle in degrees (0 to 360) indicating how to rotate exon labels, where 90 is vertical, and 0 is horizontal.
exonLabelSize	numeric value or unit object from grid::unit(). Numeric values are assumed to have unit "pt" which refers to font point size. Used to size exon labels when labelExons=TRUE.
newValues	argument passed to addGRLgaps() to fill column values for newly created gap entries. It is useful to have feature_type="gap" so gaps have a different value than exons. It is also useful to have subclass="gap" when there are "cds" and "noncds" entries in the provided flatExonsByGene data.
gene_order	character value indicating whether the flattened gene model should be plotted "first" above the transcript exon models, or "last" and below the transcript exon models.
return_type	character value indicating whether to return the ggplot graphic object "grob", or the data.frame "df" used to create the ggplot object.
ref2c	list output from make_ref2compressed() which contains among other things, the trans_grc data of class "trans" used in ggplot2::coord_trans() or ggplot2::scale_x_continuous().
hjust, vjust	numeric value to position exon labels passed to ggrepel::geom_text_repel().
direction	argument passed to ggrepel::geom_text_repel() to restrict placement of labels to one axis direction.
compressGaps	logical indicating whether to compress gaps between exons. When ref2c is supplied, this argument is ignored and the supplied ref2c is used directly.
tx2geneDF	data.frame or NULL, optionally used to help identify matching transcripts for the requested gene value, used when "gene_name" is not present in values(flatExonsByTx).
label_coords	numeric vector length 2, optional range of genomic coordinates to restrict labels, so labels are not arranged by ggrepel::geom_text_repel() even when coord_cartesian() is used to zoom into a specific x-axis range.
verbose	logical indicating whether to print verbose output.
...	additional arguments are passed to relevant functions as needed, including make_ref2compressed().

Details

This function is intended to help plot gene and transcript exon models, and is a lightweight wrapper around grl2df().

It takes flatExonsByGene which is the output from flattenExonsBy(), and essentially plots the end result for review.

Alternatively, when return_type="df", the output is the data.frame used to produce the ggplot, which allows for more customization.

See also

Other jam plot functions: bgaPlotly3d(), factor2label(), grl2df(), jitter_norm(), plotSashimi(), prepareSashimi(), stackJunctions()

Other jam ggplot2 functions: geom_diagonal_wide_arc(), plotSashimi(), splicejam-extensions, to_basic.GeomShape()

Other splicejam core functions: exoncov2polygon(), grl2df(), make_ref2compressed(), plotSashimi(), prepareSashimi()

Examples

## Assume we start with flattened gene exons
data(test_exon_wide_gr);
test_flatExonsByGene <- GenomicRanges::split(test_exon_wide_gr,
   GenomicRanges::values(test_exon_wide_gr)[,"gene_name"]);

# The most basic plot of exons
gene2gg(gene="TestGene1", flatExonsByGene=test_flatExonsByGene);
#> Warning: package ‘ggplot2’ was built under R version 3.6.2
#> Warning: package ‘ggforce’ was built under R version 3.6.2
#> Warning: failed to set names on the unlisted CompressedRleList object
#> Warning: package ‘data.table’ was built under R version 3.6.2

# You can be fancy and number the exons
test_flatExonsByGene <- assignGRLexonNames(test_flatExonsByGene,
   geneSymbolColname="gene_name");
gene2gg(gene="TestGene1", flatExonsByGene=test_flatExonsByGene);
#> Warning: failed to set names on the unlisted CompressedRleList object

# Or the exon labels can be hidden
gene2gg(gene="TestGene1", flatExonsByGene=test_flatExonsByGene, labelExons=FALSE)
#> Warning: failed to set names on the unlisted CompressedRleList object

if (1 == 2) {
   ## Do not run automated examples until sample data is available

ggGria1 <- gene2gg("Gria1",
   flatExonsByGene=flatExonsByGeneCds);

## if transcript exons are available
ggGria1 <- gene2gg("Gria1",
   flatExonsByGene=flatExonsByGene,
   flatExonsByTx=flatExonsByTx);

}