Skip to content

README.md

Latest commit

 

History

History
54 lines (41 loc) · 3 KB

README.md

File metadata and controls

54 lines (41 loc) · 3 KB
Raw

Examples

Three small (10-row) TCR-beta files in the formats CRAFT consumes, plus a quickstart.py that loads the trained model and produces sequence embeddings.

The TCR sequences here are illustrative only — they are realistic-looking but synthetic, so nothing in this directory contains patient data.

File reference

File Format Used by Notes
example_adaptive_immunoseq.tsv Adaptive immunoSEQ export model_training/00_pre_process_data.py, ocscc_analyses/01_craft_00_preprocess.py Bulk-repertoire input. Required columns: nucleotide, vIndex, n1Index, dIndex, n2Index, jIndex, cdr3Length, vMaxResolved, dMaxResolved, jMaxResolved, cloneResolved, sequenceStatus, frequencyCount (%), seq_index.
example_airr_c.tsv AIRR-C standard Single-cell pipelines (after IgBLAST realignment to AIRR-C TSV) Universal interchange format for adaptive-immune-receptor data. CRAFT does not consume AIRR-C directly — convert via IgBLAST first or use craft.igblast.TCRJunctionAnalyzer.process_dataframe_complete to produce the post-IgBLAST schema below.
example_post_igblast.csv Post-IgBLAST CSV mcpas_gbm_analyses/igblast_*, mcpas_gbm_analyses/01_craft_00_preprocess.py (single-cell) Required columns: v_gene, j_gene, CDR3_nt, index. The index column is the per-cell barcode that downstream GeneDatasetInference carries through to the embedding output.

Quickstart

# 1. Install CRAFT in editable mode (from the repo root, not from examples/)
pip install -e .

# 2. Set your project directory once.
export CRAFT_PROJECT_DIR=$PWD

# 3. Download the trained model checkpoint and tokenizers from Zenodo
#    (DOI 10.5281/zenodo.19891746 — see top-level README for the curl recipe).
#    Final on-disk layout under $CRAFT_PROJECT_DIR:
#       tokenizers/cdr3_tokenizer.json
#       tokenizers/bart_custom_tokenizer/{added_tokens,merges,special_tokens_map,tokenizer_config,vocab}.{json,txt}
#       models/06_model_phase3c/final_model.pth

# 4. Run the example.
python examples/quickstart.py --input examples/example_adaptive_immunoseq.tsv

The quickstart will print the embedding tensor shape for each of the 10 input clones and write the per-clone embedding to examples/quickstart_embeddings.npz.

Format crosswalk

The internal CRAFT pipeline operates on tokenized parquet files derived from one of the three input formats above. The tokenization steps (V/D/J gene tokenizer in craft.embeddings, CDR3 BPE tokenizer in craft.training) are the same regardless of which input format you start from — only the preprocessing differs.

Adaptive immunoSEQ TSV ──┐
                          ├──► craft.embeddings.format_tcr_dataframe ──► tokenized parquet ──► CRAFT model
Post-IgBLAST CSV ────────┘                       (+craft.embeddings.tokenize_*)
                                                         ▲
AIRR-C TSV ──► IgBLAST realignment via craft.igblast ─────┘