### Install AMULETY from Source

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Install AMULETY after downloading or cloning the source code.

```bash
pip install .
```

--------------------------------

### Install ML Dependencies

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Installs necessary Python packages for the machine learning tutorial. Ensure you have pip installed.

```python
!pip install pandas numpy scikit-learn torch matplotlib seaborn
```

--------------------------------

### Install AMULETY from Source

Source: https://github.com/immcantation/amulety/blob/main/README.md

Installs AMULETY from its GitHub repository. This method requires cloning the repository and then installing with pip.

```bash
git clone https://github.com/immcantation/amulety.git
cd amulety
pip install -e .
```

--------------------------------

### Install Dependencies

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Installs necessary libraries for the tutorial, including antiberty, transformers, datasets, scikit-learn, biopython, and pyarrow. Run this once per session.

```python
#!pip install -q antiberty transformers datasets scikit-learn biopython pyarrow
```

--------------------------------

### Download Example Data and Reference Database

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Create a tutorial directory and download an example BCR sequence file (AIRR format) and the IgBlast reference database using wget.

```bash
# Create tutorial directory and download example data
! mkdir -p tutorial
! wget -P tutorial https://zenodo.org/records/17186858/files/AIRR_subject1_FNA_d0_1_Y1.tsv
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Install pre-commit hooks to automatically check code quality before committing. Run pre-commit manually if needed.

```bash
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
```

```bash
$ pre-commit .
```

--------------------------------

### Install AMULETY with Pip

Source: https://github.com/immcantation/amulety/blob/main/README.md

Installs AMULETY using pip. IgBlast must be installed separately if translations are needed.

```bash
pip install amulety
```

--------------------------------

### Verify AMULETY Installation

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Run this command to check if AMULETY is installed correctly and to display the help message, showing available commands and options.

```bash
! amulety --help
```

--------------------------------

### Download TCR example data

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Download the sample TCR data file from Zenodo for testing purposes. The data is saved in the 'tutorial' directory.

```bash
# Download TCR example data
! wget -P tutorial https://zenodo.org/records/17186858/files/AIRR_tcr_sample.tsv
```

--------------------------------

### Set Up Local Development Environment

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Create a conda environment and install the AMULETY package in editable mode for local development.

```bash
$ conda create -n amulety python=3.11
$ cd amulety/
$ pip install -e .
```

--------------------------------

### Import Amulety Library

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Imports the necessary Amulety library for the tutorial. Ensure Amulety is installed.

```python
from amulety import embed_airr

print("All libraries imported successfully!")
```

--------------------------------

### Install AMULETY

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Install the AMULETY package using pip. This is the first step before using the library for generating sequence embeddings.

```python
# Install Amulety
!pip install amulety

```

--------------------------------

### Install AMULETY with Conda and Python

Source: https://github.com/immcantation/amulety/blob/main/README.md

Installs AMULETY and explicitly includes Python if it was not installed correctly in the previous step.

```bash
conda install -c conda-forge -c bioconda python amulety --strict-channel-priority
```

--------------------------------

### Install Immune2vec Dependencies

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Install the specific Python dependencies required for the Immune2vec model, including a precise version of gensim.

```bash
python3 -m pip install gensim==3.8.3
pip3 install ray
```

--------------------------------

### Check Amulety Dependencies

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use this command to verify if all necessary optional dependencies for Amulety models are installed. Missing dependencies will be listed with installation instructions.

```bash
# Check which optional dependencies are missing
! amulety check-deps
```

--------------------------------

### Import Libraries and Setup Device

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Imports essential Python libraries for data manipulation, machine learning, and deep learning. It also checks for CUDA availability and sets the device to GPU if possible, otherwise defaults to CPU.

```python
import os
import random
from collections import Counter

import numpy as np
import pandas as pd
import torch

from sklearn.metrics import (
    precision_score, recall_score, f1_score,
    matthews_corrcoef, roc_auc_score,
    average_precision_score, balanced_accuracy_score
)

from sklearn.model_selection import StratifiedGroupKFold
from datasets import Dataset, DatasetDict, ClassLabel
import transformers
from transformers import (
    AutoTokenizer,
    AutoModelForSequenceClassification,
    TrainingArguments,
    Trainer
)

import antiberty

print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
device
```

--------------------------------

### Install AMULETY with Conda

Source: https://github.com/immcantation/amulety/blob/main/README.md

Installs AMULETY and its IgBlast dependency using conda. Requires Python 3.8 or higher.

```bash
conda install -c conda-forge -c bioconda amulety --strict-channel-priority
```

--------------------------------

### Install AMULETY with AbLang Support (Python < 3.14)

Source: https://github.com/immcantation/amulety/blob/main/README.md

Creates a dedicated conda environment with Python 3.13 to ensure AbLang compatibility, as AbLang does not support Python 3.14 and above.

```bash
conda create -n amulety-ablang python=3.13
conda activate amulety-ablang
pip install amulety ablang
```

--------------------------------

### Use Immune2vec Model with Custom Path

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Run AMULETY with the Immune2vec model, specifying the installation path to the cloned repository.

```bash
amulety embed --model immune2vec --installation-path /path/to/immune2vec_model --input-airr data.tsv --chain H --output-file-path output.pt
```

--------------------------------

### Embed Sequences with Amulety

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

This example demonstrates how to embed sequences using the Amulety CLI. Specify the input AIRR file, the chain type (e.g., HL for heavy-light pairs), the desired embedding model (e.g., antiberta2), and the output file path.

```bash
amulety embed --chain HL --model antiberta2 --output-file-path out.pt airr_rearrangement.tsv
```

--------------------------------

### Clone AMULETY Repository

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Clone the public repository from GitHub to get the source code for AMULETY.

```bash
git clone https://github.com/immcantation/amulety
```

--------------------------------

### Load AntiBERTy Model and Tokenizer

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Loads the AntiBERTy model and its corresponding tokenizer. Ensure the antiberty package is installed and model files are accessible.

```python
def get_antiberty_paths():
    """Locate AntiBERTy model + vocab from the antiberty package."""
    project_path = os.path.dirname(os.path.realpath(antiberty.__file__))
    trained_dir = os.path.join(project_path, "trained_models")
    model_dir = os.path.join(trained_dir, "AntiBERTy_md_smooth")
    vocab = os.path.join(trained_dir, "vocab.txt")
    print("AntiBERTy model:", model_dir)
    print("AntiBERTy vocab:", vocab)
    return model_dir, vocab

def load_antiberty_classifier(num_labels: int = 2):
    """Load AntiBERTy as a sequence-classification model + tokenizer."""
    model_dir, vocab = get_antiberty_paths()
    tokenizer = transformers.BertTokenizer(
        vocab_file=vocab,
        do_lower_case=False
    )
    model = AutoModelForSequenceClassification.from_pretrained(
        model_dir,
        num_labels=num_labels
    )
    model.to(device)
    size = sum(p.numel() for p in model.parameters())
    print(f"Model size: {size/1e6:.2f}M parameters")
    return model, tokenizer
```

--------------------------------

### Embed sequences with custom light chain selection using quality score

Source: https://github.com/immcantation/amulety/blob/main/docs/cli.md

Specify a custom numeric column like 'quality_score' to guide AMULETY's light chain selection when using paired chains (HL). The chain with the highest value in this column will be chosen.

```bash
amulety embed --chain HL --model antiberta2 --duplicate-col quality_score --output-file-path embeddings.pt input.tsv
```

--------------------------------

### Embed BCR Sequences with Amulety CLI

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use this command to generate embeddings for BCR sequences from an AIRR file. Specify the input file, chain type, embedding model, batch size, and output path. The 'antiberty' model is used in this example.

```bash
! amulety embed --input-airr tutorial/AIRR_subject1_FNA_d0_1_Y1_translated.tsv --chain H --model antiberty --batch-size 2 --output-file-path tutorial/test_embedding.pt
```

--------------------------------

### Embed AIRR Data with AntiBERTa2

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use the `amulety embed` command to generate sequence embeddings from AIRR data. Specify the input file, chain type, model, batch size, and output path. This example uses the AntiBERTa2 model.

```bash
amulety embed --input-airr tutorial/AIRR_subject1_FNA_d0_1_Y1_translated.tsv --chain H --model antiberta2 --batch-size 2 --output-file-path tutorial/AIRR_subject1_FNA_d0_1_Y1_antiberta2.pt
```

--------------------------------

### Print AMULETY Usage Help

Source: https://github.com/immcantation/amulety/blob/main/README.md

Displays the command-line usage help for the AMULETY package.

```bash
amulety --help
```

--------------------------------

### Download BCR AIRR Dataset

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Downloads the tutorial dataset in AIRR format. This command creates a 'tutorial' directory if it doesn't exist and saves the dataset within it.

```bash
! mkdir -p tutorial
! wget -P tutorial https://zenodo.org/records/17186858/files/ML_bcr_airr_dataset.tsv
```

--------------------------------

### Set up Fine-tuning Parameters for AntiBERTy

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Configures training arguments, including output directory, evaluation and saving strategies, learning rate, batch size, number of epochs, and model loading behavior. Ensures reproducibility by setting a random seed.

```python
set_seed(1)

FOLD_ID = 1
OUT_PATH = os.path.join(OUTPUT_DIR, f"{RUN_ID}_Fold_{FOLD_ID}")
os.makedirs(OUT_PATH, exist_ok=True)
print("Saving checkpoints to:", OUT_PATH)

training_args = TrainingArguments(
    output_dir=OUT_PATH,
    evaluation_strategy="epoch",
    save_strategy="epoch",
    logging_strategy="epoch",
    learning_rate=LR,
    per_device_train_batch_size=BATCH_SIZE,
    per_device_eval_batch_size=BATCH_SIZE,
    num_train_epochs=N_EPOCHS,
    warmup_ratio=0.0,
    load_best_model_at_end=True,
    metric_for_best_model="auc",
    lr_scheduler_type="linear",
    seed=1
)

trainer = Trainer(
    model=model,
    args=training_args,
    tokenizer=tokenizer,
    train_dataset=tokenized_datasets["train"],
    eval_dataset=tokenized_datasets["validation"],
    compute_metrics=compute_metrics,
)
```

--------------------------------

### Download and Extract IgBLAST Reference Database

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use wget to download the IgBLAST reference database zip file and unzip to extract its contents. The rm command cleans up the downloaded zip file. Ensure the 'tutorial' directory exists.

```bash
! wget -P tutorial -c https://github.com/nf-core/test-datasets/raw/airrflow/database-cache/igblast_base.zip
```

```bash
! unzip tutorial/igblast_base.zip -d tutorial
```

```bash
! rm tutorial/igblast_base.zip
```

--------------------------------

### Configure Training Parameters

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Sets up configuration variables for the fine-tuning process, including the sequence column to use, the dataset variant, data and output directories, training hyperparameters like batch size and learning rate, and random seeds for reproducibility. A unique run ID is generated based on these settings.

```python
# Which column in the parquet to use as sequences
MODEL_TYPE = "HL"  

# Which dataset variant to use
SEQUENCE_SCOPE = "CDR3"  

# Path to your data directory
DATA_DIR = "../data/" 

# Path where models and logs will be saved
OUTPUT_DIR = "../models/"

# Training hyperparameters
BATCH_SIZE = 64        
LR = 1e-5              
N_EPOCHS = 10          

RANDOM_STATE_OUTER = 7 if SEQUENCE_SCOPE == "CDR3" else 9
RANDOM_STATE_INNER = 1

RUN_ID = f"S_antiBERTy_{{MODEL_TYPE}}_fine_tuning_{{SEQUENCE_SCOPE}}"
print("Run ID:", RUN_ID)
print("Data dir:", DATA_DIR)
print("Output dir:", OUTPUT_DIR)
```

--------------------------------

### Display Amulety Embed Help

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Run this command to display the help message for the `amulety embed` command, showing all available options and their descriptions.

```python
! amulety embed --help
```

--------------------------------

### Python API for Immune2vec Embeddings

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Generate embeddings using the Immune2vec model via its Python API, providing the sequences and installation path.

```python
from amulety.protein_embeddings import immune2vec
embeddings = immune2vec(sequences, installation_path='/path/to/immune2vec_model')
```

--------------------------------

### Train the AntiBERTy Model

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Initiates the fine-tuning process for the AntiBERTy model using the configured trainer and datasets. The training results, including metrics, are captured.

```python
train_result = trainer.train()
train_result.metrics
```

--------------------------------

### Clone AMULETY Repository

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Clone your forked AMULETY repository locally to begin development.

```bash
$ git clone git@github.com:<your_name_here>/amulety.git
```

--------------------------------

### Check AMULETY Dependencies

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Use the command-line interface to check for missing dependencies required by AMULETY models.

```bash
amulety check-deps
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Stage, commit, and push your changes to your forked repository on GitHub.

```bash
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

--------------------------------

### Download AMULETY Source Tarball

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Download the source code tarball from the GitHub repository.

```bash
curl -OJL https://github.com/immcantation/amulety/tarball/master
```

--------------------------------

### Run Local Tests

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Execute the test suite locally to ensure your changes do not break existing functionality.

```bash
pytest .
```

--------------------------------

### Use AMULETY via Docker Alias

Source: https://github.com/immcantation/amulety/blob/main/README.md

Demonstrates using the previously created AMULETY Docker alias to embed antibody sequences using the 'antiberta2' model.

```bash
amulety embed --input-airr AIRR_translated.tsv --chain H --model antiberta2 --output-file-path antiberta2_embeddings.tsv
```

--------------------------------

### Data Splitting and Preparation

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Splits data into training, validation, and test sets using cross-validation and prepares it for Hugging Face Datasets. This code is typically used at the beginning of a fine-tuning process.

```python
train_df = pd.DataFrame({"sequence": X_train.values, "labels": y_train})
val_df   = pd.DataFrame({"sequence": X_val.values,   "labels": y_val})
test_df  = pd.DataFrame({"sequence": X_test.values,  "labels": y_test})

raw_datasets = DatasetDict({
    "train": Dataset.from_pandas(train_df.reset_index(drop=True)),
    "validation": Dataset.from_pandas(val_df.reset_index(drop=True)),
    "test": Dataset.from_pandas(test_df.reset_index(drop=True)),
})
```

--------------------------------

### Export Fine-tuned Model for Amulety

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Saves the fine-tuned AntiBERTy model and its tokenizer to a specified directory. This prepares the model for integration with Amulety as a custom model.

```python
from pathlib import Path

# Directory where we will save the fine-tuned model for Amulety
CUSTOM_MODEL_PATH = Path(OUTPUT_DIR) / f"{RUN_ID}_amulety_custom"
CUSTOM_MODEL_PATH.mkdir(parents=True, exist_ok=True)

# `trainer` already holds the fine-tuned best model because we used `load_best_model_at_end=True`
# but to be explicit, we save the current `model` and `tokenizer`.
model.save_pretrained(CUSTOM_MODEL_PATH)
tokenizer.save_pretrained(CUSTOM_MODEL_PATH)

print("Saved fine-tuned model for Amulety at:", CUSTOM_MODEL_PATH)
```

--------------------------------

### Check AMULETY Dependencies in Python

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Use the Python API to check for missing dependencies required by AMULETY models.

```python
from amulety.utils import check_dependencies
check_dependencies()
```

--------------------------------

### Create AMULETY Docker Alias

Source: https://github.com/immcantation/amulety/blob/main/README.md

Creates a shell alias to simplify running AMULETY commands within a Docker container. This allows using 'amulety' directly instead of the full 'docker run' command.

```bash
alias amulety="docker run -itv `pwd`:`pwd` -w `pwd` -u $(id -u):$(id -g) immcantation/amulety amulety"
```

--------------------------------

### Load and Prepare BCR AIRR Dataset

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Downloads a BCR AIRR dataset from a Zenodo URL and filters it to include only cells that have both heavy (H) and light (L) chains.

```python
airr_demo = pd.read_csv("https://zenodo.org/records/17186858/files/ML_bcr_airr_dataset.tsv", sep='\t')
# cells that have at least one H and one L
mask_both = (
    airr_demo.groupby("cell_id")["chain_type"]
      .agg(lambda x: set(x))
      .pipe(lambda s: s[s.apply(lambda st: {"H", "L"}.issubset(st))])
)
cells_with_both = mask_both.index
```

--------------------------------

### Create a New Branch

Source: https://github.com/immcantation/amulety/blob/main/docs/contributing.md

Create a new branch for your bug fix or feature development.

```bash
$ git checkout -b name-of-your-bugfix-or-feature
```

--------------------------------

### Apply Tokenization to Datasets

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Applies the defined preprocessing function to the raw datasets in a batched manner and removes the original sequence column. This prepares the data for the model.

```python
tokenized_datasets = raw_datasets.map(
    preprocess_function,
    batched=True,
    remove_columns=["sequence"],
)
```

--------------------------------

### Load and Preprocess Data

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Loads sequence data from a parquet file and preprocesses it for AntiBERTy. This includes sequence length truncation, special token replacement, and formatting.

```python
MAX_LENGTH = 512 - 2  # AntiBERTy max length minus specials

def load_data(scope: str = "CDR3", model_type: str = "HL"):
    if scope == "FULL":
        filename = "S_FULL.parquet"
        print("Loading full-length sequences...")
    else:
        filename = "S_CDR3.parquet"
        print("Loading CDR3 sequences...")

    path = os.path.join(DATA_DIR, filename)
    if not os.path.exists(path):
        raise FileNotFoundError(f"Could not find {path}. Please check DATA_DIR and filename.")

    df = pd.read_parquet(path)

    X = df[model_type].apply(lambda s: s[:MAX_LENGTH])
    X = X.str.replace("<cls><cls>", "[CLS][CLS]", regex=False)
    X = X.apply(insert_space_every_other_except_cls)

    y = np.isin(df["label"], ["S+", "S1+", "S2+"]).astype(int)
    groups = df["subject"].values

    print(f"Total sequences: {len(X)}")
    print(f"Unique donors: {len(np.unique(groups))}")
    print("Label counts:", Counter(y))

    return X, y, groups, df

X, y, y_groups, raw_df = load_data(SEQUENCE_SCOPE, MODEL_TYPE)
```

--------------------------------

### Embed Using a Local Custom Model

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Use this command to generate embeddings from a local custom model. Ensure the model is compatible with HuggingFace transformers and specify all required parameters like embedding dimension and max length.

```bash
amulety embed --chain HL --model custom --model-path "/path/to/local/model" --embedding-dimension 768 --max-length 256 --output-file-path embeddings.pt input.tsv
```

--------------------------------

### Translate IGBlast with Amulety CLI

Source: https://github.com/immcantation/amulety/blob/main/docs/cli.md

Use the `translate-igblast` command to translate IGBLAST results. The `--verbose` flag enables DEBUG level logging.

```bash
amulety translate-igblast --verbose
amulety translate-igblast -v
amulety translate-igblast --help
```

--------------------------------

### Use Custom Model with AMULETY

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Embeddings using a custom model from HuggingFace, specifying model path, embedding dimension, and max length.

```bash
amulety embed --chain HL --model custom --model-path "your-username/your-custom-model" --embedding-dimension 1280 --max-length 512 --output-file-path embeddings.pt input.tsv
```

--------------------------------

### Create Random Baseline for Model Comparison

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

This code prepares a random baseline for model comparison by shuffling the embeddings. It creates a copy of the input features (`X_final`) and then randomly permutes both the rows and columns to ensure complete randomization. This serves as a benchmark to validate the meaningfulness of the learned embeddings.

```python
# Create random baseline by shuffling embeddings
print("Running random baseline comparison...")

# Shuffle the embeddings while keeping labels intact
# np.random.seed(42)
X_random = X_final.copy()
# Shuffle both rows and columns to completely randomize
X_random = X_random[np.random.permutation(X_random.shape[0])]
X_random = X_random[:, np.random.permutation(X_random.shape[1])]
```

--------------------------------

### Translate Nucleotides to Amino Acids with Amulety CLI

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use the `amulety translate-igblast` command to convert nucleotide sequences in an AIRR file to amino acid sequences. Specify the input AIRR file, the output directory, and the IgBlast reference directory.

```bash
! amulety translate-igblast -i tutorial/AIRR_subject1_FNA_d0_1_Y1.tsv -o tutorial -r tutorial/igblast_base
```

--------------------------------

### Generate Embeddings with AntiBERTa2

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

This snippet shows the command to generate embeddings using the AntiBERTa2 model. It logs the process and indicates where the output is saved.

```bash
2025-09-24 11:44:40,872 - INFO - Generated embeddings with dimensions torch.Size([95, 1024])
2025-09-24 11:44:40,873 - INFO - Saving embedding as a pickled torch object.
2025-09-24 11:44:40,875 - INFO - Saving sequence filtered metadata as TSV file.
2025-09-24 11:44:40,881 - INFO - Saved embedding at tutorial/AIRR_subject1_FNA_d0_1_Y1_antiberta2.pt
```

--------------------------------

### Clone Immune2vec Repository

Source: https://github.com/immcantation/amulety/blob/main/docs/installation.md

Clone the Immune2vec model repository from Bitbucket.

```bash
git clone https://bitbucket.org/yaarilab/immune2vec_model.git
```

--------------------------------

### Compare Amulety Embeddings vs. Random Baseline Performance

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

This code compares the performance metrics (F1 score, MCC, accuracy) between Amulety embeddings and the random baseline. It calculates means, standard deviations, and percentage improvement, then prints a summary table.

```python
# Compare results
print("Performance Comparison: Amulety Embeddings vs Random Baseline")
print("=" * 60)

comparison_data = []
for metric in ['f1_score', 'mcc_score', 'accuracy']:
    amulety_mean = results_df[metric].mean()
    amulety_std = results_df[metric].std()
    random_mean = random_df[metric].mean()
    random_std = random_df[metric].std()
    improvement = ((amulety_mean - random_mean) / random_mean) * 100
    
    comparison_data.append({
        'Metric': metric.upper(),
        'Amulety': f"{amulety_mean:.4f} ± {amulety_std:.4f}",
        'Random': f"{random_mean:.4f} ± {random_std:.4f}",
        'Improvement': f"{improvement:.1f}%"
    })
    
    print(f"{metric.upper()}:")
    print(f"  Amulety Embeddings: {amulety_mean:.4f} ± {amulety_std:.4f}")
    print(f"  Random Baseline:    {random_mean:.4f} ± {random_std:.4f}")
    print(f"  Improvement:        {improvement:.1f}%")
    print()

comparison_df = pd.DataFrame(comparison_data)
print("Summary Table:")
print(comparison_df.to_string(index=False))
```

--------------------------------

### Compute Metrics for Trainer

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Defines a callback function for Hugging Face's Trainer to compute various evaluation metrics, including precision, recall, F1-score, AUC, and MCC.

```python
def compute_metrics(eval_pred):
    """Metrics callback for Hugging Face Trainer."""
    logits, labels = eval_pred
    probs = torch.softmax(torch.tensor(logits), dim=1).numpy()[:, 1]
    preds = np.argmax(logits, axis=1)

    return {
        "precision": precision_score(labels, preds),
        "recall": recall_score(labels, preds),
        "f1_weighted": f1_score(labels, preds, average="weighted"),
        "apr": average_precision_score(labels, probs),
        "balanced_accuracy": balanced_accuracy_score(labels, preds),
        "auc": roc_auc_score(labels, probs),
        "mcc": matthews_corrcoef(labels, preds),
    }
```

--------------------------------

### Prepare Labels and Filter Missing Data

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Prepares labels for a prediction task by selecting a target column, removing samples with missing labels, and printing dataset statistics. Ensure 'heavy_sample' DataFrame and 'X_embeddings' are available.

```python
# Prepare labels for prediction task
# Example: Predict V gene family
target_column = 'v_call_family'
y_labels = heavy_sample[target_column].values
subjects = heavy_sample['subject'].values

# Remove samples with missing labels
valid_mask = pd.notna(y_labels)
X_embeddings = X_embeddings[valid_mask]
y_labels = y_labels[valid_mask]
subjects = subjects[valid_mask]

print(f"Data after removing missing labels:")
print(f"Samples: {len(y_labels)}")
print(f"Features: {X_embeddings.shape[1]}")
print(f"Unique subjects: {len(np.unique(subjects))}")

# Check class distribution
class_counts = Counter(y_labels)
print(f"\nClass distribution:")
for class_name, count in class_counts.most_common():
    print(f"  {class_name}: {count}")
```

--------------------------------

### Embed sequences with custom light chain selection using UMI count

Source: https://github.com/immcantation/amulety/blob/main/docs/cli.md

Use the '--duplicate-col umi_count' option to instruct AMULETY to select the light chain based on the UMI count when processing paired chains (HL). This ensures the most abundant UMI is prioritized.

```bash
amulety embed --chain HL --model antiberta2 --duplicate-col umi_count --output-file-path embeddings.pt input.tsv
```

--------------------------------

### Prepare BCR Data for Embedding

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Filters BCR data to include only heavy chains and samples a subset for demonstration purposes. Adjust sample size based on computational resources.

```python
# Prepare data for embedding
# Filter for heavy chains only for this example
heavy_chains = bcr_data[bcr_data['chain_type'] == 'H'].copy()
print(f"Using {len(heavy_chains)} heavy chain sequences for embedding")

# Take a subset for demonstration 
# please adjust size based on computational resources)
sample_size = min(10000, len(heavy_chains))
heavy_sample = heavy_chains.sample(n=sample_size, random_state=42).reset_index(drop=True)
print(f"Working with {len(heavy_sample)} sequences for demonstration")
```

--------------------------------

### Embed sequences with default light chain selection

Source: https://github.com/immcantation/amulety/blob/main/docs/cli.md

Use this command to embed sequences when paired chains (HL) are specified. AMULETY automatically selects the best light chain using the 'duplicate_count' column by default.

```bash
amulety embed --chain HL --model antiberta2 --output-file-path embeddings.pt input.tsv
```

--------------------------------

### Embed Heavy and Light Chains with AbLang

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Use the `amulety embed` command to process AIRR data and generate embeddings. Specify the input file, chain type (H+L for both heavy and light chains), the model to use (ablang), batch size, and output file path.

```bash
! amulety embed --input-airr tutorial/AIRR_subject1_FNA_d0_1_Y1_translated.tsv --chain H+L --model ablang --batch-size 2 --output-file-path tutorial/AIRR_subject1_FNA_d0_1_Y1_ablang.pt
```

--------------------------------

### Run AMULETY using Docker Container

Source: https://github.com/immcantation/amulety/blob/main/README.md

Executes AMULETY within a Docker container, mounting the current directory for input/output and setting the working directory. This command embeds TCR sequences using the 'immune2vec' model.

```bash
docker run -itv `pwd`:`pwd` -w `pwd` -u $(id -u):$(id -g) immcantation/amulety amulety embed --input-airr tests/AIRR_rearrangement_translated_mixed.tsv --chain H --model immune2vec --output-file-path test_fixed.tsv --cache-dir /tmp/cache
```

--------------------------------

### Load and Freeze AntiBERTy Model

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Loads a pre-trained AntiBERTy classifier and freezes the layers except for the last N layers. This is useful for fine-tuning specific parts of the model.

```python
model, tokenizer = load_antiberty_classifier(num_labels=2)
model = freeze_antiberty_layers(model, train_last_n_layers=3)
```

--------------------------------

### Load and Inspect BCR AIRR Data

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Loads the downloaded BCR AIRR dataset using pandas and prints its shape and column names. Displays the first few rows of the dataframe.

```python
# Load the BCR AIRR dataset
bcr_data = pd.read_csv("tutorial/ML_bcr_airr_dataset.tsv", sep='\t')

print(f"Dataset shape: {bcr_data.shape}")
print(f"\nColumns: {list(bcr_data.columns)}")
print(f"\nFirst few rows:")
bcr_data.head()
```

--------------------------------

### Initialize Nested Cross-Validation Results

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Initializes a dictionary to store the results from the nested cross-validation process, including fold number, performance metrics, and the best hyperparameter found.

```python
# Run nested cross-validation
print("Running nested cross-validation...")
print("This may take a few minutes depending on dataset size and computational resources.")

# Initialize results storage
cv_results = {
    'fold': [],
    'f1_score': [],
    'mcc_score': [],
    'accuracy': [],
    'best_C': []
}

```

--------------------------------

### Import ML Libraries in Python

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Imports common libraries used for machine learning tasks including data manipulation (pandas, numpy), deep learning (torch), visualization (matplotlib, seaborn), model selection and evaluation (sklearn), and utility functions (collections, warnings).

```python
import pandas as pd
import numpy as np
import torch
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.model_selection import StratifiedGroupKFold, GridSearchCV
from sklearn.svm import SVC
from sklearn.metrics import matthews_corrcoef, f1_score, accuracy_score
from sklearn.preprocessing import LabelEncoder
from collections import Counter
import warnings
warnings.filterwarnings('ignore')
```

--------------------------------

### Tokenization Preprocessing Function

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Defines a function to tokenize input sequences and prepare them for model training. It handles padding and truncation to a maximum length.

```python
def preprocess_function(batch):
    encodings = tokenizer(
        batch["sequence"],
        padding="max_length",
        truncation=True,
        max_length=MAX_LENGTH,
    )
    encodings["labels"] = batch["labels"]
    return encodings
```

--------------------------------

### Visualize Sequence Length and Chain Type Distribution

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Generates histograms and pie charts to visualize the distribution of sequence lengths and chain types in BCR data. Requires matplotlib.

```python
import matplotlib.pyplot as plt

plt.figure(figsize=(12, 4))

plt.subplot(1, 2, 1)
plt.hist(bcr_data['sequence_length'], bins=50, alpha=0.7, edgecolor='black')
plt.xlabel('Sequence Length')
plt.ylabel('Frequency')
plt.title('Distribution of Sequence Lengths')

plt.subplot(1, 2, 2)
chain_counts = bcr_data['chain_type'].value_counts()
plt.pie(chain_counts.values, labels=chain_counts.index, autopct='%1.1f%%')
plt.title('Chain Type Distribution')

plt.tight_layout()
plt.show()
```

--------------------------------

### Embed Sequences with Amulety

Source: https://github.com/immcantation/amulety/blob/main/docs/cli.md

Use this command to embed sequences from an AIRR rearrangement file. Specify the input file, chain type, embedding model, and output path. The cache directory, sequence column, cell ID column, and batch size can also be configured.

```bash
amulety embed --input-airr airr_rearrangement.tsv --chain HL --model antiberta2 \
 --output-file-path out.tsv
```

--------------------------------

### Visualize Performance Comparison

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/ML_tutorial.ipynb

Generates a bar chart to visualize the performance comparison between Amulety embeddings and the random baseline across different metrics (F1 Score, MCC Score, Accuracy). Error bars represent standard deviation.

```python
# Create comparison visualization
fig, ax = plt.subplots(1, 1, figsize=(10, 6))

metrics = ['f1_score', 'mcc_score', 'accuracy']
metric_names = ['F1 Score', 'MCC Score', 'Accuracy']

x = np.arange(len(metrics))
width = 0.35

amulety_means = [results_df[metric].mean() for metric in metrics]
amulety_stds = [results_df[metric].std() for metric in metrics]
random_means = [random_df[metric].mean() for metric in metrics]
random_stds = [random_df[metric].std() for metric in metrics]

bars1 = ax.bar(x - width/2, amulety_means, width, yerr=amulety_stds, 
               label='Amulety Embeddings', alpha=0.8, capsize=5)
bars2 = ax.bar(x + width/2, random_means, width, yerr=random_stds, 
               label='Random Baseline', alpha=0.8, capsize=5)

ax.set_xlabel('Metrics')
ax.set_ylabel('Score')
# ax.set_title('Performance Comparison: Amulety Embeddings vs Random Baseline')
ax.set_xticks(x)
ax.set_xticklabels(metric_names)
ax.legend()
ax.set_ylim(0, 1)

# Add value labels on bars
def add_value_labels(bars, values, stds):
    for bar, val, std in zip(bars, values, stds):
        height = bar.get_height()
        ax.text(bar.get_x() + bar.get_width()/2., height + std + 0.01,
                f'{val:.3f}', ha='center', va='bottom', fontsize=9)

add_value_labels(bars1, amulety_means, amulety_stds)
add_value_labels(bars2, random_means, random_stds)

plt.tight_layout()
plt.show()
```

--------------------------------

### Set Random Seeds

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Sets random seeds for PyTorch, NumPy, and Python's random module to ensure reproducibility of experiments.

```python
def set_seed(seed: int = 42):
    """Set random seeds for reproducibility."""
    torch.manual_seed(seed)
    torch.cuda.manual_seed_all(seed)
    torch.backends.cudnn.deterministic = True
    torch.backends.cudnn.benchmark = False
    np.random.seed(seed)
    random.seed(seed)
    os.environ["PYTHONHASHSEED"] = str(seed)
```

--------------------------------

### Load and Sample BCR Data

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/fine_tuning_tutorial.ipynb

Loads a BCR dataset from a TSV file and samples a subset of cells for further processing. Handles potential DtypeWarnings during CSV loading.

```python
import pandas as pd
import numpy as np

# Load the dataset, handling potential mixed type warnings
airr_demo = pd.read_csv("https://zenodo.org/records/17186858/files/ML_bcr_airr_dataset.tsv", sep='\t')

# Sample up to 1000 cells without replacement
n_cells = min(1000, len(cells_with_both))
sampled_cells = np.random.choice(cells_with_both, size=n_cells, replace=False)
df_sampled = airr_demo[airr_demo["cell_id"].isin(sampled_cells)].copy()
df_sampled.head()
```

--------------------------------

### Embed BCR Paired Chains with BALM-paired

Source: https://github.com/immcantation/amulety/blob/main/docs/tutorials/amulety_cli.ipynb

Embeds heavy-light chain pairs from an AIRR TSV file using the BALM-paired model. The model is automatically downloaded on first use. Specify `--chain HL` for paired chains.

```bash
# Embed heavy-light chain pairs using BALM-paired
# The model will be automatically downloaded on first use
! amulety embed --input-airr tutorial/AIRR_subject1_FNA_d0_1_Y1_translated.tsv --chain HL --model balm-paired --batch-size 2 --output-file-path tutorial/AIRR_subject1_FNA_d0_1_Y1_balm_paired.pt
```