Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

abutils is a Python library for working with adaptive immune receptor repertoire (AIRR) data, including antibody and T-cell receptor sequences. It provides models, functions, and visualization tools for bulk AIRR datasets and serves as a core component of the ab[x] toolkit.

## Build and Test Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Run all tests
pytest

# Run a specific test file
pytest abutils/tests/test_sequence.py

# Run a specific test
pytest abutils/tests/test_sequence.py::test_function_name -v
```

## Code Architecture

### Module Namespace Pattern (scanpy-style)
The library uses a scanpy-inspired namespace pattern with short module aliases:
- `abutils.tl` - Tools: clustering, alignment, phylogenetics, clonify (lineage assignment)
- `abutils.pl` - Plots: bar, scatter, heatmap, kde, ridge, donut visualizations
- `abutils.io` - I/O: reading/writing FASTA, FASTQ, CSV, AIRR, Parquet formats
- `abutils.pp` - Preprocessing: data preparation utilities
- `abutils.cl` / `abutils.color` - Color utilities and palettes

### Core Data Models (`abutils/core/`)
Three primary classes represent AIRR data:
- **Sequence**: Container for individual antibody/TCR sequences with annotations. Accepts raw strings, dicts, BioPython SeqRecords, or iterables. Annotations stored in `.annotations` dict are accessible via bracket notation (`seq['v_gene']`).
- **Pair**: Represents paired heavy/light (BCR) or alpha/beta (TCR) chains. Contains multiple Sequence objects with automatic chain type detection via locus or V-gene.
- **Lineage**: Groups related Pair objects into clonal lineages for phylogenetic analysis.

### Tools Module (`abutils/tools/`)
- `alignment.py`: Multiple sequence alignment (FAMSA, MAFFT, MUSCLE) and pairwise alignment (local, global, semiglobal via parasail)
- `cluster.py`: Sequence clustering with CD-HIT, MMseqs2, or VSEARCH backends
- `clonify.py`: Lineage/clonotype assignment using CDR3 similarity with shared mutation bonus
- `phylo.py`: Phylogenetic tree construction with FastTree, visualization with baltic

### Bundled Binaries (`abutils/binaries/`)
External tools are bundled for convenience: CD-HIT, FastTree, MAFFT, MUSCLE, MMseqs2, VSEARCH, minimap2, fastp. Binaries are platform-specific (darwin/linux, amd64/arm64) and downloaded on first use if not included in the package. Access via `abutils.bin.get_path("tool_name")`.

### I/O Patterns
The `io` module provides consistent read/write functions:
- `read_*` / `to_*` functions for each format (fasta, fastq, csv, airr, parquet)
- `from_polars` / `to_polars` convert between Sequence/Pair objects and Polars DataFrames
- Pair data uses column suffixes `:0` (heavy) and `:1` (light) in tabular formats

### DataFrame Support
Both Pandas and Polars are supported, with Polars preferred internally for performance. Lazy evaluation (`pl.LazyFrame`) is used where possible.

## Key Conventions

- AIRR format uses tab-separated values with standard field names (`sequence_id`, `sequence`, `v_call`, `j_call`, `cdr3`, etc.)
- Sequence IDs default to `sequence_id`, sequences to `sequence` field
- Test files are in `abutils/tests/` and follow `test_*.py` naming
- Python 3.10+ required
1 change: 0 additions & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ include docs/*.txt
include abutils/core/*
include abutils/plots/*
include abutils/plots/models/*
include abutils/tenx/*
include abutils/tools/*
include abutils/utils/*
include abutils/utils/matrices/*
Expand Down
6 changes: 3 additions & 3 deletions abutils/tests/test_alignment.py
Original file line number Diff line number Diff line change
Expand Up @@ -532,7 +532,7 @@ def test_local_alignment_multiple_targets():


def test_local_alignment_seqrecord():
query = SeqRecord("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP")
query = SeqRecord(Seq("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"), id="query")
target = "MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"
alignment = local_alignment(query, target=target)
assert isinstance(alignment, PairwiseAlignment)
Expand Down Expand Up @@ -597,7 +597,7 @@ def test_global_alignment_multiple_targets():


def test_global_alignment_seqrecord():
query = SeqRecord("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP")
query = SeqRecord(Seq("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"), id="query")
target = "MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"
alignment = global_alignment(query, target=target)
assert isinstance(alignment, PairwiseAlignment)
Expand Down Expand Up @@ -662,7 +662,7 @@ def test_semiglobal_alignment_multiple_targets():


def test_semiglobal_alignment_seqrecord():
query = SeqRecord("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP")
query = SeqRecord(Seq("MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"), id="query")
target = "MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP"
alignment = semiglobal_alignment(query, target=target)
assert isinstance(alignment, PairwiseAlignment)
Expand Down
10 changes: 5 additions & 5 deletions abutils/tests/test_cluster.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,11 +183,11 @@ def test_cluster_with_fasta_file(nt_fasta_file):
def test_cluster_with_seqrecord_objects(nt_sequence_strings):
s1, s2 = nt_sequence_strings
seqs = [
SeqRecord(s1, "seq1"),
SeqRecord(s1, "seq2"),
SeqRecord(s1, "seq3"),
SeqRecord(s2, "seq4"),
SeqRecord(s2, "seq5"),
SeqRecord(Seq(s1), id="seq1"),
SeqRecord(Seq(s1), id="seq2"),
SeqRecord(Seq(s1), id="seq3"),
SeqRecord(Seq(s2), id="seq4"),
SeqRecord(Seq(s2), id="seq5"),
]
clusters = cluster(seqs, threshold=0.9)
assert isinstance(clusters, Clusters)
Expand Down
Loading