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

Build an explicit spliced CDS coordinate map

On this page

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

Builds a mapping from observed protein residues to genomic coding bases. CDS rows sharing feature_id form one coding model. Their genomic intervals must be non-overlapping and have one sequence and known strand. Segments are ordered in transcription direction, increasing on + and decreasing on -. An explicit segment_order overrides genomic sorting, allowing a declared circular-origin join. A segments list-column can declare segment_order for transcription order, including reverse-strand and origin joins; otherwise its pieces follow genomic strand order. Generic segment_index identifiers are preserved as source metadata and do not define transcription order. Nested phases may be supplied or derived from an explicit first phase or codon_start - 1; no phase is guessed from the genomic envelope. Trans-spliced models spanning different sequence IDs are rejected.

Usage

Code

build_ggchord_cds(cds_data, genetic_code = NULL, partial = c("error", "trim"))

Arguments

cds_data

Data frame with feature_id, accver, ordered one-based inclusive start/end, strand (+/-) and GFF3 phase (0–2, numeric or literal text as returned by read_gff3()). . remains unknown; unknown initial phase requires explicit codon_start for nested CDS. If type is present, select CDS rows explicitly before building a map. Alternatively supply one row per CDS with a segments list-column and explicit initial phase or codon_start (1–3). Nested genomic pieces retain explicit segment_order when supplied and are never replaced by the parent's outer envelope.

genetic_code

Optional positive integer code ID, scalar or named by CDS feature_id. Must agree with a supplied genetic_code column. Missing IDs remain unknown; they do not prevent coordinate-only projection.

partial

"error" (default) or explicit "trim".

Value

A ggchord_cds list containing a models summary, transcription- ordered segments per feature, original source_data and provenance. Segment cds_start/cds_end identify complete-codon nucleotide positions; genomic coordinates and original row numbers remain available.

Details

GFF3 phase counts bases from a segment's biological 5-prime end to the next codon boundary. Only the first phase is skipped; later phases validate the accumulated coding length, retaining bases of codons split across exons. partial = "error" rejects partial ends. Explicit "trim" permits a nonzero first phase, partial-end flags and incomplete terminal codons, and excludes bases without complete codons. Residue one then means the first complete observed codon, not an inferred position in an unobserved protein.

Optional partial5, partial3, genetic_code, and protein_id columns must agree within each model. A nonzero initial phase requires partial5; if absent it is recorded as partial5. A terminal remainder similarly records partial3 unless a conflicting explicit flag is supplied. Genetic-code IDs are retained as metadata: coordinate projection does not translate sequence, identify stop codons, or infer a genetic code. codon_count includes any source terminal stop codon. Frameshifts, ribosomal slippage and translation exceptions or non-join location operators cannot be represented by a simple triplet map and are rejected when declared. No full protein length or identity is inferred.

See also

https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md

ggchord_data_contract

Examples

Code

library(dplyr)
data(plasmid_example_pUC19)
feature_source <- find_common_features(plasmid_example_pUC19)
features <- feature_source |>
  select(accver, start, end, strand, type, anno)
coding <- features |>
  filter(anno == "AmpR", type == "CDS") |>
  select(accver, start, end, strand) |>
  mutate(feature_id = paste(accver, "AmpR", sep = ":"), phase = 0)
cds <- build_ggchord_cds(coding, genetic_code = 11)
cds$features