Skip to contents

Geom for gene model tracks

Source: R/geom_gene.R
geom_gene.Rd

geom_gene provides a flexible way to visualize gene models in genomic coordinates. It can display exons, introns, and strand information, with automatic handling of gene structure and strand separation.

Usage

geom_gene(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  height = NULL,
  exon_height = 0.4,
  intron_width = 0.4,
  arrow_length = 0,
  arrow_type = "open",
  exon_color = "gray50",
  exon_fill = "gray50",
  intron_color = "gray50",
  clip_to_region = NULL,
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by aes().

data

The data to be displayed in this layer.

stat

The statistical transformation to use on the data.

position

Position adjustment, either as a string, or the result of a call to a position adjustment function.

...

Other arguments passed on to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like color = "red" or size = 3.

height

Height of gene tracks for discrete y-axis. If NULL (default), uses the exon_height parameter to determine track height.

exon_height

Height of exons relative to track height. A numeric value between 0 and 1. Default: 0.75

intron_width

Line width for intron segments. Default: 0.4

arrow_length

Length of directional arrows in inches. Set to 0 to disable arrows. Default: 0

arrow_type

Type of arrow head. See grid::arrow() for options. Default: "open"

exon_color

Default border color for exons. Can be overridden by color or colour aesthetics. Default: "gray50"

exon_fill

Default fill color for exons. Can be overridden by fill aesthetic. Default: "gray50"

intron_color

Default color for intron lines. Can be overridden by color or colour aesthetics. Default: "gray50"

clip_to_region

Optional numeric vector of length 2 specifying the genomic region boundaries (start, end) to clip features to. Features partially overlapping the region will be trimmed. Default: NULL

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

Logical. Should this layer be included in the legends? NA (the default) includes the layer in the legends if any aesthetics are mapped.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them.

Value

A ggplot2 layer that can be added to a plot.

Details

The GeomGene ggproto object implements the core functionality for rendering gene models. It handles both the data processing and the actual drawing of gene features.

Key features:

  • Automatically processes input data to handle different input formats

  • Manages the coordinate transformation for proper genomic scaling

  • Handles the rendering of both exons and introns with appropriate styling

  • Supports strand-specific visualization with optional directional arrows

  • Implements proper handling of missing values and edge cases

Aesthetics

The following aesthetics are required:

  • xstart: Start position of the feature (genomic coordinate)

  • xend: End position of the feature (genomic coordinate)

  • type: Type of feature ("gene" or "exon")

Optional aesthetics:

  • color: Color for both exons (fill) and introns (color)

  • fill: Fill color for exons (overrides color for fill if specified)

  • strand: Strand information ("+" or "-")

  • y: Optional grouping variable (overrides automatic strand-based grouping)

The following aesthetics are used by the geom:

  • xstart, xend: Start and end genomic coordinates

  • type: Feature type ("gene" or "exon")

  • strand: Strand information ("+" or "-")

  • y: Optional y-axis grouping

  • colour: Color for both exons (fill) and introns (line)

  • fill: Fill color for exons (overrides colour for fill)

  • linewidth: Width of intron lines

  • alpha: Transparency (0-1)

  • linetype: Line type for introns

  • size: Size of points (unused, for compatibility)

Data Format

The function expects a data frame with the following columns:

  • Required:

    • xstart, xend: Genomic coordinates of features

    • type: Either "gene" (for introns) or "exon"

  • Optional:

    • strand: "+" or "-" for forward/reverse strand

    • exon_start, exon_end: For long-format exon data

    • Any additional columns for aesthetics (e.g., gene names, biotypes)

Features

  • Automatic strand separation with customizable track heights

  • Support for both wide and long data formats

  • Customizable appearance of exons and introns

  • Optional directional arrows for strand indication

  • Integration with ggplot2's theming system

Methods

The ggproto object implements the following methods:

  • setup_data(): Processes input data and sets up y-axis positions

  • setup_params(): Configures drawing parameters including arrow settings

  • draw_panel(): Main drawing method that renders the gene models

  • draw_key(): Defines how to draw the legend key

Examples

if (FALSE) { # \dontrun{
library(ggplot2)

# Example 1: Basic usage with automatic strand separation
ggplot(gene_data) +
  geom_gene(aes(
    xstart = start, xend = end,
    type = feature, color = gene_name
  ))

# Example 2: Custom y-axis grouping by biotype
ggplot(gene_data) +
  geom_gene(aes(
    xstart = start, xend = end,
    type = feature, y = biotype,
    fill = gene_name
  ))

# Example 3: Styling options
ggplot(gene_data) +
  geom_gene(
    aes(xstart = start, xend = end, type = feature),
    exon_fill = "steelblue",
    exon_color = "navy",
    intron_color = "darkblue",
    intron_width = 0.6,
    exon_height = 0.8,
    arrow_length = unit(0.05, "inches")
  )
} # }