API Reference

cooccurrence_matrix(df::DataFrame, columns::Vector{Symbol}; normalize=false)

Compute a co-occurrence matrix from a DataFrame.

Each row in the DataFrame represents one observation. Labels from different columns that appear in the same row are considered co-occurring.

Arguments

• df::DataFrame: Input data
• columns::Vector{Symbol}: Column names to analyze

Keywords

• normalize::Bool=false: If true, normalize counts to frequencies

Returns

• CoOccurrenceMatrix: Matrix of co-occurrence counts/frequencies

Example

df = DataFrame(
    V_call = ["IGHV1-2*01", "IGHV1-2*01", "IGHV3-23*01"],
    D_call = ["IGHD2-2*01", "IGHD3-10*01", "IGHD2-2*01"],
    J_call = ["IGHJ6*01", "IGHJ6*01", "IGHJ4*02"]
)
cooc = cooccurrence_matrix(df, [:V_call, :D_call, :J_call])

chordplot(cooc::CoOccurrenceMatrix)
chordplot!(ax, cooc::CoOccurrenceMatrix)

Create a chord diagram from co-occurrence data.

Attributes

• inner_radius = 0.92: Inner radius for ribbons (closer to outer for less wasted space)
• outer_radius = 1.0: Outer radius for arcs
• arc_width = 0.08: Width of arc segments
• gap_fraction = 0.03: Gap between arcs as fraction of circle
• ribbon_alpha = 0.65: Transparency for ribbons
• ribbon_alpha_by_value = false: If true, scale opacity by ribbon value (min 10%, larger ribbons more visible)
• ribbon_alpha_scale = :linear: Scaling method for value-based opacity (:linear default, :log for better distribution of small integers)
• ribbon_tension = 0.5: Bezier curve tension (0=straight, 1=tight)
• show_labels = true: Show labels
• label_offset = 0.12: Distance from arc to label (increase for longer labels to avoid overlap)
• label_fontsize = 10: Label font size
• rotate_labels = true: Rotate labels to follow arcs (prevents upside-down text)
• label_justify = :inside: Label justification (:inside aligns toward circle center, :outside aligns away)
• min_arc_flow = 0: Filter out arcs and labels with total flow below this value (helps reduce overlap from many small segments)
• colorscheme = :group: Color scheme (:group, :categorical, or AbstractColorScheme)
• arc_strokewidth = 0.5: Arc border width
• arc_strokecolor = :black: Arc border color
• arc_alpha = 0.9: Transparency for arcs (slight transparency for modern look)
• sort_by = :group: How to sort arcs (:group, :value, :none)
• min_ribbon_value = 0: Hide ribbons below this value

Example

using CairoMakie, ChordPlots, DataFrames

df = DataFrame(
    V_call = ["V1", "V1", "V2", "V2", "V3"],
    D_call = ["D1", "D2", "D1", "D2", "D1"],
    J_call = ["J1", "J1", "J2", "J2", "J1"]
)

cooc = cooccurrence_matrix(df, [:V_call, :D_call, :J_call])
fig, ax, plt = chordplot(cooc)

chordplot(df::DataFrame, columns; kwargs...)

Create chord plot directly from DataFrame.

setup_chord_axis!(ax::Axis)

Configure axis for chord plot display (equal aspect, no decorations).

compute_layout(cooc::CoOccurrenceMatrix{T, S}, config::LayoutConfig=LayoutConfig()) where {T, S}

Compute the complete layout for a chord diagram.

Algorithm

1. Calculate total flow for each label
2. Allocate angular width proportional to flow
3. Assign arc positions
4. Generate ribbon endpoints based on co-occurrence values

filter_top_n(cooc::CoOccurrenceMatrix, n::Int)

Keep only the top n labels by total flow.

filter_by_threshold(cooc::CoOccurrenceMatrix{T, S}, min_value::T) where {T, S}

Create a new CoOccurrenceMatrix with values below threshold set to zero.

normalize(cooc::CoOccurrenceMatrix{T, S}) where {T, S}

Return a normalized version where all values sum to 1.

CoOccurrenceMatrix{T<:Real, S<:AbstractString}

Stores co-occurrence counts between labels with group information.

Type Parameters

• T: Numeric type for counts (enables Integer or Float)
• S: String type for labels

Fields

• matrix::Matrix{T}: Symmetric co-occurrence matrix
• labels::Vector{S}: Combined list of all labels
• groups::Vector{GroupInfo{S}}: Group information
• label_to_index::Dict{S, Int}: Fast label lookup

Example

cooc = CoOccurrenceMatrix(df, [:V_call, :D_call, :J_call])
cooc["IGHV1-2*01", "IGHD2-2*01"]  # Get co-occurrence count

filter_ribbons(layout::ChordLayout, min_value::Real)

Filter ribbons below a minimum value threshold.

filter_ribbons_top_n(layout::ChordLayout, n::Int)

Keep only the top n ribbons by value.

LayoutConfig{T<:Real}

Configuration for layout computation.

Fields

• inner_radius::T: Inner radius for ribbon attachment
• outer_radius::T: Outer radius for arcs
• gap_fraction::T: Fraction of circle to use for gaps between arcs
• start_angle::T: Starting angle (0 = right, π/2 = top)
• direction::Int: 1 for counterclockwise, -1 for clockwise
• sort_by::Symbol: How to sort arcs (:group, :value, :none)

ChordLayout{T<:Real}

Complete layout information for rendering a chord diagram.

Fields

• arcs::Vector{ArcSegment{T}}: Arc segments for each label
• ribbons::Vector{Ribbon{T}}: All ribbons
• inner_radius::T: Inner radius for ribbons
• outer_radius::T: Outer radius for arcs
• gap_angle::T: Gap between adjacent arcs

group_colors(cooc::CoOccurrenceMatrix; palette=:default)

Create a color scheme based on groups using Makie's default categorical palette (same as AlgebraOfGraphics uses - Wong colors, colorblind-friendly).

Arguments

• palette::Symbol: Color palette style (:default for Makie/AoG palette, :modern for custom)

gradient_colors(; colormap=:viridis, min_val=0.0, max_val=1.0)

Create a gradient-based color scheme.

with_alpha(color::Colorant, alpha::Real)

Return color with specified alpha value.

darken(color::Colorant, factor::Real=0.2)

Darken a color by the given factor.

lighten(color::Colorant, factor::Real=0.2)

Lighten a color by the given factor.

GroupColorScheme{C<:Colorant}

Assigns colors based on label groups.

Fields

• group_colors::Dict{Symbol, C}: Color for each group
• default_color::C: Fallback color

CategoricalColorScheme{C<:Colorant}

Assigns distinct colors to each label.

Fields

• colors::Vector{C}: Color palette

GradientColorScheme

Colors based on a gradient (e.g., by value).

Fields

• colormap::Symbol: Makie colormap name
• range::Tuple{Float64, Float64}: Value range for mapping

arc_points(start_angle::Real, end_angle::Real, radius::Real; n_points::Int=50)

Generate points along an arc.

Arguments

• start_angle: Start angle in radians
• end_angle: End angle in radians
• radius: Arc radius
• n_points: Number of points (more = smoother)

Returns

• Vector{Point2f}: Points along the arc

arc_polygon(inner_radius::Real, outer_radius::Real, start_angle::Real, end_angle::Real; n_points::Int=30)

Generate a filled arc (annular sector) as a polygon.

Returns points forming a closed polygon: outer arc → inner arc (reversed) → close.

ribbon_path(ribbon::Ribbon, radius::Real; n_bezier::Int=30, tension::Real=0.5)

Generate the path for a ribbon connecting two arcs.

The ribbon consists of:

1. Source arc segment
2. Bezier curve to target
3. Target arc segment
4. Bezier curve back to source

Arguments

• ribbon: Ribbon geometry specification
• radius: Radius where ribbons attach
• n_bezier: Points per Bezier curve
• tension: Control point tension (0 = straight, 1 = tight curves)

ribbon_paths(ribbons::Vector{Ribbon{T}}, radius::Real; kwargs...)

Generate paths for multiple ribbons.

label_position(arc::ArcSegment, radius::Real, offset::Real; rotate::Bool=true, justify::Symbol=:inside)

Calculate position for an arc's label.

Arguments

• arc: Arc segment
• radius: Outer radius of the arc
• offset: Distance from arc to label
• rotate: Whether to rotate label to follow arc
• justify: Label justification (:inside aligns toward circle center, :outside aligns away)

label_positions(arcs::Vector{ArcSegment{T}}, radius::Real, offset::Real; kwargs...)

Calculate positions for all arc labels.

Keyword Arguments

• rotate::Bool=true: Whether to rotate labels to follow arcs
• justify::Symbol=:inside: Label justification (:inside or :outside)

ArcSegment{T<:Real}

Represents an arc on the outer circle for a single label.

Fields

• label_idx::Int: Index into the label array
• start_angle::T: Starting angle in radians
• end_angle::T: Ending angle in radians
• value::T: Total flow value (determines arc width)

RibbonEndpoint{T<:Real}

Represents one end of a ribbon attached to an arc.

Fields

• label_idx::Int: Which label this endpoint is on
• start_angle::T: Start angle on the arc
• end_angle::T: End angle on the arc

Ribbon{T<:Real}

Represents a ribbon connecting two labels.

Fields

• source::RibbonEndpoint{T}: Source endpoint
• target::RibbonEndpoint{T}: Target endpoint
• value::T: Co-occurrence value

RibbonPath

Stores the complete path for rendering a ribbon.

GroupInfo{S<:AbstractString}

Information about a group of labels (e.g., V calls, D calls, J calls).

Fields

• name::Symbol: Group identifier
• labels::Vector{S}: Labels belonging to this group
• indices::UnitRange{Int}: Index range in the combined label list