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

Merge adjacent or overlapping alignment blocks of the same sequence pair

On this page

• Usage
• Arguments
• Value
• See also
• Examples

Merges alignment blocks that belong to the same (query, subject) pair, are adjacent (gap <= max_gap) or overlapping on both sequences, and are compatible. The merged pident is weighted by alignment length. Merging is deliberately conservative: blocks whose merged query and subject spans would differ by more than max(max_gap, 1), whose pident differs by more than min_pident_difference, or whose orientation differs (when require_same_orientation) are left unmerged. With the default orientation check, subject bounds must also progress in the order implied by the relative direction; crossing block orders remain separate. Query/subject identifiers always define separate groups, even when group_by selects additional metadata. An unmerged row retains its original alignment length. For a merged row, length is the query envelope span, not a newly computed alignment length; .length_estimated marks this display summary. Source lengths and identities are retained in the report. Overlap can count aligned bases more than once in the weighted identity; gaps can add unaligned bases to the envelope. Use the original blocks for alignment statistics. Rows with a single-base endpoint remain independent: endpoint order cannot define an absolute direction for an aggregate envelope.

Usage

Code

merge_ggchord_ribbons(
  ribbon_data,
  max_gap = 0,
  min_pident_difference = 0,
  require_same_orientation = TRUE,
  group_by = c("qaccver", "saccver"),
  extra_columns = c("consistent", "first")
)

Arguments

ribbon_data

data.frame in ribbon_data format.

max_gap

Numeric, default 0. Maximum gap (in bp) allowed between two blocks on both sequences for them to be merged.

min_pident_difference

Numeric, default 0. When > 0, two blocks are only merged when their pident difference is <= this value.

require_same_orientation

Logical, default TRUE. Only merge blocks with the same relative query/subject direction and compatible progression of their bounds. Reversing both endpoints preserves relative direction. FALSE explicitly permits a coarser mixed-direction summary.

group_by

Character vector, default c("qaccver", "saccver"). Additional grouping columns; query/subject IDs always remain grouping keys.

extra_columns

How to handle columns other than the required ribbon fields when multiple rows are merged. "consistent" (default) keeps a value only when all source rows agree and otherwise stores a typed missing value; "first" retains the first source row's value.

Value

A list with data (merged data frame with source_rows attribute) and report (data.frame with output_row, from_rows, n_merged, and list-columns source_length and source_pident for every output row).

See also

ggchord_data_contract

Examples

Code

library(dplyr)
data(ribbon_data_example)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send, pident, length)
out <- merge_ggchord_ribbons(links, max_gap = 100)
out$report