0.16.6 documentation

Complete canonical API text; task articles explain the workflows. Tutorials

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 named ggchord tables with an explicit audit trail

On this page

• Usage
• Arguments
• Value
• Details
• See also
• Examples

Converts inputs using the existing as_ggchord_*() adapters and returns named feature/link collections alongside the constructor's three tables. Collections are passed explicitly to layers, for example geom_feature(data = result$features$sites); preparation never adds layers. Import files first with the appropriate reader. No file format, alignment, sequence length, genome membership or biological identity is guessed.

Usage

Code

prepare_ggchord_data(
  seq_data,
  ribbon_data = NULL,
  gene_data = NULL,
  features = list(),
  links = list(),
  mapping = list(),
  steps = list()
)

Arguments

seq_data

Sequence input accepted by as_ggchord_seq().

ribbon_data

Optional paired intervals accepted by as_ggchord_link().

gene_data

Optional directional gene input accepted by as_ggchord_feature(). Nondirectional intervals belong in features.

features, links

Named lists of feature or paired-interval inputs.

mapping

Named list with optional seq, ribbon, gene column mappings, and features/links lists of mappings named like the respective collections. Each column mapping is a named character vector.

steps

Named list of explicit helper argument lists. Supported names: clean, filter, deduplicate, merge, bundle, optimize. Data arguments are supplied by preparation and cannot be overridden.

Value

A list with seq_data, ribbon_data, gene_data, features, links and report. report$valid describes final validity, with validation before/after, feature_issues, per-link validations, conversions, steps, effective step_arguments, a ribbon source_rows list (original input rows contributing to each output row), pair_counts, and optional layout_suggestion. Structural conversion errors stop; biological reference/bounds errors remain in the report and are never repaired by default. Helper stage reports number rows in that stage's input.

Details

By default this only converts and validates. Optional operations run in the fixed order clean, filter, deduplicate, merge, bundle, optimize. Each entry in steps is a named list of arguments for the corresponding existing helper. An empty list requests its defaults. clean affects only the constructor tables; the other operations affect ribbon_data only. Preparation sets cleaning's reversed_interval = "keep" by default to preserve directional endpoints. Explicit "sort" cannot be followed by deduplication, merging, bundling or optimization, which use those endpoints. Those operations also reject previously sorted input whose direction contradicts the endpoints; supply the original directional link table. Geometry, named feature/link tables and the original inputs are never silently filtered, merged or reoriented. Optimization returns a suggestion. Expensive pairwise duplicate diagnostics are disabled in validation here; request steps = list(deduplicate = list(...)) to deduplicate explicitly.

An optional genome column in seq_data groups contigs as metadata. accver must remain globally unique; contigs are never concatenated. Stable feature IDs and parent ID lists are preserved when supplied, not manufactured from row numbers. Repeated IDs can describe feature segments; uniqueness for a specific join is checked by the consumer, such as find_ggchord_loci().

See also

ggchord_data_contract

Examples

Code

library(dplyr)
data(seq_data_example)
seqs <- seq_data_example |>
  select(accver, length)
data(ribbon_data_example)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send)
data(gene_data_example)
genes <- gene_data_example |>
  transmute(accver, start, end, strand = source_strand)
prepared <- prepare_ggchord_data(seqs, links, features = list(genes = genes))
prepared$report