ClonalTree
Minimum-spanning-tree B-cell lineage reconstruction
Accepts:TSVCSV
What it does
ClonalTree reconstructs B-cell receptor lineage trees from clonally related sequences. It uses a minimum-spanning-tree algorithm combined with genotype abundance information to infer parsimonious trees representing the evolutionary relationships within a clone.
In this framework it runs an AIRR/IMGT processing pipeline — formatting and labelling, initial clustering, optional refinement, two-level clonotype grouping, and clonal-tree construction — and outputs trees in Newick format plus parent/cost tables.
- Minimum-spanning-tree lineage reconstruction with abundance weighting
- AIRR/IMGT formatting, clustering and refinement pipeline
- Configurable distance methods (V, J, CDR3) and clonotype grouping (L1–L5)
- Optional tree revision
- Newick output plus parent-relationship / cost tables
Accepted input types
| Input type | What the framework does with it |
|---|---|
| TSV | AIRR / IMGT HighV-QUEST table (tab-separated), fed into the formatting and clustering pipeline. Enable column mapping if headers differ from the canonical keys. |
| CSV | Comma-separated table; converted to TSV when possible before the pipeline runs. |
Form fields
Every field shown in this method's form, generated from the package's field definitions so it always matches the live form. The mapping column is filled only where a field corresponds clearly to a native method parameter.
Input Mapping
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Enable input column mapping doMapping | When true, map uploaded tabular headers to canonical ClonalTree AIRR keys before safe conversions. | Yes / No | No | N/A (wrapper-specific) | Always |
Sequence ID column column_map.sequence_id | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Full sequence column column_map.sequence | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Productive column column_map.productive | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
V call column column_map.v_call | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
D call column column_map.d_call | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
J call column column_map.j_call | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
V identity column column_map.v_identity | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
D identity column column_map.d_identity | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
J identity column column_map.j_identity | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Sequence alignment column column_map.sequence_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
J sequence alignment column column_map.j_sequence_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Run refinement step is enabled |
V sequence alignment column column_map.v_sequence_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Run refinement step is enabled |
J sequence alignment aa column column_map.j_sequence_alignment_aa | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Run refinement step is enabled |
V sequence alignment aa column column_map.v_sequence_alignment_aa | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled and Run refinement step is enabled |
Junction aa column column_map.junction_aa | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR3 aa column column_map.cdr3_aa | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR1 column column_map.cdr1 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR2 column column_map.cdr2 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR3 nucleotide column column_map.cdr3 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
FWR1 column column_map.fwr1 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
FWR2 column column_map.fwr2 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
FWR3 column column_map.fwr3 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
FWR4 column column_map.fwr4 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
V germline alignment column column_map.v_germline_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
D germline alignment column column_map.d_germline_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
J germline alignment column column_map.j_germline_alignment | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
NP1 column column_map.np1 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
NP2 column column_map.np2 | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
V sequence start column column_map.v_sequence_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR1 start column column_map.cdr1_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR1 end column column_map.cdr1_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR2 start column column_map.cdr2_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR2 end column column_map.cdr2_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR3 start column column_map.cdr3_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
CDR3 end column column_map.cdr3_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
D sequence start column column_map.d_sequence_start | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
D sequence end column column_map.d_sequence_end | — | text | — | N/A (wrapper-specific) | Shown when Enable input column mapping is enabled |
Run Selection
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Run label run_name | Optional label used as the output prefix; defaults to the uploaded file name without extension. | text | — | — | Always |
Unique sequence abundance threshold abundance_threshold | Minimum count retained during AIRR formatting (format_labeling_imgt_airr.py -t). | integer (≥ 1) | 3 | ClonalTree format_labeling_imgt_airr.py -t (minimum count retained during formatting). | Always |
Top clones for trees top_clonesRequired | Number of top clones to analyze (top_clones.py -s / setting NUMBER_TOP_CLONE). | integer (≥ 1) | 5 | ClonalTree top_clones.py -s / NUMBER_TOP_CLONE (number of top clones analysed). | Always |
Clonotypes per clone clonotypes_per_cloneRequired | Comma/space-separated clonotype counts per selected clone (e.g. "30, 200" or "all"). | text | 30, 200 | — | Always |
Clone Clustering
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Initial clone CDR3 threshold clone_cdr3_similarityRequired | Initial clustering threshold (initial_clustering.py -t). | number (0–1) | 0.7 | ClonalTree initial_clustering.py -t (initial CDR3 clustering threshold). | Always |
Refinement
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Run refinement step use_refinement | Run refinement.py before two-level clonotype grouping. | Yes / No | Yes | Runs ClonalTree refinement.py before clonotype grouping. | Always |
V distance method v_distance | Refinement V-distance mode: 1=Binary, 2=Levenshtein, 3=GIANA, 4=K-mers. | 1, 2, 3, 4 | 1 | Refinement V-distance mode (1 = Binary, 2 = Levenshtein, 3 = GIANA, 4 = K-mers). | Always |
J distance method j_distance | Refinement J-distance mode: 1=Binary, 2=Levenshtein, 3=GIANA, 4=K-mers. | 1, 2, 3, 4 | 2 | Refinement J-distance mode (1 = Binary, 2 = Levenshtein, 3 = GIANA, 4 = K-mers). | Always |
CDR3 distance method cdr3_distance | Refinement CDR3-distance mode: 1=Binary, 2=Levenshtein, 3=GIANA, 4=K-mers. | 1, 2, 3, 4 | 2 | Refinement CDR3-distance mode (1 = Binary, 2 = Levenshtein, 3 = GIANA, 4 = K-mers). | Always |
Distance combine method combine_distance | Refinement combine mode: 1=Mean, 2=Weighted Mean, 3=Harmonic Mean. | 1, 2, 3 | 1 | Refinement combine mode (1 = Mean, 2 = Weighted Mean, 3 = Harmonic Mean). | Always |
Merge singleton clones merge_singleton | Allow refinement to merge singleton clusters (setting MERGE_SINGLETON). | Yes / No | Yes | Refinement MERGE_SINGLETON setting. | Always |
Clonotype Grouping
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Clonotype definition method clonotype_method | Two-level clonotype method: L1, L2, L3, L4, or L5. | L1, L2, L3, L4, L5 | L3 | Two-level clonotype definition method (L1–L5). | Always |
Clonotype similarity threshold clonotype_similarity_threshold | Similarity threshold used by methods L4 and L5. | number (0–1) | 0.8 | — | Always |
Tree Construction
| Field | What it is / used for | Allowed values | Default | Maps to method parameter | Visible when |
|---|---|---|---|---|---|
Weight trees by abundance tree_use_abundance | clonal_tree.py -a 0 enables abundance weighting. | Yes / No | Yes | ClonalTree clonal_tree.py -a (abundance weighting). | Always |
Enable tree revision tree_revision | clonal_tree.py -r 0 enables revision. | Yes / No | Yes | ClonalTree clonal_tree.py -r (tree revision). | Always |
Conditional fields & behaviour
Fields that appear or change based on other inputs
- The column-mapping fields appear only when the mapping toggle is on; several alignment-column mappings additionally require the refinement step to be enabled.
- The clonotype similarity threshold is used by the L4 and L5 grouping methods.