LineageCollapse

Abstract type for all distance metrics used in sequence comparison.

Abstract type for tie-breaking strategies used when selecting lineage representatives.

Abstract type for clustering methods.

Abstract type for lineage collapse strategies.

HammingDistance <: AbstractDistanceMetric

Hamming distance metric - counts the number of mismatches between sequences.

Hardest <: CollapseStrategy

Collapse strategy that selects exactly one representative per lineage.

HierarchicalClustering{T} <: ClusteringMethod

Hierarchical clustering with a distance cutoff.

Fields

• cutoff::T: Distance threshold for cluster merging

Example

HierarchicalClustering(1.0f0)  # Merge clusters within distance 1.0

LevenshteinDistance <: AbstractDistanceMetric

Levenshtein (edit) distance metric.

MostCommonVdjNtTieBreaker

A tie-breaker that selects the representative based on the most common VDJ_nt sequence weighted by count, matching igdiscover's clonotypes behavior.

For each lineage, it:

1. Sums the count for each unique vdj_nt sequence
2. Selects the vdj_nt with the highest total count
3. Returns the first row with that vdj_nt

NormalizedHammingDistance <: AbstractDistanceMetric

Normalized Hamming distance - mismatches divided by sequence length.

Soft{T} <: CollapseStrategy

Collapse strategy that keeps all clones above a frequency threshold.

Fields

• cutoff::T: Minimum clone frequency to retain (0.0 to 1.0)

Example

Soft(0.2)  # Keep clones with frequency ≥ 20%

TieBreaker <: AbstractTieBreaker

A configurable tie-breaker that sorts candidates by specified column criteria.

Fields

• criteria::Vector{Pair{Symbol,Bool}}: Sorting criteria as column => descending pairs. Columns are checked in order; true means sort descending (higher is better).

Example

# Sort by count descending, then by cdr3 ascending (lexicographic)
TieBreaker([:count => true, :cdr3 => false])

ByCdr3Count()

Tie-breaker that selects by highest CDR3 count, then lexicographic CDR3.

ByFirst()

Tie-breaker that selects the first candidate (no sorting).

ByLexicographic()

Tie-breaker that selects by lexicographically smallest CDR3.

ByMostCommonVdjNt()

Create a tie-breaker that matches igdiscover's clonotypes representative selection.

Selects the representative by finding the VDJnt sequence with the highest total count across all members of the lineage, then returns the first row with that VDJnt.

Requires columns: vdj_nt, count

ByMostNaive()

Tie-breaker prioritizing sequences closest to germline (highest V/J identity), then by VDJ count, CDR3 count, and lexicographic CDR3.

BySequenceCount()

Tie-breaker that selects by highest sequence count, then lexicographic CDR3.

ByVdjCount()

Tie-breaker that selects by highest VDJ nucleotide count, then lexicographic CDR3.

collapse_lineages(df::DataFrame, strategy=Hardest(); tie_breaker, tie_atol) -> DataFrame

Collapse lineages to representative sequences.

Arguments

• df::DataFrame: Data from process_lineages with lineage_id column
• strategy::CollapseStrategy=Hardest(): Collapse strategy
  • Hardest(): One representative per lineage (highest clone frequency)
  • Soft(cutoff): Keep all clones with frequency ≥ cutoff

Keyword Arguments

• tie_breaker::AbstractTieBreaker=ByMostCommonVdjNt(): Strategy for breaking ties
• tie_atol::Real=0.0: Tolerance for frequency comparison

Returns

For Hardest():

• Selected rows with added count::Int (sum of counts) and nVDJ_nt::Int (unique VDJ sequences)

For Soft(cutoff):

• Rows meeting threshold with added clone_frequency::Float64 and sequence_count::Int

compute_distance(metric::AbstractDistanceMetric, x::LongDNA{4}, y::LongDNA{4}) -> Float32

Compute distance between two DNA sequences using the specified metric.

compute_pairwise_distance(metric, sequences) -> Matrix{Float32}

Compute pairwise distance matrix for DNA sequences.

deduplicate_data(df::DataFrame, use_barcode::Bool=false)::DataFrame

Deduplicate the input DataFrame based on sequence or sequence+barcode.

Arguments

• df::DataFrame: Input DataFrame.
• use_barcode::Bool=false: Whether to use barcode for deduplication.

Returns

• DataFrame: Deduplicated DataFrame.

hardest_tie_summary(df::DataFrame; atol=0.0) -> DataFrame

Diagnostic function to identify lineages with tied maximum clone frequencies.

load_data(filepath::String; 
          delimiter::Char='	', 
          required_columns=[:sequence_id, :sequence, :v_sequence_end, :j_sequence_start, :cdr3, :v_call, :j_call, :stop_codon])::DataFrame

Load data from a file (compressed or uncompressed) and return a DataFrame.

Arguments

• filepath::String: Path to the data file.
• delimiter::Char=' ': Delimiter used in the data file (default: tab).
• required_columns::Vector{Symbol}: Required columns to select from the data file.

Returns

• DataFrame: DataFrame containing the loaded data.

Throws

• ArgumentError: If any of the required columns are missing in the data file.

perform_clustering(method::HierarchicalClustering, linkage, dist_matrix) -> Vector{Int}

Perform hierarchical clustering and return cluster assignments.

preprocess_data(df::DataFrame; min_d_region_length::Union{Int,Nothing}=nothing, deduplicate::Bool=false, use_barcode::Bool=false)::DataFrame

Preprocess the input DataFrame by performing data cleaning and transformation.

Arguments

• df::DataFrame: Input DataFrame.
• min_d_region_length::Union{Int,Nothing}=nothing: Minimum length of the D region to keep. If nothing, no filtering is applied.
• deduplicate::Bool=false: Whether to deduplicate the DataFrame.
• use_barcode::Bool=false: Whether to use barcode for deduplication (only applicable if deduplicate is true).

Returns

• DataFrame: Preprocessed DataFrame.

process_lineages(df::DataFrame; distance_metric, clustering_method, linkage) -> DataFrame

Process sequences into lineages with explicit metric and clustering configuration.

Keyword Arguments

• distance_metric::AbstractDistanceMetric=HammingDistance(): Distance metric for CDR3 comparison
• clustering_method::ClusteringMethod=HierarchicalClustering(1.0f0): Clustering method and cutoff
• linkage::Symbol=:single: Hierarchical clustering linkage

See process_lineages(df, threshold) for return value documentation.

process_lineages(df::DataFrame, threshold; linkage=:single) -> DataFrame

Process sequences into lineages using CDR3 clustering.

Arguments

• df::DataFrame: Preprocessed data with columns v_call_first, j_call_first, cdr3, cdr3_length, d_region
• threshold: Clustering threshold. Integer for absolute mismatches, Float (0.0-1.0) for fraction of CDR3 length.
• linkage::Symbol=:single: Hierarchical clustering linkage (:single, :complete, :average)

Returns

DataFrame with added columns:

• lineage_id::Int: Unique lineage identifier
• cluster::Int: Cluster assignment within V/J group
• cluster_size::Int: Number of sequences in cluster
• min_distance::Float32: Minimum distance to other CDR3s in cluster
• cdr3_count::Int: Count of this CDR3 in cluster
• max_cdr3_count::Int: Maximum CDR3 count in cluster
• cdr3_frequency::Float64: cdr3_count / max_cdr3_count