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); }