gggenes: Draw Gene Arrow Maps in 'ggplot2'

Description

A 'ggplot2' extension for drawing gene arrow maps.

Author(s)

Maintainer: David Wilkins david@wilkox.org

Other contributors:

• Zachary Kurtz zdkurtz@gmail.com [contributor]

See Also

Useful links:

• https://wilkox.org/gggenes/

• Report bugs at https://github.com/wilkox/gggenes/issues/

A set of example dummy alignment genes.

Description

Dummy genes, similar to those generated with make_alignment_dummies(), for example purposes only.

Usage

example_dummies

Format

A data frame with eight rows and three variables:

molecule

the genome

start

the start position of the dummy

end

the end position of the dummy

gene

the name of the dummy gene

A set of example genetic features.

Description

Genetic features for example purposes only.

Usage

example_features

Format

A data frame with 23 rows and five variables:

molecule

the genome

name

the name of the feature

type

the type of the feature

position

the position of the feature

forward

is the feature oriented, and if so in the forward direction?

A set of example genes.

Description

Genes for example purposes only.

Usage

example_genes

example_subgenes

Format

A data frame with 72 rows and six variables:

molecule

the genome

gene

the name of the gene

start

the start position of the gene

end

the end position of the gene

strand

the strand of the gene

orientation

the orientation of the gene

example_subgenes (143 rows) also contains:

subgene

the name of the subgene

from

the start position of the subgene segment

to

the end position of the subgene segment

An object of class data.frame with 143 rows and 9 columns.

A 'ggplot2' geom to draw point genetic features

Description

geom_feature() draws lines to indicate the positions of point genetic features, for example restriction sites, origins of replication or transcription start sites.

Usage

geom_feature(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE,
  feature_height = unit(3, "mm"),
  feature_width = unit(3, "mm"),
  arrowhead_width = unit(2, "mm"),
  ...
)

Arguments

Details

Features are drawn as vertical lines extending from the horizontal line representing the molecule. The position of the feature is expressed with the x aesthetic. Optionally, the forward aesthetic can be used to specific an orientation for the feature (e.g. the direction of transcription), in which case an angled arrowhead will be added. The forward aesthetic assumes that the x-axis is oriented in the normal direction, i.e. increasing from left to right; if it is not, the values in forward will need to be inverted manually.

Aesthetics

• x (required; position of the feature)

• y (required; molecule)

• forward (optional; if TRUE, or a value coercible to TRUE, the feature will be drawn with an arrowhead pointing right, if FALSE, pointing left, if NA, the feature will be drawn as a vertical line)

• alpha

• colour

• linetype

• size

See Also

geom_feature_label()

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
                                            y = molecule, fill = gene)) +
  geom_gene_arrow() +
  geom_feature(data = example_features, ggplot2::aes(x = position, y = molecule, 
                                                     forward = forward)) +
  ggplot2::facet_wrap(~ molecule, scales = "free")

A 'ggplot2' geom to add text labels to point genetic features

Description

geom_feature_label() adds text labels to features drawn with geom_feature().

Usage

geom_feature_label(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = FALSE,
  feature_height = unit(4, "mm"),
  label_height = unit(3, "mm"),
  ...
)

Arguments

Details

Standard 'ggplot2' aesthetics for text are supported (see Aesthetics).

Aesthetics

• x (required; position of the feature)

• y (required; molecule)

• label (required; the label text)

• forward (optional; will draw text in the appropriate location for features with angled arrowheads)

• colour

• size

• alpha

• family

• fontface

• angle

See Also

geom_feature()

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
                                            y = molecule, fill = gene)) +
  geom_gene_arrow() +
  geom_feature(data = example_features, ggplot2::aes(x = position, y = molecule, 
                                                     forward = forward)) +
  geom_feature_label(data = example_features,
                     ggplot2::aes(x = position, y = molecule, label = name, 
                                  forward = forward)) + 
  ggplot2::facet_wrap(~ molecule, scales = "free")

A 'ggplot2' geom to draw genes as arrows

Description

geom_gene_arrow() draws genes as arrows, allowing gene maps to be drawn.

Usage

geom_gene_arrow(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  arrowhead_width = grid::unit(4, "mm"),
  arrowhead_height = grid::unit(4, "mm"),
  arrow_body_height = grid::unit(3, "mm"),
  ...
)

Arguments

Details

This geom draws genes as arrows along a horizontal line representing the molecule. The start and end locations of the gene are expressed with the xmin and xmax aesthetics, while the molecule can be specified with the y aesthetic. Optionally, an additional forward aesthetic can be used to reverse the orientation of some or all genes from that implied by xmin and xmax.

Unless the plot is faceted with a free x scale, all the molecules will share a common x axis. This means that if the locations are very different across different molecules, the genes might appear very small and squished together with a lot of unnecessary empty space. To get around this, either facet the plot with scales = "free_x", or normalise the gene locations if their exact locations are not important.

See make_alignment_dummies() for a method to align genes between molecules.

Aesthetics

• xmin,xmax (start and end of the gene; will be used to determine gene orientation)

• y (molecule)

• forward (if any value that is not TRUE, or coercible to TRUE, the gene arrow will be drawn in the opposite direction to that determined by xmin and xmax)

• alpha

• colour

• fill

• linetype

• size

See Also

theme_genes(), make_alignment_dummies(), geom_gene_label()

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
                                            y = molecule, fill = gene)) +
geom_gene_arrow() +
ggplot2::facet_wrap(~ molecule, scales = "free")

A 'ggplot2' geom to add text labels to gene arrows

Description

geom_gene_label() can be used to add a text label to genes drawn with geom_gene_arrow().

Usage

geom_gene_label(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(0.1, "lines"),
  align = "centre",
  min.size = 4,
  grow = F,
  reflow = F,
  height = grid::unit(3, "mm"),
  ...
)

Arguments

Details

geom_gene_label() uses the 'ggfittext' package to fit text to genes. All text drawing options available in ggfittext::geom_fit_text() (growing, reflowing, etc.) are also available here. For full details on how these options work, see the documentation for ggfittext::geom_fit_text().

Standard 'ggplot2' aesthetics for text are supported (see Aesthetics).

Aesthetics

• xmin,xmax (start and end of the gene; required)

• y (molecule; required)

• label (the label text; required)

• colour

• size

• alpha

• family

• fontface

• angle

See Also

geom_gene_arrow

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
  y = molecule, fill = gene, label = gene)) +
  geom_gene_arrow() +
  geom_gene_label() +
  ggplot2::facet_wrap(~ molecule, ncol = 1, scales = "free") +
  theme_genes()

A 'ggplot2' geom to draw subgene segments of gene arrows

Description

geom_subgene_arrow() draws subgenes segments within gene arrows drawn with geom_gene_arrow().

Usage

geom_subgene_arrow(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  arrowhead_width = grid::unit(4, "mm"),
  arrowhead_height = grid::unit(4, "mm"),
  arrow_body_height = grid::unit(3, "mm"),
  ...
)

Arguments

Details

The start and end locations of the subgene are given with the xsubmin and xsubmax aesthetics. geom_subgene_arrow() requires some information about the 'parent' gene, provided with the same aesthetics used for geom_gene_arrow(): start and end locations of the 'parent' gene with the xmin and xmax aesthetics, the molecule with the y aesthetic, and optionally the direction with the forward aesthetic. If the geometry of the parent gene has been changed with arrowhead_width, arrowhead_height or arrow_body_height, identical parameters should be given to geom_subgene_arrow().

Aesthetics

• xmin,xmax (start and end of the gene; will be used to determine gene orientation)

• xsubmin,xsubmax (start and end of subgene segment). Should be consistent with xmin/xmax

• y (molecule)

• forward (if FALSE, or coercible to FALSE, the gene arrow will be drawn in the opposite direction to that determined by xmin and xmax)

• alpha

• colour

• fill

• linetype

• size

See Also

geom_gene_arrow(), geom_subgene_label()

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
                                            y = molecule)) +
geom_gene_arrow() +
geom_subgene_arrow(data = example_subgenes,
      ggplot2::aes(xmin = start, xmax = end, xsubmin = from, xsubmax = to,
                   y = molecule, fill = gene)) +
ggplot2::facet_wrap(~ molecule, scales = "free")

A 'ggplot2' geom to add text labels to subgenes

Description

geom_subgene_label() can be used to add a text label to subgenes drawn with geom_subgene_arrow().

Usage

geom_subgene_label(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(0.1, "lines"),
  align = "centre",
  min.size = 4,
  grow = F,
  reflow = F,
  height = grid::unit(3, "mm"),
  ...
)

Arguments

Details

geom_subgene_label() uses the 'ggfittext' package to fit text to genes. All text drawing options available in ggfittext::geom_fit_text() (growing, reflowing, etc.) are also available here. For full details on how these options work, see the documentation for ggfittext::geom_fit_text().

Standard 'ggplot2' aesthetics for text are supported (see Aesthetics.)

Aesthetics

• xsubmin,xsubmax (start and end of the subgene; required)

• y (molecule; required)

• colour

• size

• alpha

• family

• fontface

• angle

Prepare dummy data to visually align a single gene across faceted molecules

Description

make_alignment_dummies() helps you to visually align genes across molecules that have been faceted with a free x scale. The output of this function is a data frame of dummy genes. If these dummy genes are added to a 'ggplot2' plot with ggplot::geom_blank(), they will extend the x axis range in such a way that the start or end of a selected gene is visually aligned across the facets.

Usage

make_alignment_dummies(data, mapping, on, side = "left")

Arguments

Examples

dummies <- make_alignment_dummies(example_genes, ggplot2::aes(xmin = start,
  xmax = end, y = molecule, id = gene), on = "genE")

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
    y = molecule, fill = gene)) +
  geom_gene_arrow() +
  ggplot2::geom_blank(data = dummies) +
  ggplot2::facet_wrap(~ molecule, scales = "free", ncol = 1)

A 'ggplot2' theme for drawing gene maps

Description

This theme removes extraneous plot elements for drawing an 'arrows-on-a-string' style gene map in 'ggplot2'.theme_genes_flipped() is like theme_genes(), but for flipped coordinates.

Usage

theme_genes()

theme_genes_flipped()

Details

This theme removes strip text (the text that labels facets when you use ggplot2::facet_wrap() or ggplot::facet_grid()). This makes it easier to draw molecules on different x scales by setting the y aesthetic to the molecule, then faceting with facet_grid( ~ molecule, scales = "free").

See Also

geom_gene_arrow()

Examples

ggplot2::ggplot(example_genes, ggplot2::aes(xmin = start, xmax = end,
                                            y = molecule, fill = gene)) +
geom_gene_arrow() +
ggplot2::facet_wrap(~ molecule, scales = "free") +
theme_genes()