0.16.6 documentation

Site guide · find your task

Setup and learning paths

HomeInstall and prepare the environmentChoose your learning module

Module I · Chord

1.1 Tables and field meanings1.2 Produce and import comparisons1.3 Build the layers step by step1.4 Direction, curvature and clearance1.5 Filter and summarize links1.6 Full source-file workflow1.7 Complete chord showcase

Module II · Collinear

2.1 Reuse chord input tables2.2 Switch coordinates and add layers2.3 Routes, clearance and the ruler2.4 Compare CDS neighbourhoods2.5 Focus, anchors and segments2.6 Complete collinear showcase

Module III · Plasmid

3.1 DNA, annotations and 13 references3.2 From a circle to annotation layers3.3 Features, primers and restriction3.4 Thirteen plasmid references3.5 Complete plasmid cases

Consult as needed · Data and layers

Prepare tables and coordinatesImport and convert dataImport nucleotide and protein alignmentsProject protein intervals to genomic coordinatesFeatures, stacking and genomic decorationLabels and local placementQuantitative tracksMappings, scales, guides and themesSet values by sequence and strandCommon adjustments and grammarExport, preview and diagnostics

Learning map and reference

Articles and complete workflowsFunction referenceReproducible galleryFrequently asked questionsMigrate to the candidate APITerminology and design sourcesDevelopment status and changes

Import nucleotide and protein alignments

On this page

• Prepare this page
• Use the default tabular columns
• File layout and minimal plotting fields differ
• Read BLASTp with explicit coordinate units
• Sources and limits
• Check your result

Use standard BLAST tabular output without the historical custom 17-column layout. Distinguish file fields, minimal plotting roles and nucleotide versus protein units.

Prepare this page

In a fresh R session, run the code below, then follow this page in order. Colours and layout are optional display choices; inputs select only the fields needed. For file-based examples, first extract the input bundle so the working directory contains examples/.

Code

library(ggchord)
library(dplyr)

Use the default tabular columns

The historical custom list of 17 fields is unnecessary. Use standard tabular output:

Code

blastn -query query.fna -subject subject.fna -outfmt 6 -out result.tsv
blastp -query proteins.faa -subject reference.faa -outfmt 7 -out result.tsv

Format 6 is a table; 7 adds comments. Without a custom field list both use 12 default fields. Omitting -outfmt entirely produces pairwise text, which this tabular reader does not parse. Fields are query ID, subject ID, pident, length, mismatch, gapopen, qstart, qend, sstart, send, evalue, bitscore. Their identifier roles become qaccver/saccver; values are preserved and need not be accession versions. See the NCBI format documentation.

File layout and minimal plotting fields differ

Twelve file columns do not require twelve plotting columns. After the preparation code above, try the source-backed records:

Code

blast_source <- read_blast("examples/blastn-standard/MT108731.1__MT118296.1.tsv")
blast_links <- blast_source |>
  select(qaccver, saccver, qstart, qend, sstart, send)
# A six-column table is sufficient for drawing; extra fields stay in blast_source.
custom_path <- tempfile(fileext = ".tsv")
write.table(blast_links, custom_path, sep = "\t", quote = FALSE, row.names = FALSE, col.names = FALSE)
custom_source <- read_blast(custom_path, format = "custom", col_names = names(blast_links))
custom_links <- custom_source |>
  select(all_of(names(blast_links)))
unlink(custom_path)

blast_source retains statistics and provenance; blast_links has six endpoint roles. Identity requires pident only when mapped/filtered; alignment-length filters or weights require length. qlen/slen support the corresponding coverage calculations. They are not general plotting requirements. A custom headerless layout requires explicit col_names; arbitrary six-column meanings are not guessed. Use as_ggchord_link(x, mapping = ...) for an already-read non-BLAST table; see format conversion.

Files in examples/blastn-standard/ retain historical HSP rows and their first 12 values. They are column conversions, not new BLAST runs. Old .o7 inputs are unchanged; the conversion script and hashes record that distinction.

Read BLASTp with explicit coordinate units

This real BLASTP 2.9.0+ output and query CDS annotation come from the public EMALE tutorial. Retain the original table, then select sufficiently long, low-evalue query HSPs with complete known CDS mappings.

Code

protein_source <- read_blast("examples/format-inputs/emales-mavirus-blastp.tsv", source_file = TRUE)
emale_source <- read_gff3("examples/format-inputs/emales-BVI_023A.gff3", source_file = TRUE)
# The source declares complete Prodigal CDS and translation table 11.
emale_coding <- emale_source |>
  filter(grepl("partial=00", attributes)) |>
  select(feature_id, accver, start, end, strand, phase)
emale_cds <- build_ggchord_cds(emale_coding, genetic_code = 11)
# Keep strong HSPs whose query protein has a known complete CDS.
# Gaps are retained: projecting one query span does not assert an ungapped pair.
protein_kept <- protein_source |>
  filter(qaccver %in% emale_coding$feature_id, evalue <= 1e-10, length >= 50) |>
  arrange(desc(bitscore))
selected_hsp <- protein_kept |>
  slice_head(n = 1)
query_interval <- tibble(
  feature_id = "query_HSP", parent_id = selected_hsp$qaccver,
  start = selected_hsp$qstart, end = selected_hsp$qend
)
projected_query <- project_ggchord_features(query_interval, emale_cds)
# Subject projection additionally requires its own CDS map; it is not guessed from an accession.

Metric	Observed output
Original BLASTp HSPs	2948
Complete query CDS records	24
Query HSPs retained by the explicit filter	3
Selected query start (aa)	50
Selected query end (aa)	289
Projected query-span rows	1

BLASTp endpoints are amino-acid coordinates. This example projects the query HSP span into the known CDS’s genomic coordinates, retaining strand and phase. A gapped HSP still has a projectable query span; that envelope is not a base-by-base nucleotide correspondence. Weak hits, gap counts and statistics remain in the source.

Projecting both ends requires the subject’s own CDS map. It cannot be inferred from an accession, maximum endpoint or annotation name. The ungapped = TRUE assertion for project_ggchord_links() needs evidence. The projection tutorial uses two real plasmid CDS with identical oriented DNA to demonstrate a justified ungapped two-ended case.

Native protein backbones with aa axes are outside this version. For blastx and tblastn, check each endpoint’s units independently. Parsing does not establish that a table can be drawn directly in genomic bp coordinates.

Sources and limits

Original EMALE records come from the public gggenomes data/tutorial. Only data records are reused; all figures are drawn with ggchord, without copying upstream figures or plotting code. The input bundle’s sources.json records URLs, archive members, line ranges, hashes and selection. Parsing neither reruns alignments nor establishes biological function.

Check your result

A basic link table needs six fields. BLASTp reading retains aa coordinates; use a supported CDS mapping before drawing on this version’s bp axes.

Continue: CDS coordinate projection →