01 / Context

Purpose

What does it mean for two receptor observations to belong together? V/J identity, CDR3 similarity and sequence agreement can yield different partitions. ClonoDefs makes those choices explicit and records what each analysis includes and excludes.

02 / Implementation

Implementation

Annotate the assumptions

Read AIRR tables, validate receptor fields and record exclusions. Assign initial clones using V/J partitions and a deterministic lexical first-fit all-pairs similarity rule. Membership is independent of read abundance.

Choose a definition

Apply one of five clonotype definitions within each assigned clone. Exact-sequence rules and threshold-based rules serve different operational questions; no single partition is treated as biological ground truth.

Keep an auditable record

Export assignments, clone and clonotype counts, exclusions, per-clone AIRR tables and a configuration/input-hash manifest. Optional rooted minimum spanning distance trees summarize observed representatives.

Method / Operational choices

Five operational definitions

Each rule operates within an already assigned clone. Expand a definition to see its criteria.

L1Strict

Identical observed rearranged V(D)J nucleotide interval from annotated V start to J end.

L2IMGT-oriented

Unambiguous V/D/J alleles, frame and junction anchors, plus exact CDR3 amino acid; uses documented AIRR proxies.

L3B-DIVE-style

Same V family, J family and exact CDR3 amino-acid sequence, within an assigned clone.

L4Similarity

Same V gene and CDR3 similarity above a configured threshold using normalized Levenshtein or Hamming.

L5Length-controlled

Same V gene and CDR3 length, with positional amino-acid identity above a configured threshold.

03 / Evidence & interpretation

Evidence

Software evidence

The repository validation record reports 28 passing automated tests and example runs using L2 and L3 definitions. These checks demonstrate documented software behavior rather than biological correctness.

Limitations

  • Grouping depends on the chosen definition and similarity threshold. Deterministic all-pairs assignment is an operational convention; other partitions may exist.
  • L2 uses documented AIRR proxy fields and currently excludes ordinary light-chain records without D calls.
  • Optional distance trees connect observed representatives. They describe sequence distances rather than inferred ancestors or validated evolutionary lineages.

04 / Contribution

Contribution & attribution

Research need and design developed collaboratively within ComputImm Laboratory, with colleagues and supervisors; software implementation and deployment by Seyyed Mohammad Hamidi.

05 / Code & methods

Source & documentation

View ClonoDefs on GitHub (opens in a new tab)
Scientific definitions (opens in a new tab)Software validation record (opens in a new tab)Grouping implementation (opens in a new tab)

Source reviewed at commit bdf731398a78, 28 October 2026. Documentation links are pinned to this snapshot.