### Install gggenomes and dependencies

Source: https://github.com/thackl/gggenomes/blob/main/README.md

Instructions for installing the stable version from CRAN, the developmental version from GitHub, and the optional ggtree dependency.

```R
# Install from CRAN
install.packages("gggenomes") 

# optionally install ggtree to plot genomes next to trees
# https://bioconductor.org/packages/release/bioc/html/ggtree.html
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("ggtree")

# Install latest developmental version from github
devtools::install_github("thackl/gggenomes")
```

--------------------------------

### Visualize genomic links

Source: https://context7.com/thackl/gggenomes/llms.txt

Examples of drawing links between genomic sequences with various styles and configurations.

```r
p2 <- p0 + geom_link(aes(fill = de, color = de), offset = 0.05) +
  scale_fill_viridis_b() + scale_colour_viridis_b()
```

```r
p3 <- p0 |> flip(3, 4, 5) +
  geom_link()
```

```r
q0 <- gggenomes(emale_genes, emale_seqs) |>
  add_clusters(emale_cogs) +
  geom_seq() + geom_gene()
```

```r
q0 + geom_link(aes(fill = cluster_id))              # polygon
q0 + geom_link_curved(aes(fill = cluster_id))       # bezier curved
q0 + geom_link_line(aes(color = cluster_id))        # line
```

--------------------------------

### Use Tidyselect Helpers to Pick Bins

Source: https://context7.com/thackl/gggenomes/llms.txt

Employ `tidyselect` helpers like `starts_with()` within `pick()` to select bins based on pattern matching. This offers a flexible way to choose bins for visualization.

```R
p %>% pick(starts_with("B"))
```

--------------------------------

### Visualize synteny links

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Imports alignment links and adds them to the visualization, including flipping specific bins.

```R
emale_links <- read_paf("emales.paf")

p4 <- gggenomes(emale_seqs_6, emale_genes, emale_tirs, emale_links) +
  geom_seq() + geom_bin_label() +
  geom_feature(size=5, data=use_features(features)) +
  geom_gene(aes(fill=gc_cont)) +
  geom_link() +
  scale_fill_distiller(palette="Spectral")

p4 <- p4 %>% flip_bins(3:5)
p4

pp(p4)
```

--------------------------------

### Initialize gggenomes Plot with Data Tracks

Source: https://context7.com/thackl/gggenomes/llms.txt

Initializes a gggenomes plot with gene, sequence, feature, and link data. Use this to declare input data for the track system and pre-compute layouts.

```r
library(gggenomes)

# Basic initialization with genes, sequences, features, and links
gggenomes(
  genes = emale_genes,      # gene annotations
  seqs = emale_seqs,        # sequence lengths
  feats = emale_tirs,       # terminal inverted repeats
  links = emale_ava         # all-vs-all alignments
) +
  geom_seq() +              # draw chromosomes
  geom_bin_label() +        # label bins
  geom_feat(linewidth = 8) +  # draw features
  geom_gene(aes(fill = strand), position = "strand") +  # draw genes
  geom_link(offset = 0.15)  # draw synteny links
```

```r
# Initialize directly from files
gggenomes(
  genes = ex("emales/emales.gff"),
  seqs = ex("emales/emales.gff"),
  feats = ex("emales/emales-tirs.gff"),
  links = ex("emales/emales.paf")
) + geom_seq() + geom_gene() + geom_feat() + geom_link()
```

```r
# Multi-contig genomes with wrapping
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()
```

--------------------------------

### gggenomes - Initialize a Comparative Genomics Plot

Source: https://context7.com/thackl/gggenomes/llms.txt

Initializes a gggenomes-flavored ggplot object and declares input data for the track system. It pre-computes a layout and adds coordinates to each data frame before plot construction. The function accepts genes, sequences, features, and links as input tracks.

```APIDOC
## gggenomes - Initialize a Comparative Genomics Plot

### Description
Initializes a gggenomes-flavored ggplot object and is used to declare input data for the track system. It pre-computes a layout and adds coordinates to each data frame before plot construction. The function accepts genes, sequences, features, and links as input tracks.

### Method
`gggenomes()`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **genes** (data.frame) - Gene annotations.
- **seqs** (data.frame) - Sequence lengths.
- **feats** (data.frame) - Terminal inverted repeats or other features.
- **links** (data.frame) - All-vs-all alignments.
- **infer_bin_id** (function) - Function to infer bin IDs.
- **wrap** (numeric) - Value for wrapping genomes.

### Request Example
```r
library(gggenomes)

# Basic initialization with genes, sequences, features, and links
gggenomes(
  genes = emale_genes,
  seqs = emale_seqs,
  feats = emale_tirs,
  links = emale_ava
) + 
  geom_seq() +
  geom_bin_label() +
  geom_feat(linewidth = 8) +
  geom_gene(aes(fill = strand), position = "strand") +
  geom_link(offset = 0.15)

# Initialize directly from files
gggenomes(
  genes = ex("emales/emales.gff"),
  seqs = ex("emales/emales.gff"),
  feats = ex("emales/emales-tirs.gff"),
  links = ex("emales/emales.paf")
) + geom_seq() + geom_gene() + geom_feat() + geom_link()

# Multi-contig genomes with wrapping
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()
```

### Response
N/A (R object)
```

--------------------------------

### Access Track Information

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `track_info()` to view information about the available tracks in a gggenomes object. This is useful for understanding the data structure before accessing specific tracks.

```R
gg <- gggenomes(emale_genes, emale_seqs, emale_tirs, emale_ava)
gg %>% track_info()  # view track information
```

--------------------------------

### Sync Based on Protein Alignments

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `sync()` with `add_sublinks()` to automatically orient bins based on protein-protein alignments. This is useful for visualizing conserved protein-coding regions.

```R
p %>% 
  add_sublinks(emale_prot_ava) %>%
  sync() + labs(caption = "protein sync")
```

--------------------------------

### Align Using align() Function

Source: https://context7.com/thackl/gggenomes/llms.txt

Demonstrates left, right, and center alignment of genes using the align() function.

```r
p <- gggenomes(emale_genes, links = emale_ava) +
  geom_link() +
  geom_gene(aes(fill = name)) +
  scale_fill_brewer(palette = "Dark2", na.value = "cornsilk3") +
  geom_bin_label()

# Left-align on MCP gene
p |> align(name == "MCP")

# Right-align on MCP gene
p |> align(name == "MCP", .justify = "right")

# Center-align on multiple genes after syncing
p |> sync() |> align(name %in% c("MCP", "pri-hel"), .justify = "center")
```

--------------------------------

### Select and Reorder Bins by ID and Position

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `pick(C, 1)` to select specific bins (e.g., 'C') and reorder them by their position. This provides control over the display order of genomic bins.

```R
p %>% pick(C, 1)
```

--------------------------------

### Pick Sequences with Bin Scope

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `pick_seqs(3:1, .bins = C)` to select sequences within a specific bin ('C') and control their order. The `.bins` argument scopes the selection.

```R
p %>% pick_seqs(3:1, .bins = C)
```

--------------------------------

### Visualize gene annotations

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Imports GFF annotations and adds them to the gggenomes plot with GC-content coloring.

```R
emale_genes <- read_gff("emales.gff") %>%
  rename(feature_id=ID) %>%                       # we'll need this later
  mutate(gc_cont=as.numeric(gc_cont))             # per gene GC-content

p2 <- gggenomes(emale_seqs_6, emale_genes) +
  geom_seq() + geom_bin_label() +
  geom_gene(aes(fill=gc_cont)) +
  scale_fill_distiller(palette="Spectral")
p2

pp(p2)
```

--------------------------------

### Compare genome synteny

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Performs all-vs-all alignment and visualizes links between genomes.

```sh
# All-vs-all alignment | https://github.com/lh3/minimap2
minimap2 -X -N 50 -p 0.1 -c emales.fna emales.fna > emales.paf
```

--------------------------------

### Automatically Sync Genome Alignments

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `sync()` to automatically flip bins to maximize forward strand links between neighbors, based on genome alignments. This simplifies visualization of syntenic regions.

```R
p %>% 
  add_links(emale_ava) %>%
  sync() + labs(caption = "auto sync")
```

--------------------------------

### Annotate genes with Prodigal

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Prepares sequences and runs Prodigal to generate gene annotations in GFF format.

```sh
# https://github.com/thackl/seq-scripts
seq-join -n emales-concat < emales.fna > emales-concat.fna                       
# Annotate genes | https://github.com/hyattpd/Prodigal
prodigal -n -t emales-prodigal.train -i emales-concat.fna                                 
prodigal -t emales-prodigal.train -i emales.fna -o emales-prodigal.gff -f gff
# A little help to clean up the prodigal gff | https://github.com/thackl/seq-scripts
gff-clean emales-prodigal.gff > emales.gff
```

--------------------------------

### Read PAF File (minimap2)

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads minimap/minimap2 PAF alignment files. Includes support for optional tagged fields. Can be used directly with gggenomes.

```r
# Read PAF file with alignment data
links <- read_paf(ex("emales/emales.paf"))

# Use in gggenomes
gggenomes(seqs = emale_seqs, links = links) +
  geom_seq() + geom_link()
```

--------------------------------

### Pick Specific Sequences

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `pick_seqs(1, c3)` to select individual sequences within bins. This allows for fine-grained control over which sequences are displayed.

```R
p %>% pick_seqs(1, c3)
```

--------------------------------

### Visualize comparative viral genomes with gggenomes

Source: https://github.com/thackl/gggenomes/blob/main/README.md

Uses the gggenomes package to combine gene, sequence, and link data into a multi-track plot with synchronized genome directions.

```R
library(gggenomes)

# to inspect the example data shipped with gggenomes
data(package="gggenomes")

gggenomes(
  genes = emale_genes, seqs = emale_seqs, links = emale_ava,
  feats = list(emale_tirs, ngaros=emale_ngaros, gc=emale_gc)) |> 
  add_sublinks(emale_prot_ava) |>
  sync() + # synchronize genome directions based on links
  geom_feat(position="identity", size=6) +
  geom_seq() +
  geom_link(data=links(2)) +
  geom_bin_label() +
  geom_gene(aes(fill=name)) +
  geom_gene_tag(aes(label=name), nudge_y=0.1, check_overlap = TRUE) +
  geom_feat(data=feats(ngaros), alpha=.3, size=10, position="identity") +
  geom_feat_note(aes(label="Ngaro-transposon"), data=feats(ngaros),
      nudge_y=.1, vjust=0) +
  geom_wiggle(aes(z=score, linetype="GC-content"), feats(gc),
      fill="lavenderblush4", position=position_nudge(y=-.2), height = .2) +
  scale_fill_brewer("Genes", palette="Dark2", na.value="cornsilk3")
  
ggsave("emales.png", width=8, height=4)
```

--------------------------------

### Parse and plot genome sequences

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Reads FASTA metadata and visualizes the first six genomes.

```R
library(tidyverse)
library(gggenomes)

# parse sequence length and some metadata from fasta file
emale_seqs <- read_fai("emales.fna") %>%
  extract(seq_desc, into = c("emale_type", "is_typespecies"), "=(\S+) \S+=(\S+)",
    remove=F, convert=T) %>%
  arrange(emale_type, length)

# plot the genomes - first six only to keep it simple for this example
emale_seqs_6 <- emale_seqs[1:6,]
p1 <- gggenomes(emale_seqs_6) +
 geom_seq() + geom_bin_label()
p1

pp(p1)
```

--------------------------------

### Perform BLAST Search and Parse Results

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Performs a BLASTp search and parses the results along with custom annotations from a FASTA file. Requires BLAST+ and Perl.

```sh
# mavirus.faa - published
blastp -query emales.faa -subject mavirus.faa -outfmt 7 > emales_mavirus-blastp.tsv
perl -ne 'if(/>(\S+) gene=(\S+) product=(.+)/){print join("\t", $1, $2, $3), "\n"}' mavirus.faa > mavirus.tsv
```

--------------------------------

### Align Genomes with Phylogenetic Tree

Source: https://context7.com/thackl/gggenomes/llms.txt

Combine a phylogenetic tree (`ggtree`) with a `gggenomes` plot using `pick_by_tree()`. This aligns the genome visualization to the tree structure, useful for comparative genomics.

```R
t + p %>% pick_by_tree(t) + plot_layout(widths = c(1, 5))
```

--------------------------------

### Sync Based on Shared Orthologs

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `sync()` with `add_clusters()` to automatically orient bins based on shared orthologs (COGs). This helps in visualizing conserved gene clusters across genomes.

```R
p %>% 
  add_clusters(emale_cogs) %>%
  sync() + labs(caption = "ortholog sync")
```

--------------------------------

### Calculate GC Content

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Calculates the GC content of a FASTA file and saves it as a TSV. Requires the seq-scripts tool.

```sh
seq-gc -Nbw 50 emales.fna > emales-gc.tsv
```

--------------------------------

### Visualize continuous data

Source: https://context7.com/thackl/gggenomes/llms.txt

Methods for plotting coverage or wiggle data along sequences using various geometric representations.

```r
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_coverage(aes(z = score), height = 0.5) +
  geom_seq()
```

```r
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score)) +
  geom_seq()
```

```r
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()
```

```r
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")
```

```r
gggenomes(seqs = emale_seqs, feats = emale_gc) +
  geom_wiggle(aes(z = score, color = score), geom = "linerange") +
  geom_seq() +
  scale_colour_viridis_b(option = "A")
```

--------------------------------

### File I/O Functions

Source: https://context7.com/thackl/gggenomes/llms.txt

Functions for reading and writing various genomic file formats.

```APIDOC
## File I/O Functions

### read_gff3 - Read GFF3/GFF2/GTF Files

Reads feature annotations from GFF3 format files (with some GFF2/GTF support).

```r
# Read GFF3 file
genes <- read_gff3(ex("emales/emales.gff"))

# Filter by type during import
cds_only <- read_gff3(ex("emales/emales.gff"), types = "CDS")

# Read compressed files
genes <- read_gff3(ex("gorg/gorg.gff.xz"))

# Keep original attributes column
genes_full <- read_gff3(ex("emales/emales.gff"), keep_attr = TRUE)
```

### read_bed - Read BED Files

Reads feature data from BED format files, automatically converting 0-based coordinates to 1-based.

```r
# Read BED file (coordinates converted to 1-based)
gc_content <- read_bed(ex("emales/emales-gc.bed"))

# Add extra columns
gc_content <- read_bed(
  ex("emales/emales-gc.bed"),
  col_names = c(def_names("bed"), "score")
)
```

### read_paf - Read PAF Files (minimap2)

Reads minimap/minimap2 PAF alignment files including optional tagged fields.

```r
# Read PAF file with alignment data
links <- read_paf(ex("emales/emales.paf"))

# Use in gggenomes
gggenomes(seqs = emale_seqs, links = links) +
  geom_seq() + geom_link()
```

### read_blast - Read BLAST Output

Reads BLAST tab-separated output format (outfmt 6/7).

```r
# Read BLAST output
blast_hits <- read_blast(ex("gorg/gorg-pads-defense.o6"))

# Swap query and subject if needed
blast_hits <- read_blast(ex("gorg/gorg-pads-defense.o6"), swap_query = TRUE)
```

### read_gbk - Read GenBank Files

Reads GenBank flat files (.gb/.gbk/.gbff) using a Perl-based converter.

```r
# Read GenBank file
genes <- read_gbk("genome.gbk")

# Filter by feature type
cds <- read_gbk("genome.gbk", types = "CDS")
```

### read_vcf - Read VCF Files

Reads Variant Call Format files for mutation/variant data.

```r
# Read VCF file
variants <- read_vcf("variants.vcf")

# Parse INFO column into separate columns
variants <- read_vcf("variants.vcf", parse_info = TRUE)

# Use with geom_variant
gggenomes(seqs = seqs, feats = variants) +
  geom_seq() +
  geom_variant(aes(color = type))
```

### read_seq_len / read_fai - Read Sequence Index

Reads sequence length information from various formats.

```r
# Read from fasta index
seqs <- read_fai(ex("emales/emales.fna.seqkit.fai"))

# Auto-detect format (fasta, gbk, gff3)
seqs <- read_seq_len(ex("emales/emales.fna"))
```

### write_gff3 - Write GFF3 Files

Writes feature data back to GFF3 format.

```r
# Write genes to GFF3
filename <- tempfile(fileext = ".gff")
write_gff3(emale_genes, filename, emale_seqs, id_var = "feat_id")
```
```

--------------------------------

### Draw sequences and contigs

Source: https://context7.com/thackl/gggenomes/llms.txt

Functions for rendering sequence tracks, handling multiple contigs per bin, and adjusting layout parameters.

```r
gggenomes(seqs = emale_seqs) +
  geom_seq() +
  geom_bin_label()
```

```r
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() +
  geom_seq_label()
```

```r
gggenomes(seqs = seqs, wrap = 300) +
  geom_seq() +
  geom_bin_label() +
  geom_seq_label()
```

```r
gggenomes(seqs = seqs, spacing = 100) +
  geom_seq() +
  geom_bin_label() +
  geom_seq_label()
```

--------------------------------

### Manage data tracks

Source: https://context7.com/thackl/gggenomes/llms.txt

Functions to add feature annotations, alignment links, and sub-features to an existing gggenomes object.

```r
gggenomes(seqs = emale_seqs) %>%
  add_feats(repeats = emale_tirs) +
  geom_seq() + geom_feat()
```

```r
gggenomes(seqs = emale_seqs) %>%
  add_links(links = emale_ava) +
  geom_seq() + geom_link()
```

```r
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()
```

--------------------------------

### Highlight Regions with Locate

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `locate()` to add loci of interest as a new track for highlighting. This function is useful for drawing attention to specific genomic regions within the visualization.

```R
gggenomes(g0, s1, f1, wrap = 2e5) %>%
  locate(.track_id = feats) + 
  geom_seq() + geom_bin_label() + 
  geom_feat(data = feats(loci), color = "plum3") + 
  geom_point(aes(x = x, y = y, color = system), data = feats()) + 
  scale_color_brewer(palette = "Dark2")
```

--------------------------------

### Read BLAST Output

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads BLAST tab-separated output format (outfmt 6/7). Allows swapping query and subject if necessary.

```r
# Read BLAST output
blast_hits <- read_blast(ex("gorg/gorg-pads-defense.o6"))

# Swap query and subject if needed
blast_hits <- read_blast(ex("gorg/gorg-pads-defense.o6"), swap_query = TRUE)
```

--------------------------------

### Cluster Protein Sequences

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Converts a FASTA file to amino acid sequences, clusters them using MMseqs2, and extracts cluster IDs. Requires Prodigal, MMseqs2, and cluster-ids.

```sh
gff2cds --aa --type CDS --source Prodigal_v2.6.3 --fna emales.fna emales.gff > emales.faa
mmseqs easy-cluster emales.faa emales-mmseqs /tmp -e 1e-5 -c 0.7; 
cluster-ids -t "cog%03d" < emales-mmseqs_cluster.tsv > emales-cogs.tsv
```

--------------------------------

### Shift Bins Manually

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `shift()` to manually move bins horizontally by specified amounts. This is useful for adjusting the layout and spacing of genomic elements.

```R
p1 <- p0 |> shift(2:3, by = c(-8000, 10000))
```

--------------------------------

### Read GenBank File

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads GenBank flat files (.gb/.gbk/.gbff) using an internal Perl-based converter. Supports filtering by feature type during import.

```r
# Read GenBank file
genes <- read_gbk("genome.gbk")

# Filter by feature type
cds <- read_gbk("genome.gbk", types = "CDS")
```

--------------------------------

### Remove Bins

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `pick(-B)` to remove specific bins from the visualization. This allows for selective display of genomic data.

```R
p %>% pick(-B)
```

--------------------------------

### Read GFF3 File

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads feature annotations from GFF3 format files. Supports GFF2/GTF with some limitations. Compressed files can also be read.

```r
# Read GFF3 file
genes <- read_gff3(ex("emales/emales.gff"))

# Filter by type during import
cds_only <- read_gff3(ex("emales/emales.gff"), types = "CDS")

# Read compressed files
genes <- read_gff3(ex("gorg/gorg.gff.xz"))

# Keep original attributes column
genes_full <- read_gff3(ex("emales/emales.gff"), keep_attr = TRUE)
```

--------------------------------

### Visualize terminal inverted repeats

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Imports TIR data and adds it as features to the genome plot.

```R
emale_tirs_paf <- read_paf("emales-tirs.paf") %>%
  filter(seq_id1 == seq_id2 & start1 < start2 & map_length > 99 & de < 0.1)
emale_tirs <- bind_rows(
  select(emale_tirs_paf, seq_id=seq_id1, start=start1, end=end1, de),
  select(emale_tirs_paf, seq_id=seq_id2, start=start2, end=end2, de))

p3 <- gggenomes(emale_seqs_6, emale_genes, emale_tirs) +
  geom_seq() + geom_bin_label() +
  geom_feature(size=5) +
  geom_gene(aes(fill=gc_cont)) +
  scale_fill_distiller(palette="Spectral")
p3

pp(p3)
```

--------------------------------

### Write GFF3 File

Source: https://context7.com/thackl/gggenomes/llms.txt

Writes feature data back to GFF3 format. Requires feature data, a filename, sequence information, and optionally an ID variable.

```r
# Write genes to GFF3
filename <- tempfile(fileext = ".gff")
write_gff3(emale_genes, filename, emale_seqs, id_var = "feat_id")
```

--------------------------------

### Draw Gene Models with geom_gene

Source: https://context7.com/thackl/gggenomes/llms.txt

Draws gene models, including multi-exon features, CDS, and mRNAs. Supports coloring by GC content and strand-based positioning.

```r
# Basic gene drawing
gggenomes(genes = emale_genes) +
  geom_gene()
```

```r
# Genes colored by GC content with strand-based positioning
gggenomes(genes = emale_genes) +
  geom_gene(aes(fill = as.numeric(gc_content)), position = "strand") +
  scale_fill_viridis_b()
```

```r
# Spliced genes with UTRs
g0 <- read_gff3(ex("eden-utr.gff"))
gggenomes(genes = g0) +
  geom_gene(position = "pile")
```

```r
# Fine control over gene model aesthetics
gggenomes(genes = g0) +
  geom_gene(aes(fill = type),
    position = "pile",
    size = 2,
    shape = c(4, 3),           # arrow tip dimensions
    rna_size = 2,              # non-coding region size
    intron_shape = 4,          # intron kink
    stroke = 0,
    cds_aes = aes(fill = "black"),
    rna_aes = aes(fill = fill),
    intron_aes = aes(colour = fill, stroke = 2)
  ) +
  scale_fill_viridis_d()
```

--------------------------------

### Read Sequence Index

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads sequence length information from various index formats like FASTA index (.fai) or auto-detects from FASTA, GBK, or GFF3 files.

```r
# Read from fasta index
seqs <- read_fai(ex("emales/emales.fna.seqkit.fai"))

# Auto-detect format (fasta, gbk, gff3)
seqs <- read_seq_len(ex("emales/emales.fna"))
```

--------------------------------

### Zoom in on Loci with Focus

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `focus()` to extract and zoom into loci containing features of interest. This function is ideal for detailed examination of specific genomic regions.

```R
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")
```

--------------------------------

### Pull Specific Tracks

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `pull_feats()`, `pull_seqs()`, and `pull_genes()` to extract data from specific tracks. Tracks can be accessed by their default name, ID, or position.

```R
gg %>% pull_feats()           # first feat track (not "genes")
gg %>% pull_feats(feats)      # by id
gg %>% pull_feats(1)          # by position
gg %>% pull_seqs()            # seqs track
gg %>% pull_genes()           # genes track
```

--------------------------------

### Manually Flip Bins or Sequences

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `flip()` to manually reverse the orientation of specified bins or sequences. This is useful for correcting or adjusting the strand orientation of genomic regions.

```R
p %>% 
  add_links(emale_ava) %>%
  flip(4:6) + labs(caption = "manual flip")
```

--------------------------------

### Add Gene and Feature Labels

Source: https://context7.com/thackl/gggenomes/llms.txt

Adds text labels to genes or features. Supports custom labels for genes and notes for features, with options for positioning.

```r
# Gene labels
gggenomes(genes = emale_genes) +
  geom_gene() +
  geom_gene_label(aes(label = name))

# Feature labels with notes
gggenomes(seqs = emale_seqs, feats = emale_ngaros) +
  geom_seq() +
  geom_feat(color = "darkred") +
  geom_feat_note(aes(label = type), nudge_y = 0.1)
```

--------------------------------

### Scales and Labels

Source: https://context7.com/thackl/gggenomes/llms.txt

Functions for customizing genomic scales and adding labels to plots.

```APIDOC
## Scales and Labels

### scale_x_bp - Genomic X-Scale

Default scale for genomic x-axis with human-readable base pair labels.

```r
# Default scale (automatic)
gggenomes(emale_genes) + geom_gene()

# Customize labels with suffix
gggenomes(emale_genes) + geom_gene() +
  scale_x_bp(suffix = "bp", sep = " ")

# Set explicit limits
gggenomes(emale_genes) + geom_gene() +
  scale_x_bp(limits = c(0, 3e4))
```

### geom_gene_label / geom_feat_label - Add Labels

Add text labels to genes, features, or links.

```r
# Gene labels
gggenomes(genes = emale_genes) +
  geom_gene() +
  geom_gene_label(aes(label = name))

# Feature labels with notes
gggenomes(seqs = emale_seqs, feats = emale_ngaros) +
  geom_seq() +
  geom_feat(color = "darkred") +
  geom_feat_note(aes(label = type), nudge_y = 0.1)
```
```

--------------------------------

### Integrate BLAST Hits and Transposons into Genome Plot

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Reads BLAST results and GFF annotations for transposons, then adds them as features and subfeatures to a gggenomes plot. Requires the gggenomes package.

```R
emale_blast <- read_blast("emales_mavirus-blastp.tsv")
emale_blast %<>%
  filter(evalue < 1e-3) %>%
  select(feature_id=qaccver, start=qstart, end=qend, saccver) %>%
  left_join(read_tsv("mavirus.tsv", col_names = c("saccver", "blast_hit", "blast_desc")))

# manual annotations by MFG
emale_transposons <- read_gff("emales-manual.gff", types = c("mobile_element"))


p7 <- gggenomes(emale_seqs_6, emale_genes, emale_tirs, emale_links) %>%
  add_features(emale_gc) %>%
  add_clusters(genes, emale_cogs) %>%
  add_features(emale_transposons) %>%
  add_subfeatures(genes, emale_blast, transform="aa2nuc") %>%
  flip_bins(3:5) + 
  geom_feature(aes(color="integrated transposon"),
    use_features(emale_transposons), size=7) + 
  geom_seq() + geom_bin_label() +
  geom_link(offset = c(0.3, 0.2), color="white", alpha=.3) +
  geom_feature(aes(color="terminal inverted repeat"), use_features(features),
    size=4) +
  geom_gene(aes(fill=cluster_label)) +
  geom_feature(aes(color=blast_desc), use_features(emale_blast), size=2,
    position="pile") + 
  geom_ribbon(aes(x=(x+xend)/2, ymax=y+.24, ymin=y+.38-(.4*score),
    group=seq_id, linetype="GC-content"), use_features(emale_gc),
                       fill="blue", alpha=.5) +
  scale_fill_brewer("Conserved genes", palette="Set3") +
  scale_color_viridis_d("Blast hits & Features", direction = -1) +
  scale_linetype("Graphs") +
  ggtitle(expression(paste("Endogenous mavirus-like elements of ",
  italic("C. burkhardae"))))

p7

pp(p7)
```

--------------------------------

### Define plot export helper function

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

A utility function to save ggplot objects as PNG files using Cairo graphics.

```R
pp <- function(x=NA, fmt="emales-%s.png"){
  out <- as_label(enexpr(x))
  out <- sprintf(fmt, out)
  print(paste0("generating ", out))
  ggsave(out, x, type="cairo", width=18, height=8)
}
```

--------------------------------

### Read BED File

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads feature data from BED format files. Automatically converts 0-based coordinates to 1-based. Extra columns can be added.

```r
# Read BED file (coordinates converted to 1-based)
gc_content <- read_bed(ex("emales/emales-gc.bed"))

# Add extra columns
gc_content <- read_bed(
  ex("emales/emales-gc.bed"),
  col_names = c(def_names("bed"), "score")
)
```

--------------------------------

### Detect terminal inverted repeats

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Uses seqkit and minimap2 to identify and filter terminal inverted repeats.

```sh
# split into one genome per file | https://bioinf.shenwei.me/seqkit/
seqkit split -i emales.fna  
# self-align opposite strands                        
for fna in `ls emales.fna.split/*.fna`; do
  minimap2 -c -B5 -O6 -E3 --rev-only $fna $fna > $fna.paf;
done;
cat emales.fna.split/*.paf > emales-tirs.paf
```

--------------------------------

### Add Protein-Protein Alignments

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `add_sublinks` to add protein-protein alignments as sublinks to the genome plot. Requires `geom_gene()` and `geom_link()`.

```R
gggenomes(emale_genes) %>%
  add_sublinks(emale_prot_ava) + 
  geom_gene() + geom_link()
```

--------------------------------

### Read VCF File

Source: https://context7.com/thackl/gggenomes/llms.txt

Reads Variant Call Format files for mutation/variant data. Can parse the INFO column into separate columns and be used with geom_variant.

```r
# Read VCF file
variants <- read_vcf("variants.vcf")

# Parse INFO column into separate columns
variants <- read_vcf("variants.vcf", parse_info = TRUE)

# Use with geom_variant
gggenomes(seqs = seqs, feats = variants) +
  geom_seq() +
  geom_variant(aes(color = type))
```

--------------------------------

### Plot genomic variants

Source: https://context7.com/thackl/gggenomes/llms.txt

Visualization of variant call data with support for custom shapes, positioning, and text labels.

```r
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),
  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))

gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant()
```

```r
gggenomes(seqs = s1, feats = f1) +
  geom_seq() +
  geom_variant(aes(shape = type), offset = -0.1) +
  scale_shape_variant() +
  geom_bin_label()
```

```r
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()
```

```r
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()
```

--------------------------------

### Align Bins to Target Gene

Source: https://context7.com/thackl/gggenomes/llms.txt

Aligns all bins to a specific target gene by filtering and shifting.

```r
mcp <- emale_genes |>
  dplyr::filter(name == "MCP") |
  dplyr::group_by(seq_id) |
  dplyr::slice_head(n = 1)
p2 <- p0 |> shift(all_of(mcp$seq_id), by = -mcp$start) +
  geom_gene(data = genes(name == "MCP"), fill = "#01b9af")

p0 + p1 + p2
```

--------------------------------

### Genomic X-Scale Customization

Source: https://context7.com/thackl/gggenomes/llms.txt

Customizes the genomic x-axis scale with human-readable base pair labels. Allows setting suffixes, separators, and explicit limits.

```r
# Default scale (automatic)
gggenomes(emale_genes) + geom_gene()

# Customize labels with suffix
gggenomes(emale_genes) + geom_gene() +
  scale_x_bp(suffix = "bp", sep = " ")

# Set explicit limits
gggenomes(emale_genes) + geom_gene() +
  scale_x_bp(limits = c(0, 3e4))
```

--------------------------------

### Add GC Content to Genome Plot

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Reads GC content data and adds it as a ribbon to a gggenomes plot. Requires the thacklr R package.

```R
emale_gc <- thacklr::read_bed("emales-gc.tsv") %>%
  rename(seq_id=contig_id)

p5 <- p4 %>% add_features(emale_gc)
p5 <- p5 + geom_ribbon(aes(x=(x+xend)/2, ymax=y+.24, ymin=y+.38-(.4*score),
    group=seq_id, linetype="GC-content"), use_features(emale_gc),
                       fill="blue", alpha=.5)

p5

pp(p5)
```

--------------------------------

### geom_link - Draw Links Between Genomes

Source: https://context7.com/thackl/gggenomes/llms.txt

Draws connections between genomes representing alignments or syntenic regions. Available variants include `geom_link()` (filled polygons), `geom_link_curved()` (bezier-style), and `geom_link_line()` (connecting lines).

```APIDOC
## geom_link - Draw Links Between Genomes

### Description
`geom_link()` draws connections between genomes representing alignments or syntenic regions. Available variants include `geom_link()` (filled polygons), `geom_link_curved()` (bezier-style), and `geom_link_line()` (connecting lines).

### Method
`geom_link()`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **offset** (numeric) - Offset for the links.

### Request Example
```r
p0 <- gggenomes(seqs = emale_seqs, links = emale_ava) + geom_seq()

# Default polygon links
p1 <- p0 + geom_link()
```

### Response
N/A (R object)
```

--------------------------------

### Draw Links Between Genomes with geom_link

Source: https://context7.com/thackl/gggenomes/llms.txt

Draws connections between genomes representing alignments or syntenic regions. Variants include polygon, curved, and line links.

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

# Default polygon links
p1 <- p0 + geom_link()
```

--------------------------------

### Add Gene Clusters (COGs)

Source: https://context7.com/thackl/gggenomes/llms.txt

Use `add_clusters` to add gene clusters (COGs) to the genome plot. Requires `sync()`, `geom_link()`, `geom_seq()`, and `geom_gene()` with aesthetic mapping for fill.

```R
gggenomes(emale_genes, emale_seqs) %>%
  add_clusters(emale_cogs) %>%
  sync() + 
  geom_link() + 
  geom_seq() + 
  geom_gene(aes(fill = ifelse(is.na(cluster_id), NA, 
    stringr::str_glue("{cluster_id} [{cluster_size}]")))) + 
  scale_fill_discrete(name = "COGs")
```

--------------------------------

### Add Gene Clusters to Genome Plot

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Reads cluster data, processes it for plotting, and adds gene clusters to a gggenomes plot. Uses dplyr and forcats for data manipulation.

```R
emale_cogs <- read_tsv("emales-cogs.tsv", col_names = c("feature_id", "cluster_id", "cluster_n"))
emale_cogs %<>% mutate(
  cluster_label = paste0(cluster_id, " (", cluster_n, ")"),
  cluster_label = fct_lump_min(cluster_label, 5, other_level = "rare"),
  cluster_label = fct_lump_min(cluster_label, 15, other_level = "medium"),
  cluster_label = fct_relevel(cluster_label, "rare", after=Inf))
emale_cogs


p6 <- gggenomes(emale_seqs_6, emale_genes, emale_tirs, emale_links) %>%
  add_features(emale_gc) %>%
  add_clusters(genes, emale_cogs) %>%
  flip_bins(3:5) + 
  geom_seq() + geom_bin_label() +
  geom_feature(size=5, data=use_features(features)) +
  geom_gene(aes(fill=cluster_label)) +
  geom_link() +
  geom_ribbon(aes(x=(x+xend)/2, ymax=y+.24, ymin=y+.38-(.4*score),
    group=seq_id, linetype="GC-content"), use_features(emale_gc),
                       fill="blue", alpha=.5) +
  scale_fill_brewer("Conserved genes", palette="Set3")

p6

pp(p6)
```

--------------------------------

### Alignment Functions

Source: https://context7.com/thackl/gggenomes/llms.txt

Functions for aligning and synchronizing genomic features within plots.

```APIDOC
## Alignment Functions

### Align all bins to target gene

This demonstrates aligning bins to a specific target gene by manually shifting.

```r
mcp <- emale_genes |> dplyr::filter(name == "MCP") |> dplyr::group_by(seq_id) |> dplyr::slice_head(n = 1)
p2 <- p0 |> shift(all_of(mcp$seq_id), by = -mcp$start) + geom_gene(data = genes(name == "MCP"), fill = "#01b9af")

p0 + p1 + p2
```

### Align using align() function

Demonstrates left-aligning, right-aligning, and center-aligning features using the `align()` function.

```r
# Left-align on MCP gene
p |> align(name == "MCP")

# Right-align on MCP gene
p |> align(name == "MCP", .justify = "right")

# Center-align on multiple genes after syncing
p |> sync() |> align(name %in% c("MCP", "pri-hel"), .justify = "center")
```
```

--------------------------------

### Save Processed Data

Source: https://github.com/thackl/gggenomes/blob/main/data-raw/emales.org

Saves various processed genomic data objects using the usethis::use_data function for later use in R.

```R
usethis::use_data(emale_seqs, overwrite=TRUE)
usethis::use_data(emale_genes, overwrite=TRUE)
usethis::use_data(emale_links, overwrite=TRUE)
usethis::use_data(emale_tirs, overwrite=TRUE)
usethis::use_data(emale_transposons, overwrite=TRUE)
usethis::use_data(emale_gc, overwrite=TRUE)
usethis::use_data(emale_blast, overwrite=TRUE)
usethis::use_data(emale_cogs, overwrite=TRUE)
```