Title: Multi-Sequence 'BLAST' Alignment Chord Diagram Visualization Tool
Version: 0.2.0
Description: A function built on 'ggplot2' that visualizes pairwise 'BLAST' alignment results as chord diagrams, intuitively displaying homologous regions between query and subject sequences.
License: MIT + file LICENSE
Depends: R (≥ 3.6.0)
Imports: ggplot2 (≥ 3.3.0), ggnewscale (≥ 0.5.0), RColorBrewer, grDevices, grid
VignetteBuilder: knitr
Suggests: knitr, rmarkdown, qpdf, dplyr, testthat (≥ 3.0.0)
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.2
Config/testthat/edition: 3
URL: https://github.com/DangJem/ggchord
BugReports: https://github.com/DangJem/ggchord/issues
NeedsCompilation: no
Packaged: 2025-07-13 16:33:33 UTC; 92330
Author: Jem Dang [aut, cre]
Maintainer: Jem Dang <dangjem0730@gmail.com>
Repository: CRAN
Date/Publication: 2025-07-16 17:20:06 UTC

Generate Bézier curve points

Description

Generates points on a Bézier curve based on start point, end point, and control points (for smooth ribbons)

Usage

bezier_pts(p0, p3, c1, c2, n = 100)

Arguments

p0

Numeric vector (length 2), start point coordinates (x, y)

p3

Numeric vector (length 2), end point coordinates (x, y)

c1

Numeric vector (length 2), first control point coordinates (x, y)

c2

Numeric vector (length 2), second control point coordinates (x, y)

n

Integer, number of curve points (controls smoothness), default 100

Value

data.frame containing columns x, y (coordinates of points on the Bézier curve)

Generate major axis tick breakpoints

Description

Generates uniform and visually appealing major tick positions based on sequence length and target tick count (avoids excessively short end ticks)

Usage

breakPointsFunc(max_value, n = 5, tol = 0.5)

Arguments

max_value

Numeric, sequence length (maximum value)

n

Integer, target number of ticks, default 5

tol

Numeric (0-1), tolerance threshold for end tick length (proportion of the median length of other ticks), default 0.5

Value

Numeric vector, major tick positions (including 0 and max_value)

Core Plotting Function Collection

Description

Contains core functions for integrating graphic elements and generating the final ggplot2 object.

Integrates all graphic elements to generate the final chord plot

Usage

chordPlotFunc(
  allRibbon,
  ribbon_alpha,
  ribbon_color_scheme,
  ribbon_colors,
  show_legend,
  gene_polys,
  gene_pal,
  gene_color_scheme,
  final_gene_order,
  seqArcs,
  gene_arrows,
  gene_label_show,
  gene_label_size,
  show_axis,
  axisLines,
  axisTicks,
  axisLabelOrientation,
  seq_colors,
  seq_labels,
  seqs,
  extremes,
  panel_margin,
  title
)

Arguments

allRibbon

Ribbon data (data.frame)

ribbon_alpha

Ribbon transparency

ribbon_color_scheme

Ribbon color scheme

ribbon_colors

Ribbon color parameters

show_legend

Whether to display the legend

gene_polys

Gene arrow polygon data

gene_pal

Gene color vector

gene_color_scheme

Gene color scheme

final_gene_order

Order of genes in the legend

seqArcs

Sequence arc data

gene_arrows

Gene label data

gene_label_show

Whether to display gene labels

gene_label_size

Font size of gene labels

show_axis

Whether to display axes

axisLines

Axis line data

axisTicks

Tick mark data

axisLabelOrientation

Orientation of axis labels

seq_colors

Sequence color vector

seq_labels

Sequence labels

seqs

List of sequence IDs

extremes

Plot extrema (min/max coordinates)

panel_margin

Panel margins

title

Plot title

Value

ggplot2 object

Custom gene arrow legend drawing function

Description

Generates gene arrow-shaped legend symbols (polygons) for ggplot2 legends

Usage

draw_key_gene_arrow(data, params, size)

Arguments

data

Legend data (contains aesthetic mapping parameters like fill, colour, size)

params

Legend parameters (automatically passed by ggplot2)

size

Legend symbol size

Value

grid::polygonGrob object, gene arrow-shaped legend symbol

Example gene annotation data

Description

Gene annotation data for ggchord demonstration (short genes have been filtered out)

Usage

gene_data_example

Format

A data frame containing the following columns:

Generate curved sequence paths

Description

Generates smooth sequence paths (supporting straight lines, arcs, and custom curvatures) based on start angle, end angle, radius, and curvature.

Usage

generate_curvature_path(
  start_angle,
  end_angle,
  radius,
  curvature,
  n_points = 100
)

Arguments

start_angle

Numeric, start angle (in radians)

end_angle

Numeric, end angle (in radians)

radius

Numeric, path radius

curvature

Numeric, curvature (0 = straight line, 1 = standard arc, >1 = more curved)

n_points

Integer, number of points in the path (controls smoothness), default 100

Value

data.frame containing columns x, y (coordinates of points on the path)

Calculate plot extremes

Description

Extracts x/y coordinate extremes from all plot elements (sequence arcs, ribbons, gene arrows, etc.) for adjusting the plot range

Usage

get_plot_extremes(
  allRibbon = NULL,
  seqArcs = NULL,
  axisLines = NULL,
  axisTicks = NULL,
  gene_arrows = NULL,
  gene_polys = NULL,
  show_axis = FALSE
)

Arguments

allRibbon

data.frame, ribbon data (with x, y columns), default NULL

seqArcs

List, sequence arc data (each element is a data frame with x, y, seq_id), default NULL

axisLines

data.frame, axis line data (with x, y, seq_id columns), default NULL

axisTicks

data.frame, tick mark data (with x0, y0, x1, y1, label_x, label_y columns), default NULL

gene_arrows

data.frame, gene label data (with text_x, text_y columns), default NULL

gene_polys

data.frame, gene arrow polygon data (with x, y columns), default NULL

show_axis

Logical, whether to include extreme value calculation for axis-related elements, default FALSE

Value

List containing x_min (minimum x), x_max (maximum x), y_min (minimum y), y_max (maximum y)

ggchord: A ggplot2-based tool for multi-sequence alignment chord plots

Description

ggchord is used to draw chord plots containing multiple sequences, which can display alignment relationships between sequences and gene annotation information. ggchord supports customizing various parameters such as sequence arrangement, colors, ribbon styles, and gene arrow styles, making it suitable for genome alignment visualization.

Usage

ggchord(
  seq_data,
  ribbon_data = NULL,
  gene_data = NULL,
  title = NULL,
  seq_order = NULL,
  seq_labels = NULL,
  seq_orientation = NULL,
  seq_gap = 0.03,
  seq_radius = 1,
  seq_colors = NULL,
  seq_curvature = 1,
  gene_offset = 0.1,
  gene_width = 0.05,
  gene_label_show = FALSE,
  gene_label_rotation = 0,
  gene_label_size = 2.5,
  gene_label_radial_offset = 0,
  gene_label_circum_offset = 0,
  gene_label_circum_limit = TRUE,
  gene_color_scheme = c("strand", "manual"),
  gene_colors = NULL,
  gene_order = NULL,
  ribbon_color_scheme = c("pident", "query", "single"),
  ribbon_colors = NULL,
  ribbon_alpha = 0.35,
  ribbon_ctrl_point = c(0, 0),
  ribbon_gap = 0.15,
  axis_gap = 0.04,
  axis_tick_major_number = 5,
  axis_tick_major_length = 0.02,
  axis_tick_minor_number = 4,
  axis_tick_minor_length = 0.01,
  axis_label_size = 3,
  axis_label_offset = 1.5,
  axis_label_orientation = "horizontal",
  rotation = 45,
  panel_margin = 0,
  show_legend = TRUE,
  show_axis = TRUE,
  debug = FALSE
)

Arguments

seq_data

data.frame/tibble, required. A data frame containing basic sequence information, must include columns: - seq_id: Unique sequence identifier (character) - length: Sequence length (numeric, > 0)

ribbon_data

data.frame/tibble, optional. BLAST alignment result data frame, must include columns: - qaccver: Query sequence ID (matching seq_id) - saccver: Subject sequence ID (matching seq_id) - length: Alignment length - pident: Percentage of sequence identity (0-100) - qstart/qend: Start/end positions of the query sequence in the alignment - sstart/send: Start/end positions of the subject sequence in the alignment

gene_data

data.frame/tibble, optional. Gene annotation data frame, must include columns: - seq_id: ID of the associated sequence (matching seq_id) - start/end: Gene start/end positions (numeric) - strand: Strand direction (only "+" or "-") - anno: Gene annotation name (character)

title

Character. Main title of the plot, default NULL (no title displayed)

seq_order

Character vector, optional. Specifies the drawing order of sequences (must be a subset of seq_id), default follows the order in seq_data

seq_labels

Character vector/named vector, optional. Sequence labels (length matching the number of sequences or named to match seq_id), default uses seq_id

seq_orientation

Numeric (1 or -1), optional. Sequence direction (1 = forward, -1 = reverse), supports single value/vector/named vector, default 1

seq_gap

Numeric (0 <= x < 0.5), optional. Proportion of gap between sequences, supports single value/vector/named vector, default 0.03

seq_radius

Numeric (> 0), optional. Radius of sequence arcs, supports single value/vector/named vector, default 1.0

seq_colors

Color vector/named vector, optional. Colors of sequence arcs, default auto-generated based on RColorBrewer Set1

seq_curvature

Numeric, optional. Curvature of sequence arcs (0 = straight line, 1 = standard arc, > 1 = more curved), default 1.0

gene_offset

Numeric/vector/list, optional. Radial offset of gene arrows from sequences (positive values outward, negative values inward), supports: - single value: shared by all sequences/strands - vector: length matching the number of sequences (assigned by sequence) - list: named list (elements are single values or vectors with "+"/"-" to distinguish strands), default 0.1

gene_width

Numeric/vector/list, optional. Width of gene arrows, format same as gene_offset, default 0.05

gene_label_show

Logical. Whether to display gene labels, default FALSE

gene_label_rotation

Numeric/vector/list, optional. Rotation angle (degrees) of gene labels, format same as gene_offset, default 0

gene_label_size

Numeric. Font size of gene labels, default 2.5

gene_label_radial_offset

Numeric/vector/list, optional. Radial offset of gene labels relative to arrows, format same as gene_offset, default 0

gene_label_circum_offset

Numeric/vector/list, optional. Circumferential offset proportion of gene labels along sequences, format same as gene_offset, default 0

gene_label_circum_limit

Logical/vector/list, optional. Whether to limit circumferential offset to half the gene length, format same as gene_offset, default TRUE

gene_color_scheme

Character. Color scheme for genes, optional "strand" (by strand direction) or "manual" (by annotation), default "strand"

gene_colors

Color vector, optional. Fill colors for gene arrows, format depends on gene_color_scheme: - "strand": named vector ("+"/"-"), unnamed vector of length 1/2 - "manual": named vector (matching anno), unnamed vector (recycled), default auto-generated

gene_order

Character vector, optional. Display order of genes in the legend (matching anno), default follows the order in data

ribbon_color_scheme

Character. Color scheme for ribbons, optional "pident" (gradient by identity), "query" (by query sequence), "single" (uniform color), default "pident"

ribbon_colors

Color vector, optional. Color parameters for ribbons: - "single": uniform color - "query": color vector matching seq_id - "pident": color gradient (at least 2 colors), default blue-to-yellow gradient

ribbon_alpha

Numeric (0-1). Transparency of ribbons, default 0.35

ribbon_ctrl_point

Vector/list, optional. Control points for Bézier curves (adjust ribbon shape): - vector: length 2 (single control point) or 4 (c1x,c1y,c2x,c2y for two control points) - list: each element is a sublist with 1-2 control points, default c(0,0)

ribbon_gap

Numeric/vector/named vector, optional. Radial distance between sequences and ribbons, default 0.15

axis_gap

Numeric/vector/named vector, optional. Radial distance between sequences and axes, default 0.04

axis_tick_major_number

Integer/vector/named vector, optional. Number of major ticks, default 5

axis_tick_major_length

Numeric/vector/named vector, optional. Length proportion of major ticks, default 0.02

axis_tick_minor_number

Integer/vector/named vector, optional. Number of minor ticks per major tick, default 4

axis_tick_minor_length

Numeric/vector/named vector, optional. Length proportion of minor ticks, default 0.01

axis_label_size

Numeric/vector/named vector, optional. Font size of axis labels, default 3

axis_label_offset

Numeric/vector/named vector, optional. Offset proportion of labels relative to ticks, default 1.5

axis_label_orientation

Character/numeric/vector, optional. Orientation of axis labels: - "horizontal": horizontal - numeric: rotation angle (degrees) - vector: length matching the number of sequences or named vector (matching seq_id), default "horizontal"

rotation

Numeric. Overall rotation angle of the plot (degrees), default 45

panel_margin

Numeric/list, optional. Margin around the plot panel (t=top, r=right, b=bottom, l=left): - single value: same margin for all sides - list: named list (e.g., list(t=1,r=1)), default 0

show_legend

Logical. Whether to display legends, default TRUE

show_axis

Logical. Whether to display axes and ticks, default TRUE

debug

Logical. Whether to output debugging information (e.g., number of valid ribbons), default FALSE

Value

A ggplot2 graph object, which can be further adjusted with ggplot2 functions

Examples

# Example code
p <- ggchord(
  seq_data = seq_data_example,
  ribbon_data = ribbon_data_example,
  gene_data = gene_data_example
)
print(p)

Missing value handling operator

Description

Used to safely handle NULL values: returns y if x is NULL, otherwise returns x

Usage

if_null_else(x, y)

Arguments

x

Any R object (may be NULL)

y

Default value to return when x is NULL

Value

x if x is not NULL, otherwise y

Process axis label orientation parameters

Description

Standardizes axis label orientation parameters in various formats (character/numeric/vector) into a named vector (mapped by sequence ID)

Usage

process_axis_orientation(param, seqs)

Arguments

param

Character ("horizontal"), numeric (angle), vector (length matches number of sequences), or named vector, label orientation parameter

seqs

Character vector, list of sequence IDs

Value

Named vector (names are seq_id), values are "horizontal" or numeric angles

Process gene-related parameters

Description

Standardizes gene parameters (e.g., offset, width) from various input formats (single value/vector/list) into a list seperated by sequence and strand

Usage

process_gene_param(param, seqs, param_name, default_value, is_logical = FALSE)

Arguments

param

Input parameter (can be NULL, single value, vector, list)

seqs

Character vector, list of sequence IDs

param_name

Character, name of the parameter (used in error messages)

default_value

Default value when param is NULL

is_logical

Logical, whether the parameter is logical (TRUE/FALSE), default FALSE

Value

List (named by seq_id), where each element is a vector with "+"/"-" (parameter values for positive/negative strands)

Process gene color parameters in manual mode

Description

Standardizes gene color parameters in manual mode (color by gene annotation) into a vector named by gene annotation

Usage

process_manual_colors(gene_colors, unique_anno, gene_order)

Arguments

gene_colors

Color vector (can be NULL, single value, vector, named vector with gene annotations)

unique_anno

Character vector, unique gene annotation names

gene_order

Character vector, display order of genes in the legend, default NULL (order of appearance)

Value

Named vector (names are gene annotations), standardized color values (default uses RColorBrewer Set1)

Process panel margin parameters

Description

Standardizes input margin parameters into a list containing t (top), r (right), b (bottom), l (left). Supports single-value or list input.

Usage

process_panel_margin(arg_list)

Arguments

arg_list

Numeric (single value) or list (named/unnamed), margin parameters

Value

List containing four elements: t, r, b, l (numeric, margin sizes)

Process sequence-related parameters

Description

Standardizes sequence parameters (e.g., radius, gap) from various input formats (single value/vector/named vector) into a vector named by sequence IDs

Usage

process_sequence_param(
  param,
  seqs,
  param_name,
  default_value = NULL,
  allow_null = FALSE
)

Arguments

param

Input parameter (can be NULL, single value, vector, named vector)

seqs

Character vector, list of sequence IDs

param_name

Character, name of the parameter (used in error messages)

default_value

Default value when param is NULL, default NULL

allow_null

Logical, whether to allow param to be NULL, default FALSE

Value

Named vector (names are seq_ids), standardized parameter values

Process gene color parameters in strand mode

Description

Standardizes gene color parameters in strand mode (color by strand direction) into a named vector with "+"/"-"

Usage

process_strand_colors(gene_colors)

Arguments

gene_colors

Color vector (can be NULL, single value, vector of length 2, named vector with "+"/"-")

Value

Named vector (names are "+"/"-"), standardized color values (default "+" is red, "-" is blue)

Example alignment data

Description

BLAST alignment data for ggchord demonstration (length >= 100)

Usage

ribbon_data_example

Format

A data frame containing standard BLAST columns (qaccver, saccver, pident, etc.)

Example sequence data

Description

Sequence length data for ggchord demonstration

Usage

seq_data_example

Format

A data frame containing columns: seq_id, length