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

Prepare tables and coordinates

On this page

• Prepare this page
• Tables
• Coordinate contract
• Import original records
• Validate, clean, prepare
• Inspect a problematic input and its repair report
• Declare genome and contig keys
• Minimal input and protein alignments
• Check your result

Turn file observations into plotting roles. Check minimal fields and coordinates, then use validation reports to decide on cleaning; do not guess missing lengths or strands.

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/.

Preparation code — run once on this page

Code

library(ggchord)
library(dplyr)
data(seq_data_example)
data(ribbon_data_example)
data(gene_data_example)
seqs <- seq_data_example |>
  select(accver, length)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send)
# The fixture preserves biological strands separately from its old display strands.
genes <- gene_data_example |>
  transmute(accver, start, end, strand = source_strand)

Tables

Input	Required fields	Meaning
Sequence	accver, length	Unique ID; positive full length in bp
Interval link	qaccver, saccver, qstart, qend, sstart, send	Query and subject anchors
Gene	accver, start, end, strand	Known +/-; optional anno
Feature	accver, start, end, strand or declared direction	May retain unknown strand; optional type, label, feature_id

Identifiers may be arbitrary strings. Accession versions are preserved exactly. pident and alignment length are optional unless a mapping, filter or statistic needs them. A feature interval does not imply a sequence’s full length.

Coordinate contract

Genomic coordinates are one-based, inclusive bp. BED/PAF readers convert their source conventions; do not convert twice. Gene endpoints are ordered with strand stored separately; link endpoint order may encode direction. A one-bp link without direction evidence stays unknown. Unknown strand is never silently changed to +; use geom_feature() instead of the strict gene layer.

Amino-acid coordinates require explicit CDS projection. Native Cartesian layout units, genomic bp, angles in degrees, physical mm and track value units are different domains. See the full data contract.

Import original records

Run this repository-only example from its root. Original files are not rewritten.

Code

seq_files <- read_fasta_lengths(files = "examples/fasta/*.fna", source_file = TRUE)
link_files <- read_blast(files = "examples/blastn-standard/*.tsv", source_file = TRUE)
feature_files <- read_gff3(files = "examples/gff3/*.gff3", unstranded = "keep", source_file = TRUE)

read_genbank() retains record/feature provenance and segmented locations. read_bed() and read_paf() retain their conversion metadata. as_ggchord_seq(), as_ggchord_feature() and as_ggchord_link() adapt supported S4 objects; provide full lengths and IDs explicitly when the object lacks them. file and files both accept path vectors or globs; repeated resolved paths are read once in first-occurrence order. Choose one clear entry for a workflow. Missing sequence or homology data must be supplied by the analyst, not invented by the plotting layer.

Validate, clean, prepare

After this page’s preparation code:

Code

validation <- validate_ggchord_data(seqs, links, genes)
cleaned <- clean_ggchord_data(seqs, links, genes)
prepared <- prepare_ggchord_data(seqs, links, features = list(genes = genes))

Validation reports issues; cleaning makes explicit repairs with a report. Preparation combines workflow steps without inferring biological membership. Inspect validation, cleaned$report and prepared$report before plotting. source_row in geometry refers to the resolved layer input, while .source_line means a physical file line; GenBank has separate record/feature provenance. Aggregates may have source_rows and .length_estimated flags. Preserve these when filtering or merging links.

Inspect a problematic input and its repair report

Code

# Deliberately corrupt copies to demonstrate diagnostics; original rows remain intact.
problem_links <- ribbon_data_example |>
  slice_head(n = 2) |>
  select(qaccver, saccver, qstart, qend, sstart, send, pident) |>
  mutate(
    qaccver = replace(qaccver, 2, "absent"),
    pident = replace(pident, 1, 103)
  )
problem_report <- validate_ggchord_data(seqs, problem_links)
repaired <- clean_ggchord_data(seqs, problem_links, unknown_id = "drop", invalid_pident = "clip")

Metric	Observed output
Input rows	2
Rows retained after explicit cleaning	1

The demonstration intentionally includes an unknown ID and identity outside 0–100 in copied source rows. These explicit repairs are not a recommendation to clip scientific observations silently. Inspect problem_report and repaired$report, retain the original table, and choose policies appropriate to actual evidence. A legitimate reverse alignment can keep endpoint order instead of being sorted. prepare_ggchord_data() therefore retains its workflow-specific default policy; standalone cleaning and preparation should not be assumed identical.

Declare genome and contig keys

Code

# Each source record represents a separate complete phage genome.
contigs <- seqs |>
  mutate(genome = accver)
genomes <- tibble(genome = seqs$accver)
hierarchy <- validate_ggchord_hierarchy(contigs, genomes, strict = TRUE)

hierarchy$contigs summarizes declared membership without concatenating contigs. No membership is inferred from an accession prefix. Provide globally unique IDs when separate samples reuse local contig names. Use file formats and adapters for format/optional-object details, and the real-record tutorial to carry reports into a complete figure.

Minimal input and protein alignments

Metric	Observed output
Sequence columns passed to the plot	2
Link columns passed to the plot	6
Gene columns passed to the plot	4

The second positional constructor argument is ribbon_data, not gene_data. Use explicit argument names as in the shared examples. Optional identity, length and coverage fields are needed only by operations that consume them. See standard BLAST/protein input and parameter formats.

Check your result

Input IDs must match complete sequence records. Keep original records separate from repaired copies. Decreasing endpoints can be legitimate reverse hits; warnings do not all mean rows must be removed.

Continue: File formats and explicit adapters →