BLAST comparison rings

ggplasmidZY can display nucleotide similarity comparisons as one or more concentric rings around a circular plasmid or genome map.

Each BLAST ring represents one comparison sequence. The ring position follows the coordinates of the map backbone, while the color intensity represents percent identity. Higher-identity alignments are shown with stronger colors.

Basic automatic comparison

Automatic comparisons use the local NCBI BLAST+ blastn executable. The map sequence must be available from the GenBank ORIGIN sequence or from a FASTA input.

library(ggplasmidZY)

p <- ggplasmid(
  gbk = "reference.gbk",
  name = "Reference plasmid",
  blast_rings = list(
    comparison_a = list(
      label = "Comparison A",
      sequence = "comparison_a.fasta"
    ),
    comparison_b = list(
      label = "Comparison B",
      sequence = "comparison_b.fasta"
    )
  ),
  blast_plotting_mode = "region",
  blast_min_identity = 90,
  blast_min_alignment_length = 100,
  legend_position = "right"
)

p

The sequence entry can be a FASTA path, a nucleotide sequence, a data frame with a sequence column, or a Biostrings XStringSet.

NCBI BLAST+ must be installed separately and blastn must be available on the system PATH. A custom executable path can be supplied with blastn.

p <- ggplasmid(
  gbk = "reference.gbk",
  blastn = "C:/path/to/blastn.exe",
  blast_rings = list(
    comparison = list(
      label = "Reference sequence",
      sequence = "comparison.fasta"
    )
  )
)

Using precomputed BLAST results

BLAST results can also be calculated separately with blast_pairwise() and then supplied to ggplasmid().

hits <- blast_pairwise(
  query = "reference.fasta",
  subject = "comparison.fasta",
  perc_identity = 90,
  evalue = 1e-10,
  num_threads = 4
)

p <- ggplasmid(
  gbk = "reference.gbk",
  blast_rings = list(
    comparison = list(
      label = "Comparison",
      hits = hits
    )
  ),
  blast_reference = "query",
  blast_plotting_mode = "region"
)

p

blast_pairwise() uses direct query/subject mode and does not require a persistent BLAST database.

BLAST plotting modes

HSP mode

blast_plotting_mode = "hsp"

Displays each qualifying high-scoring pair separately. This mode preserves the individual BLAST alignment segments and is useful when the detailed alignment structure is important.

The default minimum identity is 0%.

Region mode

blast_plotting_mode = "region"

Combines overlapping alignments into reference-coordinate regions. When several hits overlap, the region is assigned the highest-priority alignment according to percent identity, bit score, and alignment length.

The default minimum identity is 90%.

This is usually the clearest mode for comparing whole plasmids or genomes.

Gene mode

blast_plotting_mode = "gene"

Colors annotated features when they satisfy the BLAST coverage requirement.

p <- ggplasmid(
  gbk = "reference.gbk",
  blast_rings = list(
    comparison = list(
      label = "Comparison",
      sequence = "comparison.fasta",
      mode = "gene",
      min_identity = 80,
      min_gene_coverage = 0.80
    )
  )
)

The default minimum identity is 80%, and the default minimum feature coverage is 80%. Gene mode requires annotation features with valid start and end coordinates.

Multiple rings and per-ring settings

Shared settings can be specified in the main ggplasmid() call. Individual rings can override them.

p <- ggplasmid(
  gbk = "reference.gbk",
  blast_plotting_mode = "region",
  blast_min_identity = 90,
  blast_rings = list(
    close_reference = list(
      label = "Close reference",
      sequence = "close_reference.fasta",
      colour = "#D73027"
    ),
    distant_reference = list(
      label = "Distant reference",
      sequence = "distant_reference.fasta",
      min_identity = 70,
      colour = "#4575B4",
      order = 2
    )
  )
)

Each ring must contain exactly one of:

• hits: a data frame returned by blast_pairwise()
• sequence: a sequence input used for automatic BLAST

Each ring also requires a unique label.

Colors and identity legends

Ring base colors are assigned from the selected ggsci palette.

p <- ggplasmid(
  gbk = "reference.gbk",
  blast_palette = "npg",
  blast_rings = list(
    comparison = list(
      label = "Comparison",
      sequence = "comparison.fasta"
    )
  )
)

Manual colors can be supplied in ring order:

p <- ggplasmid(
  gbk = "reference.gbk",
  blast_color_manual = c("#D73027", "#4575B4"),
  blast_rings = list(
    first = list(label = "First", sequence = "first.fasta"),
    second = list(label = "Second", sequence = "second.fasta")
  )
)

A ring-level colour setting overrides blast_color_manual.

Each ring has its own horizontal identity legend, ranging from the effective minimum identity threshold to 100%.

Ring layout

BLAST rings are drawn outside the GC tracks and inside the gene ring. Their positions and sizes are calculated automatically.

The layout can be adjusted with:

ggplasmid(
  gbk = "reference.gbk",
  blast_rings = list(
    comparison = list(
      label = "Comparison",
      sequence = "comparison.fasta"
    )
  ),
  blast_radius = NULL,
  blast_height = NULL,
  blast_spacing = 0.01
)

blast_radius, blast_height, and blast_spacing control the base radius, ring thickness, and distance between rings. Explicit dimensions that overlap the GC tracks or gene ring produce an error.