Package 'gggenomes'

Description

Add different types of tracks

Usage

add_feats(x, ...)

add_links(x, ..., .adjacent_only = TRUE)

add_subfeats(x, ..., .track_id = "genes", .transform = "aa2nuc")

add_sublinks(x, ..., .track_id = "genes", .transform = "aa2nuc")

add_clusters(x, ..., .track_id = "genes")

Arguments

Value

gggenomes object with added features

Functions

• add_feats(): Add feature annotations to sequences

• add_links(): Add links connecting sequences, such as whole-genome alignment data.

• add_subfeats(): Add features of features, such as gene/protein domains, blast hits to genes/proteins, etc.

• add_sublinks(): Add links that connect features, such as protein-protein alignments connecting genes.

• add_clusters(): Add gene clusters or other feature groups. Takes a data.frame with at least two required columns cluster_id and feat_id. The data.frame is converted to a link track connecting features belonging to the same cluster over their entire length. Additionally, the data.frame is joined to the parent feature track, adding cluster_id and all additional columns to the parent table.

Examples

# Add some repeat annotations
gggenomes(seqs = emale_seqs) %>%
  add_feats(repeats = emale_tirs) +
  geom_seq() + geom_feat()

# Add all-vs-all whole-genome alignments
gggenomes(seqs = emale_seqs) %>%
  add_links(links = emale_ava) +
  geom_seq() + geom_link()

# Add domains to genes
genes <- tibble::tibble(seq_id = "A", start = 100, end = 200, feat_id = "gene1")
domains <- tibble::tibble(feat_id = "gene1", start = 40, end = 80)
gggenomes(genes = genes) %>% add_subfeats(domains, .transform = "none") +
  geom_gene() + geom_feat()

# Add protein-protein alignments
gggenomes(emale_genes) %>%
  add_sublinks(emale_prot_ava) +
  geom_gene() + geom_link()

# add clusters
gggenomes(emale_genes, emale_seqs) %>%
  add_clusters(emale_cogs) %>%
  sync() + # works because clusters
  geom_link() + # become links
  geom_seq() +
  # works because cluster info is joined to gene track
  geom_gene(aes(fill = ifelse(is.na(cluster_id), NA,
    stringr::str_glue("{cluster_id} [{cluster_size}]")
  ))) +
  scale_fill_discrete("COGs")

Description

Add seqs

Usage

add_seqs(x, seqs, ...)

Arguments

Value

a gggenomes or gggenomes_layout object with added seqs

Description

Check strand

Usage

check_strand(strand, na)

Arguments

Value

strand vector with unknown values replaced by na

Description

Combine strands

Usage

combine_strands(strand, strand2, ...)

Arguments

Value

the combined strand

Description

For seamless reading of different file formats, gggenomes uses a mapping of known formats to associated file extensions and contexts in which the different formats can be read. The notion of context allows one to read different information from the same format/extension. For example, a gbk file holds both feature and sequence information. If read in "feats" context read_feats("*.gbk") it will return a feature table, if read in "seqs" context read_seqs("*.gbk"), a sequence index.

Usage

def_formats(
  file = NULL,
  ext = NULL,
  context = NULL,
  parser = NULL,
  allow_na = FALSE
)

Arguments

Value

dictionarish vector of file formats with recognized extensions as names

Defined formats, extensions, contexts, and parsers

      format                           ext            context                                              parser
1  ambigious                 txt, tsv, csv                 NA                                      read_ambigious
2      fasta fa, fas, fasta, ffn, fna, faa               seqs                                        read_seq_len
3        fai                           fai               seqs                                            read_fai
4       gff3          gff, gff3, gff2, gtf        feats, seqs                             read_gff3, read_seq_len
5        gbk           gbk, gb, gbff, gpff        feats, seqs                              read_gbk, read_seq_len
6        bed                           bed              feats                                            read_bed
7      blast                    m8, o6, o7       feats, links                              read_blast, read_blast
8        paf                           paf       feats, links                                  read_paf, read_paf
9      alitv                          json feats, seqs, links read_alitv_genes, read_alitv_seqs, read_alitv_links
10       vcf                           vcf              feats                                            read_vcf

Examples

# vector of defined zip formats and recognized extensions as names
# format of file
def_formats("foo.fa")

# formats associated with each extension
def_formats(ext = c("fa", "gff"))

# all formats/extensions that can be read in seqs context; includes formats
# that are defined for context=NA, i.e. that can be read in any context.
def_formats(context = "seqs")

Description

Intended to be used in readr::read_tsv()-like functions that accept a col_names and a col_types argument.

Usage

def_names(format)

def_types(format)

Arguments

Value

a vector with default column names for the given format

a vector with default column types for the given format

Functions

• def_names(): default column names for defined formats

• def_types(): default column types for defined formats

Defined formats, column types and names

  gff3       ccciicccc       seq_id,source,type,start,end,score,strand,phase,attributes
  paf        ciiicciiiiid    seq_id,length,start,end,strand,seq_id2,length2,start2,end2,map_match,map_length,map_quality
  blast      ccdiiiiiiidd    seq_id,seq_id2,pident,length,mismatch,gapopen,start,end,start2,end2,evalue,bitscore
  bed        ciicdc          seq_id,start,end,name,score,strand
  fai        ci---           seq_id,seq_desc,length
  seq_len    cci             seq_id,seq_desc,length
  vcf        cicccdccc       seq_id,start,feat_id,ref,alt,qual,filter,info,format

Examples

# read a blast-tabular file with read_tsv
readr::read_tsv(ex("emales/emales-prot-ava.o6"), col_names = def_names("blast"))

Description

Drop feature layout

Usage

drop_feat_layout(x, keep = "strand")

Arguments

Value

feat_layout without unwanted features

Description

Drop a genome layout

Usage

drop_layout(data, ...)

Arguments

Value

gggenomes object without layout

Description

Drop a link layout

Usage

drop_link_layout(x, keep = "strand")

Arguments

Value

link_layout without unwanted features

Description

Drop a seq layout

Usage

drop_seq_layout(x, keep = "strand")

Arguments

Value

seq_layout without unwanted features

Description

One row per alignment block. Alignments were computed with minimap2.

Usage

emale_ava

Format

A data frame with 125 rows and 23 columns

file_id

name of the file the data was read from

seq_id

identifier of the sequence the feature appears on

length

length of the sequence

start

start of the feature on the sequence

end

end of the feature on the sequence

strand

orientation of the feature relative to the sequence (+ or -)

seq_id2

identifier of the sequence the feature appears on

length2

length of the sequence

start2

start of the feature on the sequence

end2

end of the feature on the sequence

map_match, map_length, map_quality, NM, ms, AS, nn, tp, cm, s1, de, rl, cg

see https://github.com/lh3/miniasm/blob/master/PAF.md for additional columns

Source

• Derived & bundled data: ex("emales/emales.paf")

Description

One row per feature. Clusters are based on manual curation.

Usage

emale_cogs

Format

A data frame with 48 rows and 3 columns

cluster_id

identifier of the cluster

feat_id

identifer of the gene

cluster_size

number of features in the cluster

Source

• Derived & bundled data: ex("emales/emales-cogs.tsv")

Description

One row per 50 bp window.

Usage

emale_gc

Format

A data frame with 2856 rows and 6 columns

file_id

name of the file the data was read from

seq_id

identifier of the sequence the feature appears on

start

start of the feature on the sequence

end

end of the feature on the sequence

name

name of the feature

score

relative GC-content of the window

Source

• Derived & bundled data: ex("emales/emales-gc.bed")

Description

A data set containing gene feature annotations for 6 endogenous virophages found in the genomes of the marine protist Cafeteria burkhardae.

Usage

emale_genes

Format

A data frame with 143 rows and 17 columns

file_id

name of the file the data was read from

seq_id

identifier of the sequence the feature appears on

start

start of the feature on the sequence

end

end of the feature on the sequence

strand

reading orientation relative to sequence (+ or -)

type

feature type (CDS, mRNA, gene, ...)

feat_id

unique identifier of the feature

introns

a list column with internal intron start/end positions

parent_ids

a list column with parent IDs - feat_id's of parent features

source

source of the annotation

score

score of the annotation

phase

For "CDS" features indicates where the next codon begins relative to the 5' start

width

width of the feature

gc_content

relative GC-content of the feature

name

name of the feature

Note

geom_id

an identifier telling the which features should be plotted as on items (usually CDS and mRNA of same gene)

Source

• Publication: doi:10.1101/2020.11.30.404863

• Raw data: https://github.com/thackl/cb-emales

• Derived & bundled data: ex("emales/emales.gff")

Description

Integrated Ngaro retrotransposons of 6 EMALE genomes

Usage

emale_ngaros

Format

A data frame with 3 rows and 14 columns

file_id

name of the file the data was read from

seq_id

identifier of the sequence the feature appears on

start

start of the feature on the sequence

end

end of the feature on the sequence

strand

orientation of the feature relative to the sequence (+ or -)

type

feature type (CDS, mRNA, gene, ...)

feat_id

unique identifier of the feature

introns

a list column with internal intron start/end positions

parent_ids

a list column with parent IDs - feat_id's of parent features

source

source of the annotation

score

score of the annotation

phase

For "CDS" features indicates where the next codon begins relative to the 5' start

name

name of the feature

geom_id

an identifier telling the which features should be plotted as on items (usually CDS and mRNA of same gene)

Source

• Publication: doi:10.1101/2020.11.30.404863

• Raw data: https://github.com/thackl/cb-emales

• Derived & bundled data: ex("emales/emales-ngaros.gff")

Description

One row per alignment. Alignments were computed with mmseqs2 (blast-like).

Usage

emale_prot_ava

Format

A data frame with 827 rows and 13 columns

file_id

name of the file the data was read from

feat_id

identifier of the first feature in the alignment

feat_id2

identifier of the second feature in the alignment

pident, length, mismatch, gapopen, start, end, start2, end2, evalue, bitscore

see https://github.com/seqan/lambda/wiki/BLAST-Output-Formats for BLAST-tabular format columns

Source

• Derived & bundled data: ex("emales/emales-prot-ava.o6")

Description

A data set containing the sequence information on 6 endogenous virophages found in the genomes of the marine protist Cafeteria burkhardae.

Usage

emale_seqs

Format

A data frame with 6 rows and 4 columns

file_id

name of the file the data was read from

seq_id

sequence identifier

seq_desc

sequence description

length

length of the sequence

Source

• Publication: doi:10.1101/2020.11.30.404863

• Raw data: https://github.com/thackl/cb-emales

• Derived & bundled data: ex("emales/emales.fna")

Description

Terminal inverted repeats of 6 EMALE genomes

Usage

emale_tirs

Format

A data frame with 3 rows and 14 columns

file_id

name of the file the data was read from

seq_id

identifier of the sequence the feature appears on

start

start of the feature on the sequence

end

end of the feature on the sequence

strand

reading orientation relative to sequence (+ or -)

type

feature type (CDS, mRNA, gene, ...)

feat_id

unique identifier of the feature

introns

a list column with internal intron start/end positions

parent_ids

a list column with parent IDs - feat_id's of parent features

source

source of the annotation

score

score of the annotation

phase

For "CDS" features indicates where the next codon begins relative to the 5' start

name

name of the feature

width

end-start+1

geom_id

an identifier telling the which features should be plotted as on items (usually CDS and mRNA of same gene)

Source

• Publication: doi:10.1101/2020.11.30.404863

• Raw data: https://github.com/thackl/cb-emales

• Derived & bundled data: ex("emales/emales-tirs.gff")

Description

Get path to gggenomes example files

Usage

ex(file = NULL)

Arguments

Value

path to example file

Description

Track selection works like dplyr::pull() and supports unquoted ids and positional arguments. ... can be used to subset the data in dplyr::filter() fashion. pull-prefixed variants return the specified track from a gggenome object. Unprefixed variants work inside ⁠geom_*⁠ calls.

Usage

feats(.track_id = 1, ..., .ignore = "genes", .geneify = FALSE)

feats0(.track_id = 1, ..., .ignore = NA, .geneify = FALSE)

genes(..., .gene_types = c("CDS", "mRNA", "tRNA", "tmRNA", "ncRNA", "rRNA"))

links(.track_id = 1, ..., .ignore = NULL, .adjacent_only = NULL)

seqs(...)

bins(..., .group = vars())

track(.track_id = 1, ..., .track_type = NULL, .ignore = NULL)

pull_feats(.x, .track_id = 1, ..., .ignore = "genes", .geneify = FALSE)

pull_genes(
  .x,
  ...,
  .gene_types = c("CDS", "mRNA", "tRNA", "tmRNA", "ncRNA", "rRNA")
)

pull_links(.x, .track_id = 1, ..., .ignore = NULL, .adjacent_only = NULL)

pull_seqs(.x, ...)

pull_bins(.x, ..., .group = vars())

## S3 method for class 'gggenomes_layout'
pull_bins(.x, ..., .group = vars())

pull_track(.x, .track_id = 1, ..., .track_type = NULL, .ignore = NULL)

Arguments

Value

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

A function that pulls the specified track from a gggenomes object.

Functions

• feats(): by default pulls out the first feat track not named "genes".

• feats0(): by default pulls out the first feat track.

• genes(): pulls out the first feat track (genes), filtering for records with type=="CDS", and adding a dummy gene_id column if missing to play nice with multi-exon geoms.

• links(): by default pulls out the first link track.

• seqs(): pulls out the seqs track (there is only one).

• bins(): pulls out a binwise summary table of the seqs data powering ⁠geom_bin_*()⁠ calls. The bin table is not a real track, but recomputed on-the-fly.

• track(): pulls from all tracks in order seqs, feats, links.

Examples

gg <- gggenomes(emale_genes, emale_seqs, emale_tirs, emale_ava)
gg %>% track_info() # info about track ids, positions and types

# get first feat track that isn't "genes" (all equivalent)
gg %>% pull_feats() # easiest
gg %>% pull_feats(feats) # by id
gg %>% pull_feats(1) # by position
gg %>% pull_feats(2, .ignore = NULL) # default .ignore="genes"

# get "seqs" track (always track #1)
gg %>% pull_seqs()

# plot integrated transposons and GC content for some viral genomes
gg <- gggenomes(seqs = emale_seqs, feats = list(emale_ngaros, GC = emale_gc))
gg + geom_seq() +
  geom_feat(color = "skyblue") + # defaults to data=feats()
  geom_line(aes(x, y + score - .6, group = y), data = feats(GC), color = "gray60")

Description

flip and flip_seqs reverse-complement specified bins or individual sequences and their features. sync automatically flips bins using a heuristic that maximizes the amount of forward strand links between neighboring bins.

Usage

flip(x, ..., .bin_track = seqs)

flip_seqs(x, ..., .bins = everything(), .seq_track = seqs, .bin_track = seqs)

sync(x, link_track = 1, min_support = 0)

Arguments

Details

For more details see the help vignette: vignette("flip", package = "gggenomes")

Value

a gggenomes object with flipped bins or sequences

Examples

library(patchwork)
p <- gggenomes(genes = emale_genes) +
  geom_seq(aes(color = strand), arrow = TRUE) +
  geom_link(aes(fill = strand)) +
  expand_limits(color = c("-")) +
  labs(caption = "not flipped")

# nothing flipped
p0 <- p %>% add_links(emale_ava)

# flip manually
p1 <- p %>%
  add_links(emale_ava) %>%
  flip(4:6) + labs(caption = "manually")

# flip automatically based on genome-genome links
p2 <- p %>%
  add_links(emale_ava) %>%
  sync() + labs(caption = "genome alignments")

# flip automatically based on protein-protein links
p3 <- p %>%
  add_sublinks(emale_prot_ava) %>%
  sync() + labs(caption = "protein alignments")

# flip automatically based on genes linked implicitly by belonging
# to the same clusters of orthologs (or any grouping of your choice)
p4 <- p %>%
  add_clusters(emale_cogs) %>%
  sync() + labs(caption = "shared orthologs")

p0 + p1 + p2 + p3 + p4 + plot_layout(nrow = 1, guides = "collect")

Description

Flip strand

Usage

flip_strand(strand, na = NA)

Arguments

Value

the strand flipped

Description

Show loci containing features of interest. Loci can either be provided as predefined regions directly (⁠loci=⁠), or are constructed automatically based on pre-selected features (via ...). Features within max_dist are greedily combined into the same locus. locate() adds these loci as new track so that they can be easily visualized. focus() extracts those loci from their parent sequences making them the new sequence set. These sequences will have their locus_id as their new seq_id.

Usage

focus(
  x,
  ...,
  .track_id = 2,
  .max_dist = 10000,
  .expand = 5000,
  .overhang = c("drop", "trim", "keep"),
  .locus_id = str_glue("{seq_id}_lc{row_number()}"),
  .locus_id_group = seq_id,
  .locus_bin = c("bin", "seq", "locus"),
  .locus_score = n(),
  .locus_filter = TRUE,
  .loci = NULL
)

locate(
  x,
  ...,
  .track_id = 2,
  .max_dist = 10000,
  .expand = 5000,
  .locus_id = str_glue("{seq_id}_lc{row_number()}"),
  .locus_id_group = .data$seq_id,
  .locus_bin = c("bin", "seq", "locus"),
  .locus_score = n(),
  .locus_filter = TRUE,
  .locus_track = "loci"
)

Arguments

Value

A gggenomes object focused on the desired loci

A gggenomes object with the new loci track added

Functions

• focus(): Identify regions of interest and zoom in on them

• locate(): Identify regions of interest and add them as new feature track

Examples

# Let's hunt some defense systems in marine SAGs
# read the genomes
s0 <- read_seqs(ex("gorg/gorg.fna.fai"))
s1 <- s0 %>%
  # strip trailing number from contigs to get bins
  dplyr::mutate(bin_id = stringr::str_remove(seq_id, "_\\d+$"))
# gene annotations from prokka
g0 <- read_feats(ex("gorg/gorg.gff.xz"))

# best hits to the PADS Arsenal database of prokaryotic defense-system genes
# $ mmseqs easy-search gorg.fna pads-arsenal-v1-prf gorg-pads-defense.o6 /tmp \
#     --greedy-best-hits
f0 <- read_feats(ex("gorg/gorg-pads-defense.o6"))
f1 <- f0 %>%
  # parser system/gene info
  tidyr::separate(seq_id2, into = c("seq_id2", "system", "gene"), sep = ",") %>%
  dplyr::filter(
    evalue < 1e-10, # get rid of some spurious hits
    # and let's focus just on a few systems for this example
    system %in% c("CRISPR-CAS", "DISARM", "GABIJA", "LAMASSU", "THOERIS")
  )

# plot the distribution of hits across full genomes
gggenomes(g0, s1, f1, wrap = 2e5) +
  geom_seq() + geom_bin_label() +
  scale_color_brewer(palette = "Dark2") +
  geom_point(aes(x = x, y = y, color = system), data = feats())

# hilight the regions containing hits
gggenomes(g0, s1, f1, wrap = 2e5) %>%
  locate(.track_id = feats) %>%
  identity() +
  geom_seq() + geom_bin_label() +
  scale_color_brewer(palette = "Dark2") +
  geom_feat(data = feats(loci), color = "plum3") +
  geom_point(aes(x = x, y = y, color = system), data = feats())

# zoom in on loci
gggenomes(g0, s1, f1, wrap = 5e4) %>%
  focus(.track_id = feats) +
  geom_seq() + geom_bin_label() +
  geom_gene() +
  geom_feat(aes(color = system)) +
  geom_feat_tag(aes(label = gene)) +
  scale_color_brewer(palette = "Dark2")

Description

Put bin labels left of the sequences. nudge_left adds space relative to the total bin width between the label and the seqs, by default 5%. expand_left expands the plot to the left by 20% to make labels visible.

Usage

geom_bin_label(
  mapping = NULL,
  data = bins(),
  hjust = 1,
  size = 3,
  nudge_left = 0.05,
  expand_left = 0.2,
  expand_x = NULL,
  expand_aes = NULL,
  yjust = 0,
  ...
)

Arguments

Details

Set x and expand_x to an absolute position to align all labels at a specific location

Value

Bin labels are added as a text layer/component to the plot.

Examples

s0 <- read_seqs(list.files(ex("cafeteria"), "Cr.*\\.fa.fai$", full.names = TRUE))
s1 <- s0 %>% dplyr::filter(length > 5e5)

gggenomes(emale_genes) + geom_seq() + geom_gene() +
  geom_bin_label()

# make larger labels and extra room on the canvas
gggenomes(emale_genes) + geom_seq() + geom_gene() +
  geom_bin_label(size = 7, expand_left = .4)

# align labels for wrapped bins:
# top
gggenomes(seqs = s1, infer_bin_id = file_id, wrap = 5e6) +
  geom_seq() + geom_bin_label() + geom_seq_label()

# center
gggenomes(seqs = s1, infer_bin_id = file_id, wrap = 5e6) +
  geom_seq() + geom_bin_label(yjust = .5) + geom_seq_label()

# bottom
gggenomes(seqs = s1, infer_bin_id = file_id, wrap = 5e6) +
  geom_seq() + geom_bin_label(yjust = 1) + geom_seq_label()

Description

Visualize data that varies along sequences as ribbons, lines, lineranges, etc.

Usage

geom_coverage(
  mapping = NULL,
  data = feats(),
  stat = "coverage",
  geom = "ribbon",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  offset = 0,
  height = 0.2,
  max = base::max,
  ...
)

geom_wiggle(
  mapping = NULL,
  data = feats(),
  stat = "wiggle",
  geom = "ribbon",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  offset = 0,
  height = 0.8,
  bounds = Hmisc::smedian.hilow,
  ...
)

Arguments

Details

Geom_wiggle plots the wiggle data in both directions around the median. Geom_coverage plots the data only in positive direction. Both functions use data from the feats' track.

Value

A ggplot2 layer with coverage information.

Aesthetics

geom_wiggle() and geom_coverage() understand aesthetics depending on the chosen underlying ggplot geom, by default ggplot2::geom_ribbon(). Other options that play well are for example ggplot2::geom_line(), ggplot2::geom_linerange(), ggplot2::geom_point(). The only required aesthetic is:

• z

Examples

# Plotting data with geom_coverage with increased height.
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_coverage(aes(z = score), height = 0.5) +
  geom_seq()

# In opposite direction by calling base::min and taking the negative values of "score"
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_coverage(aes(z = -score), max = base::min, height = 0.5) +
  geom_seq()

# GC-content plotted as points with variable color in geom_coverage
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_coverage(aes(z = score, color = score), height = 0.5, geom = "point") +
  geom_seq()
# Plot varying GC-content along sequences as ribbon
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score)) +
  geom_seq()

# customize color and position
gggenomes(genes = emale_genes, seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score), fill = "lavenderblush3", offset = -.3, height = .5) +
  geom_seq() + geom_gene()

# GC-content as line and with variable color
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score, color = score), geom = "line", bounds = c(.5, 0, 1)) +
  geom_seq() +
  scale_colour_viridis_b(option = "A")

# or as lineranges
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score, color = score), geom = "linerange") +
  geom_seq() +
  scale_colour_viridis_b(option = "A")

Description

geom_feat() allows the user to draw (additional) features to the plot/graph. For example, specific regions within a sequence (e.g. transposons, introns, mutation hotspots) can be highlighted by color, size, etc..

Usage

geom_feat(
  mapping = NULL,
  data = feats(),
  stat = "identity",
  position = "pile",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

geom_feat uses ggplot2::geom_segment under the hood. As a result, different aesthetics such as alpha, linewidth, color, etc. can be called upon to modify the visualization of the data.

By default, the function uses the first feature track.

Value

A ggplot2 layer with features.

Examples

# Plotting data from the feats' track with adjusted linewidth and color
gggenomes(seqs = emale_seqs, feats = emale_ngaros) +
  geom_seq() +
  geom_feat(linewidth = 5, color = "darkred")

# Geom_feat can be called several times as well, when specified what data should be used
gggenomes(seqs = emale_seqs, feats = list(emale_ngaros, emale_tirs)) +
  geom_seq() +
  geom_feat(linewidth = 5, color = "darkred") + # uses first feature track
  geom_feat(data = feats(emale_tirs))

# Additional notes to feats can be added with functions such as: geom_feat_note / geom_feat_text
gggenomes(seqs = emale_seqs, feats = list(emale_ngaros, emale_tirs)) +
  geom_seq() +
  geom_feat(color = "darkred") +
  geom_feat(data = feats(emale_tirs), color = "darkblue") +
  geom_feat_note(data = feats(emale_ngaros), label = "repeat region", size = 4)

# Different position adjustments with a simple dataset
exampledata <- tibble::tibble(
  seq_id = c(rep("A", 3), rep("B", 3), rep("C", 3)),
  start = c(0, 30, 15, 40, 80, 20, 30, 50, 70),
  end = c(30, 90, 60, 60, 100, 80, 60, 90, 120)
)

gggenomes(feats = exampledata) +
  geom_feat(position = "identity", alpha = 0.5, linewidth = 0.5) +
  geom_bin_label()

Description

The functions below are useful for labeling features/genes in plots. Users have to call on aes(label = ...) or (label = ...) to define label's text Based on the function, the label will be placed at a specific location:

• geom_..._text() will plot text in the middle of the feature.

• geom_..._tag() will plot text on top of the feature, with a 45 degree angle.

• geom_..._note() will plot text under the feature at the left side.

The ... can be either replaced with feat or gene depending on which track the user wants to label.

With arguments such as hjust, vjust, angle, and nudge_y, the user can also manually change the position of the text.

Usage

geom_feat_text(
  mapping = NULL,
  data = feats(),
  stat = "identity",
  position = "identity",
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_feat_tag(
  mapping = NULL,
  data = feats(),
  stat = "identity",
  position = "identity",
  hjust = 0,
  vjust = 0,
  angle = 45,
  nudge_y = 0.03,
  xjust = 0.5,
  strandwise = TRUE,
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_feat_note(
  mapping = NULL,
  data = feats(),
  stat = "identity",
  position = "identity",
  hjust = 0,
  vjust = 1,
  nudge_y = -0.03,
  xjust = 0,
  strandwise = FALSE,
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_gene_text(
  mapping = NULL,
  data = genes(),
  stat = "identity",
  position = "identity",
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_gene_tag(
  mapping = NULL,
  data = genes(),
  stat = "identity",
  position = "identity",
  hjust = 0,
  vjust = 0,
  angle = 45,
  nudge_y = 0.03,
  xjust = 0.5,
  strandwise = TRUE,
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_gene_note(
  mapping = NULL,
  data = genes(),
  stat = "identity",
  position = "identity",
  hjust = 0,
  vjust = 1,
  nudge_y = -0.03,
  xjust = 0,
  strandwise = FALSE,
  ...,
  parse = FALSE,
  check_overlap = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

These labeling functions use ggplot2::geom_text() under the hood. Any changes to the aesthetics of the text can be performed in a ggplot2 manner.

Value

A ggplot2 layer with gene text.

A ggplot2 layer with feature tags.

A ggplot2 layer with feature notes.

A ggplot2 layer with gene text.

A ggplot2 layer with gene tags.

A ggplot2 layer with gene notes.

Examples

# example data
genes <- tibble::tibble(
  seq_id = c("A", "A", "A", "B", "B", "C"),
  start = c(20, 40, 80, 30, 10, 60),
  end = c(30, 70, 85, 40, 15, 90),
  feat_id = c("A1", "A2", "A3", "B1", "B2", "C1"),
  type = c("CDS", "CDS", "CDS", "CDS", "CDS", "CDS"),
  name = c("geneA", "geneB", "geneC", "geneA", "geneC", "geneB")
)

seqs <- tibble::tibble(
  seq_id = c("A", "B", "C"),
  start = c(0, 0, 0),
  end = c(100, 100, 100),
  length = c(100, 100, 100)
)

# basic plot creation
plot <- gggenomes(seqs = seqs, genes = genes) +
  geom_bin_label() +
  geom_gene()

# geom_..._text
plot + geom_gene_text(aes(label = name))

# geom_..._tag
plot + geom_gene_tag(aes(label = name))

# geom_..._note
plot + geom_gene_note(aes(label = name))

# with horizontal adjustment (`hjust`), vertical adjustment (`vjust`)
plot + geom_gene_text(aes(label = name), vjust = -2, hjust = 1)

# using `nudge_y` and and `angle` adjustment
plot + geom_gene_text(aes(label = name), nudge_y = 1, angle = 10)

# labeling with manual input
plot + geom_gene_text(label = c("This", "is", "an", "example", "test", "test"))

Description

Draw coding sequences, mRNAs and other non-coding features. Supports multi-exon features. CDS and mRNAs in the same group are plotted together. They can therefore also be positioned as a single unit using the position argument.

Usage

geom_gene(
  mapping = NULL,
  data = genes(),
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  size = 2,
  rna_size = size,
  shape = size,
  rna_shape = shape,
  intron_shape = size,
  intron_types = c("CDS", "mRNA", "tRNA", "tmRNA", "ncRNA", "rRNA"),
  cds_aes = NULL,
  rna_aes = NULL,
  intron_aes = NULL,
  ...
)

Arguments

Value

A ggplot2 layer with genes.

Aesthetics

geom_gene() understands the following aesthetics (required aesthetics are in bold):

• x

• xend

• y

• alpha

• colour

• fill

• group

• introns

• linetype

• stroke

• type

Learn more about setting these aesthetics in vignette("ggplot2-specs").

'type' and 'group' (mapped to 'type' and 'geom_id' by default) power the proper recognition of CDS and their corresponding mRNAs so that they can be drawn as one composite object. Overwrite 'group' to plot CDS and mRNAs independently.

'introns' (mapped to 'introns') is used to compute intron/exon boundaries. Use the parameter intron_types if you want to disable introns.

Examples

gggenomes(genes = emale_genes) +
  geom_gene()

gggenomes(genes = emale_genes) +
  geom_gene(aes(fill = as.numeric(gc_content)), position = "strand") +
  scale_fill_viridis_b()

g0 <- read_gff3(ex("eden-utr.gff"))
gggenomes(genes = g0) +
  # all features in the "genes" regardless of type
  geom_feat(data = feats(genes)) +
  annotate("text", label = "geom_feat", x = -15, y = .9) + xlim(-20, NA) +
  # only features in the "genes" of geneish type (implicit `data=genes()`)
  geom_gene() +
  geom_gene_tag(aes(label = ifelse(is.na(type), "<NA>", type)), data = genes(.gene_types = NULL)) +
  annotate("text", label = "geom_gene", x = -15, y = 1) +
  # control which types are returned from the track
  geom_gene(aes(y = 1.1), data = genes(.gene_types = c("CDS", "misc_RNA"))) +
  annotate("text", label = "gene_types", x = -15, y = 1.1) +
  # control which types can have introns
  geom_gene(
    aes(y = 1.2, yend = 1.2),
    data = genes(.gene_types = c("CDS", "misc_RNA")),
    intron_types = "misc_RNA"
  ) +
  annotate("text", label = "intron_types", x = -15, y = 1.2)

# spliced genes
library(patchwork)
gg <- gggenomes(genes = g0)
gg + geom_gene(position = "pile") +
  gg + geom_gene(aes(fill = type),
    position = "pile",
    shape = 0, intron_shape = 0, color = "white"
  ) +
  # some fine-control on cds/rna/intron after_scale aesthetics
  gg + geom_gene(aes(fill = geom_id),
    position = "pile",
    size = 2, shape = c(4, 3), rna_size = 2, intron_shape = 4, stroke = 0,
    cds_aes = aes(fill = "black"), rna_aes = aes(fill = fill),
    intron_aes = aes(colour = fill, stroke = 2)
  ) +
  scale_fill_viridis_d() +
  # fun with introns
  gg + geom_gene(aes(fill = geom_id), position = "pile", size = 3, shape = c(4, 4)) +
  gg + geom_gene(aes(fill = geom_id),
    position = "pile", size = 3, shape = c(4, 4),
    intron_types = c()
  ) +
  gg + geom_gene(aes(fill = geom_id),
    position = "pile", size = 3, shape = c(4, 4),
    intron_types = "CDS"
  )

Description

These geom_..._label() functions able the user to plot labels/text at individual features and/or links. Users have to indicate how to label the features/links by specifying label = ... or ⁠aes(label = ...⁠

Position of labels can be adjusted with arguments such as vjust, hjust, angle, nudge_y, etc. Also check out geom_bin_label(), geom_seq_label() or geom_feat_text() given their resemblance.

Usage

geom_gene_label(
  mapping = NULL,
  data = genes(),
  angle = 45,
  hjust = 0,
  nudge_y = 0.1,
  size = 6,
  ...
)

geom_feat_label(
  mapping = NULL,
  data = feats(),
  angle = 45,
  hjust = 0,
  nudge_y = 0.1,
  size = 6,
  ...
)

geom_link_label(
  mapping = NULL,
  data = links(),
  angle = 0,
  hjust = 0.5,
  vjust = 0.5,
  size = 4,
  repel = FALSE,
  ...
)

Arguments

Details

These labeling functions use ggplot2::geom_text() under the hood. Any changes to the aesthetics of the text can be performed in a ggplot2 manner.

Value

Gene labels are added as a text layer/component to the plot.

Description

Draws connections between genomes, such as genome/gene/protein alignments and gene/protein clusters. geom_link() draws links as filled polygons, geom_link_line() draws a single connecting line.

Note that by default only links between adjacent genomes are computed and shown. To compute and show all links between all genomes, set gggenomes(..., adjacent_only=FALSE).

Usage

geom_link(
  mapping = NULL,
  data = links(),
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  offset = 0.15,
  ...
)

geom_link_line(
  mapping = NULL,
  data = links(),
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

The function calls upon the data stored within the link track. Data frames added to this track have seq_id and seq_id2 as required variables. Optional and recommended variables include start, start2, end, end2, bin_id, bin_id2 and strand.

Note, when start/end is not specified, links will be created between the entire contigs of seq_id and seq_id2.

Value

A ggplot2 layer with links.

Examples

p0 <- gggenomes(seqs = emale_seqs, links = emale_ava) + geom_seq()

# default links
p1 <- p0 + geom_link()

# change offset from seqs and color
p2 <- p0 + geom_link(aes(fill = de, color = de), offset = 0.05) +
  scale_fill_viridis_b() + scale_colour_viridis_b()

# combine with flip
p3 <- p0 |> flip(3, 4, 5) +
  geom_link()

# compute & show all links among all genomes
# usually not useful and not recommended for large dataset
p4 <- gggenomes(links = emale_ava, adjacent_only = FALSE) + geom_link()

library(patchwork) # combine plots in one figure
p1 + p2 + p3 + p4 + plot_layout(nrow = 1)
q0 <- gggenomes(emale_genes, emale_seqs) |>
  add_clusters(emale_cogs) +
  geom_seq() + geom_gene()

# link gene clusters with polygon
q1 <- q0 + geom_link(aes(fill = cluster_id))

# link gene clusters with lines
q2 <- q0 + geom_link_line(aes(color = cluster_id))

q1 + q2 + plot_layout(nrow = 1, guides = "collect")

Description

geom_seq() draws contigs for each sequence/chromosome supplied in the seqs track. Several sequences belonging to the same bin will be plotted next to one another.

If seqs track is empty, sequences are inferred from the feats or links track respectively.

(The length of sequences can be deduced from the axis and is typically indicated in base pairs.)

Usage

geom_seq(mapping = NULL, data = seqs(), arrow = NULL, ...)

Arguments

Details

geom_seq() uses ggplot2::geom_segment() under the hood. As a result, different aesthetics such as alpha, linewidth, color, etc. can be called upon to modify the visualization of the data.

Note: The seqs track indicates the length/region of the sequence/contigs that will be plotted. Feats or links data that falls outside of this region are ignored!

Value

Sequence data drawn as contigs is added as a layer/component to the plot.

Examples

# Simple example of geom_seq
gggenomes(seqs = emale_seqs) +
  geom_seq() + # creates contigs
  geom_bin_label() # labels bins/sequences

# No sequence information supplied, will inform/warn that seqs are inferred from feats.
gggenomes(genes = emale_genes) +
  geom_seq() + # creates contigs
  geom_gene() + # draws genes on top of contigs
  geom_bin_label() # labels bins/sequences

# Sequence data controls what sequences and/or regions will be plotted.
# Here one sequence is filtered out, Notice that the genes of the removed
# sequence are silently ignored and thus not plotted.
missing_seqs <- emale_seqs |>
  dplyr::filter(seq_id != "Cflag_017B") |>
  dplyr::arrange(seq_id) # `arrange` to restore alphabetical order.

gggenomes(seqs = missing_seqs, genes = emale_genes) +
  geom_seq() + # creates contigs
  geom_gene() + # draws genes on top of contigs
  geom_bin_label() # labels bins/sequences

# Several sequences belonging to the same *bin* are plotted next to one another
seqs <- tibble::tibble(
  bin_id = c("A", "A", "A", "B", "B", "B", "B", "C", "C"),
  seq_id = c("A1", "A2", "A3", "B1", "B2", "B3", "B4", "C1", "C2"),
  start = c(0, 100, 200, 0, 50, 150, 250, 0, 400),
  end = c(100, 200, 400, 50, 100, 250, 300, 300, 500),
  length = c(100, 100, 200, 50, 50, 100, 50, 300, 100)
)

gggenomes(seqs = seqs) +
  geom_seq() +
  geom_bin_label() + # label bins
  geom_seq_label() # label individual sequences

# Wrap bins uptill a certain amount.
gggenomes(seqs = seqs, wrap = 300) +
  geom_seq() +
  geom_bin_label() + # label bins
  geom_seq_label() # label individual sequences

# Change the space between sequences belonging to one bin
gggenomes(seqs = seqs, spacing = 100) +
  geom_seq() +
  geom_bin_label() + # label bins
  geom_seq_label() # label individual sequences

Description

geom_seq_break() adds decorations to the ends of truncated sequences. These could arise from zooming onto sequence loci with focus(), or manually annotating sequences with start > 1 and/or end < length.

Usage

geom_seq_break(
  mapping_start = NULL,
  mapping_end = NULL,
  data_start = seqs(start > 1),
  data_end = seqs(end < length),
  label = "/",
  size = 4,
  hjust = 0.75,
  family = "sans",
  stat = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Value

A ggplot2 layer with sequence breaks.

Examples

# decorate breaks created with focus()
gggenomes(emale_genes, emale_seqs) |>
  focus(.expand = 1e3, .max_dist = 1e3) +
  geom_seq() + geom_gene() +
  geom_seq_break()

# customize decorations
gggenomes(emale_genes, emale_seqs) |>
  focus(.expand = 1e3, .max_dist = 1e3) +
  geom_seq() + geom_gene() +
  geom_seq_break(label = c("[", "]"), size = 3, color = "#1b9e77")

# decorate manually truncated sequences
s0 <- tibble::tribble(
  # start/end define regions, i.e. truncated contigs
  ~bin_id, ~seq_id, ~length, ~start, ~end,
  "complete_genome", "chromosome_1_long_trunc_2side", 1e5, 1e4, 2.1e4,
  "fragmented_assembly", "contig_1_trunc_1side", 1.3e4, .9e4, 1.3e4,
  "fragmented_assembly", "contig_2_short_complete", 0.3e4, 1, 0.3e4,
  "fragmented_assembly", "contig_3_trunc_2sides", 2e4, 1e4, 1.4e4
)

l0 <- tibble::tribble(
  ~seq_id, ~start, ~end, ~seq_id2, ~start2, ~end2,
  "chromosome_1_long_trunc_2side", 1.1e4, 1.4e4,
  "contig_1_trunc_1side", 1e4, 1.3e4,
  "chromosome_1_long_trunc_2side", 1.4e4, 1.7e4,
  "contig_2_short_complete", 1, 0.3e4,
  "chromosome_1_long_trunc_2side", 1.7e4, 2e4,
  "contig_3_trunc_2sides", 1e4, 1.3e4
)

gggenomes(seqs = s0, links = l0) +
  geom_seq() + geom_link() +
  geom_seq_label(nudge_y = -.05) +
  geom_seq_break()

Description

This function will put labels at each individual sequence. By default it will plot the seq_id as label, but users are able to change this manually.

Position of the label/text can be adjusted with the different arguments (e.g. vjust, hjust, angle, etc.)

Usage

geom_seq_label(
  mapping = NULL,
  data = seqs(),
  hjust = 0,
  vjust = 1,
  nudge_y = -0.15,
  size = 2.5,
  ...
)

Arguments

Details

This labeling function uses ggplot2::geom_text() under the hood. Any changes to the aesthetics of the text can be performed in a ggplot2 manner.

Value

Sequence labels are added as a text layer/component to the plot.

Examples

# example data
seqs <- tibble::tibble(
  bin_id = c("A", "A", "A", "B", "B", "B", "B", "C", "C"),
  seq_id = c("A1", "A2", "A3", "B1", "B2", "B3", "B4", "C1", "C2"),
  start = c(0, 100, 200, 0, 50, 150, 250, 0, 400),
  end = c(100, 200, 400, 50, 100, 250, 300, 300, 500),
  length = c(100, 100, 200, 50, 50, 100, 50, 300, 100)
)

# example plot using geom_seq_label
gggenomes(seqs = seqs) +
  geom_seq() +
  geom_seq_label()

# changing default label to `length` column
gggenomes(seqs = seqs) +
  geom_seq() +
  geom_seq_label(aes(label = length))

# with horizontal adjustment
gggenomes(seqs = seqs) +
  geom_seq() +
  geom_seq_label(hjust = -5)

# with wrapping at 300
gggenomes(seqs = seqs, wrap = 300) +
  geom_seq() +
  geom_seq_label()

Description

geom_variant allows the user to draw points at locations where a mutation has occured. Data on SNPs, Insertions, Deletions and more (often stored in a variant call format (VCF)) can easily be visualized this way.

Usage

geom_variant(
  mapping = NULL,
  data = feats(),
  stat = "identity",
  position = "identity",
  geom = "variant",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  offset = 0,
  ...
)

Arguments

Details

geom_variant uses ggplot2::geom_point under the hood. As a result, different aesthetics such as alpha, size, color, etc. can be called upon to modify the data visualization.

#' the function gggenomes::read_feats is able to read VCF files and converts them into a format that is applicable within the gggenomes' track system. Keep in mind: The function uses data from the feats' track.

Value

A ggplot2 layer with variant information.

Examples

# Creation of example data.
# (Note: These are mere examples and do not fully resemble data from VCF-files)
## Small example data set
f1 <- tibble::tibble(
  seq_id = c(rep(c("A", "B"), 4)), start = c(1, 10, 15, 15, 30, 40, 40, 50),
  end = c(2, 11, 20, 16, 31, 41, 50, 51), length = end - start,
  type = c("SNP", "SNP", "Insertion", "Deletion", "Deletion", "SNP", "Insertion", "SNP"),
  ALT = c("A", "T", "CAT", ".", ".", "G", "GG", "G"),
  REF = c("C", "G", "C", "A", "A", "C", "G", "T")
)
s1 <- tibble::tibble(seq_id = c("A", "B"), start = c(0, 0), end = c(55, 55), length = end - start)

## larger example data set
f2 <- tibble::tibble(
  seq_id = c(rep("A", 667)),
  start = c(
    seq(from = 1, to = 500, by = 2),
    seq(from = 500, to = 2500, by = 50),
    seq(from = 2500, to = 4000, by = 4)
  ),
  end = start + 1, length = end - start,
  type = c(
    rep("SNP", 100),
    rep("Deletion", 20),
    rep("SNP", 180),
    rep("Deletion", 67),
    rep("SNP", 100),
    rep("Insertion", 50),
    rep("SNP", 150)
  ),
  ALT = c(
    sample(x = c("A", "C", "G", "T"), size = 100, replace = TRUE),
    rep(".", 20), sample(x = c("A", "C", "G", "T"), size = 180, replace = TRUE),
    rep(".", 67), sample(x = c("A", "C", "G", "T"), size = 100, replace = TRUE),
    sample(x = c(
      "AA", "AC", "AG", "AT", "CA", "CC", "CG", "CT", "GA", "GC",
      "GG", "GT", "TA", "TC", "TG", "TT"
    ), size = 50, replace = TRUE),
    sample(x = c("A", "C", "G", "T"), size = 150, replace = TRUE)
  )
)

# Basic example plot with geom_variant
gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant()

# Improving plot elements, by changing shape and adding bin_label
gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant(aes(shape = type), offset = -0.1) +
  scale_shape_variant() +
  geom_bin_label()

# Positional adjustment based on type of mutation: position_variant
gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant(
    aes(shape = type),
    position = position_variant(offset = c(Insertion = -0.2, Deletion = -0.2, SNP = 0))
  ) +
  scale_shape_variant() +
  geom_bin_label()

# Plotting larger example data set with Changing default geom to
# `geom = "ticks"` using positional adjustment based on type (`position_variant`)
gggenomes(feats = f2) +
  geom_variant(aes(color = type), geom = "ticks", alpha = 0.4, position = position_variant()) +
  geom_bin_label()

# Changing geom to `"text"`, to plot ALT nucleotides
gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant(aes(shape = type), offset = -0.1) +
  scale_shape_variant() +
  geom_variant(aes(label = ALT), geom = "text", offset = -0.25) +
  geom_bin_label()

Description

Geom for feature text

Usage

GeomFeatText

Format

An object of class GeomFeatText (inherits from Geom, ggproto, gg) of length 6.

Description

Get/set the seqs track

Usage

get_seqs(x)

set_seqs(x, value)

Arguments

Value

a gggenomes_layout track tibble

Description

gggenomes() initializes a gggenomes-flavored ggplot object. It is used to declare the input data for gggenomes' track system.

(See for more details on the track system, gggenomes vignette or the Details/Arguments section)

Usage

gggenomes(
  genes = NULL,
  seqs = NULL,
  feats = NULL,
  links = NULL,
  .id = "file_id",
  spacing = 0.05,
  wrap = NULL,
  adjacent_only = TRUE,
  infer_bin_id = seq_id,
  infer_start = min(start, end),
  infer_end = max(start, end),
  infer_length = max(start, end),
  theme = c("clean", NULL),
  .layout = NULL,
  ...
)

Arguments

Details

gggenomes::gggenomes() resembles the functionality of ggplot2::ggplot(). It is used to construct the initial plot object, and is often followed by "+" to add components to the plot (e.g. "+ geom_gene()").

A big difference between the two is that gggenomes has a multi-track setup ('seqs', 'feats', 'genes' and 'links'). gggenomes() pre-computes a layout and adds coordinates (⁠y,x,xend⁠) to each data frame prior to the actual plot construction. This has some implications for the usage of gggenomes:

• Data frames for tracks have required variables. These predefined variables are used during import to compute x/y coordinates (see arguments).

• gggenomes' geoms can often be used without explicit aes() mappings This works because we always know the names of the plot variables ahead of time: they originate from the pre-computed layout, and we can use that information to set sensible default aesthetic mappings for most cases.

Value

gggenomes-flavored ggplot object

Examples

# Compare the genomic organization of three viral elements
# EMALEs: endogenous mavirus-like elements (example data shipped with gggenomes)
gggenomes(emale_genes, emale_seqs, emale_tirs, emale_ava) +
  geom_seq() + geom_bin_label() + # chromosomes and labels
  geom_feat(size = 8) + # terminal inverted repeats
  geom_gene(aes(fill = strand), position = "strand") + # genes
  geom_link(offset = 0.15) # synteny-blocks

# with some more information
gggenomes(emale_genes, emale_seqs, emale_tirs, emale_ava) %>%
  add_feats(emale_ngaros, emale_gc) %>%
  add_clusters(emale_cogs) %>%
  sync() +
  geom_link(offset = 0.15, color = "white") + # synteny-blocks
  geom_seq() + geom_bin_label() + # chromosomes and labels
  # thistle4, salmon4, burlywood4
  geom_feat(size = 6, position = "identity") + # terminal inverted repeats
  geom_feat(
    data = feats(emale_ngaros), color = "turquoise4", alpha = .3,
    position = "strand", size = 16
  ) +
  geom_feat_note(aes(label = type),
    data = feats(emale_ngaros),
    position = "strand", nudge_y = .3
  ) +
  geom_gene(aes(fill = cluster_id), position = "strand") + # genes
  geom_wiggle(aes(z = score, linetype = "GC-content"), feats(emale_gc),
    fill = "lavenderblush4", position = position_nudge(y = -.2), height = .2
  ) +
  scale_fill_brewer("Conserved genes", palette = "Dark2", na.value = "cornsilk3")

# initialize plot directly from files
gggenomes(
  ex("emales/emales.gff"),
  ex("emales/emales.gff"),
  ex("emales/emales-tirs.gff"),
  ex("emales/emales.paf")
) + geom_seq() + geom_gene() + geom_feat() + geom_link()

# multi-contig genomes wrap to fixed width
s0 <- read_seqs(list.files(ex("cafeteria"), "Cr.*\\.fa.fai$", full.names = TRUE))
s1 <- s0 %>% dplyr::filter(length > 5e5)
gggenomes(seqs = s1, infer_bin_id = file_id, wrap = 5e6) +
  geom_seq() + geom_bin_label() + geom_seq_label()

Description

Vectorised if_else based on strandedness

Usage

if_reverse(strand, reverse, forward)

Arguments

Value

vector with values based on strandedness

Description

Do numeric values fall into specified ranges?

Usage

in_range(x, left, right, closed = TRUE)

Arguments

Value

a logical vector of the same length as the input

Examples

in_range(1:5, 2, 4)
in_range(1:5, 2, 4, closed = c(FALSE, TRUE)) # left-open
in_range(1:5, 6:2, 3) # vector of boundaries, single values recycle


# plays nicely with dplyr
df <- tibble::tibble(x = rep(4, 5), left = 1:5, right = 3:7)
dplyr::mutate(df,
  closed = in_range(x, left, right, TRUE),
  open = in_range(x, left, right, FALSE)
)

Description

Works like dplyr::mutate() but without changing existing columns, but only adding new ones. Useful to add possibly missing columns with default values.

Usage

introduce(.data, ...)

Arguments

Value

a tibble with new columns

Examples

# ensure columns "y" and "z" exist
tibble::tibble(x = 1:3) %>%
  introduce(y = "a", z = paste0(y, dplyr::row_number()))
# ensure columns "y" and "z" exist, but do not overwrite "y"
tibble::tibble(x = 1:3, y = c("c", "d", "e")) %>%
  introduce(y = "a", z = paste0(y, dplyr::row_number()))

Description

Check whether strand is reverse

Usage

is_reverse(strand, na = FALSE)

Arguments

Value

logical vector indicating whether the strand is reverse

Description

Re-layout the tracks and update the scales after seqs have been modified

Usage

layout(x, ...)

Arguments

Value

layout with updated scales

Description

Layout sequences

Usage

layout_seqs(
  x,
  spacing = 0.05,
  wrap = NULL,
  spacing_style = c("regular", "center", "spread"),
  keep = "strand"
)

Arguments

Value

a tbl_df with plot coordinates

Description

Pick which bins and seqs to show and in what order. Uses dplyr::select()-like syntax, which means unquoted genome names, positional arguments and selection helpers, such as tidyselect::starts_with() are supported. Renaming is not supported.

Usage

pick(x, ...)

pick_seqs(x, ..., .bins = everything())

pick_seqs_within(x, ..., .bins = everything())

pick_by_tree(x, tree, infer_bin_id = .data$label)

Arguments

Details

Use the dots to select bins or sequences (depending on function suffix), and the .bins argument to set the scope for positional arguments. For example, pick_seqs(1) will pick the first sequence from the first bin, while pick_seqs(1, .bins=3) will pick the first sequence from the third bin.

Value

gggenomes object with selected bins and seqs.

gggenomes object with selected seqs.

gggenomes object with selected seqs.

gggenomes object with seqs selected by tree order.

Functions

• pick(): pick bins by bin_id, positional argument (start at top) or select-helper.

• pick_seqs(): pick individual seqs seq_id, positional argument (start at top left) or select-helper.

• pick_seqs_within(): pick individual seqs but only modify bins containing those seqs, keep rest as is.

• pick_by_tree(): align bins with the leaves in a given phylogenetic tree.

Examples

s0 <- tibble::tibble(
  bin_id = c("A", "B", "B", "B", "C", "C", "C"),
  seq_id = c("a1", "b1", "b2", "b3", "c1", "c2", "c3"),
  length = c(1e4, 6e3, 2e3, 1e3, 3e3, 3e3, 3e3)
)

p <- gggenomes(seqs = s0) + geom_seq(aes(color = bin_id), size = 3) +
  geom_bin_label() + geom_seq_label() +
  expand_limits(color = c("A", "B", "C"))
p

# remove
p %>% pick(-B)

# select and reorder, by ID and position
p %>% pick(C, 1)

# use helper function
p %>% pick(starts_with("B"))

# pick just some seqs
p %>% pick_seqs(1, c3)

# pick with .bin scope
p %>% pick_seqs(3:1, .bins = C)

# change seqs in some bins, but keep rest as is
p %>% pick_seqs_within(3:1, .bins = B)

# same w/o scope, unaffected bins remain as is
p %>% pick_seqs_within(b3, b2, b1)

# Align sequences with and plot next to a phylogenetic tree
library(patchwork) # arrange multiple plots
library(ggtree) # plot phylogenetic trees

# load and plot a phylogenetic tree
emale_mcp_tree <- read.tree(ex("emales/emales-MCP.nwk"))
t <- ggtree(emale_mcp_tree) + geom_tiplab(align = TRUE, size = 3) +
  xlim(0, 0.05) # make room for labels

p <- gggenomes(seqs = emale_seqs, genes = emale_genes) +
  geom_seq() + geom_seq() + geom_bin_label()

# plot next to each other, but with
# different order in tree and genomes
t + p + plot_layout(widths = c(1, 5))

# reorder genomes to match tree order
# with a warning caused by mismatch in y-scale expansions
t + p %>% pick_by_tree(t) + plot_layout(widths = c(1, 5))

# extra genomes are dropped with a notification
emale_seqs_more <- emale_seqs
emale_seqs_more[7, ] <- emale_seqs_more[6, ]
emale_seqs_more$seq_id[7] <- "One more genome"
p <- gggenomes(seqs = emale_seqs_more, genes = emale_genes) +
  geom_seq() + geom_seq() + geom_bin_label()
t + p %>% pick_by_tree(t) + plot_layout(widths = c(1, 5))

try({
  # no shared ids will cause an error
  p <- gggenomes(seqs = tibble::tibble(seq_id = "foo", length = 1)) +
    geom_seq() + geom_seq() + geom_bin_label()
  t + p %>% pick_by_tree(t) + plot_layout(widths = c(1, 5))

  # extra leafs in tree will cause an error
  emale_seqs_fewer <- slice_head(emale_seqs, n = 4)
  p <- gggenomes(seqs = emale_seqs_fewer, genes = emale_genes) +
    geom_seq() + geom_seq() + geom_bin_label()
  t + p %>% pick_by_tree(t) + plot_layout(widths = c(1, 5))
})

Description

position_strand() offsets forward feats upward and reverse feats downward. position_pile() stacks overlapping feats upward. position_strandpile() stacks overlapping feats up-/downward based on their strand. position_sixframe() offsets the feats based on their strand and reading frame.

Usage

position_strand(offset = 0.1, flip = FALSE, grouped = NULL, base = offset/2)

position_pile(offset = 0.1, gap = 1, flip = FALSE, grouped = NULL, base = 0)

position_strandpile(
  offset = 0.1,
  gap = 1,
  flip = FALSE,
  grouped = NULL,
  base = offset * 1.5
)

position_sixframe(offset = 0.1, flip = FALSE, grouped = NULL, base = offset/2)