### Install Humatch and Dependencies

Source: https://github.com/oxpig/humatch/blob/master/README.md

Clone the Humatch repository, set up a Python virtual environment, and install the package using pip. ANARCI is a required dependency for sequence alignment.

```bash
git clone https://github.com/oxpig/Humatch.git
cd Humatch/
python3 -m venv .humatch_venv
source .humatch_venv/bin/activate
pip install .
```

```bash
pip install --upgrade pip
```

```bash
/usr/bin/python3.9 -m venv .humatch_venv
```

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

### Input CSV File Format Example

Source: https://context7.com/oxpig/humatch/llms.txt

Example of the CSV file format required for input data. Columns include optional 'is_human' for validation, and mandatory 'heavy' and 'light' chain sequences.

```csv
is_human,heavy,light
1,QVQLVQSGAEVNKPGASVKVSCKASGYTFTGYVVHWVRQAPGQRLEWMGWINTGNGDTKYSQKFQGRVSITRDTSANTAYMEVSTLRSEDTAVYYCARDRGGSGDFDYWGQGTLVTVSS,EIVLTQSPVTLSLSPGERATLSCRASQSVSFYLAWYQQKPGQAPRLLICDASNRATGIPARFSGSGSGTDFTLTISSLEPEDFAVYYCQQRSDWPYTFGQGTKLEIK
1,QVQLVQSGAEVKKPGASVKVSCKASGYTFTGYYMHWVRQAPGQGLEWMGWINPNSGGTNYAQKFQGRVTMTRDTSISTAYMELSRLRSDDTAVYYCARGEGIAAAGTLSFYYYYGMDVWGQGTTVTVSS,SYELTQPPSVSVSPGQTARITCSGDALPKQYAYWYQQKPGQAPVLVIYKDSERPSGIPERFSGSSSGTTVTLTISGVQAEDEADYYCQSADSSGTWVFGGGTKLTVL
0,EVKLVESGGGLVQPGGSLRLSCATSGFTFTDYYMSWVRQPPGKALEWLGFIRNKANGYTTEYSASVKGRFTISRDNSQSILYLQMNTLRAEDSATYYCARDDGYFAYWGQGTLVTVSA,DVVMTQTPLSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPLTFGAGTKLELK
```

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

### Sequence alignment output format

Source: https://github.com/oxpig/humatch/blob/master/README.md

Example of the tabular output generated by the alignment process.

```text
1       Q       E
2       V       I
3       Q       V
3A      -       -
4       L       L
5       V       T
...     ...     ...
126     V       I
127     S       K
128     S       -
```

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

### Germline-likeness Mutation Example

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

Demonstrates germline-likeness mutations in isolation. Allows specifying a target gene, target score, and whether to allow CDR mutations. Can also fix specific IMGT positions.

```python
example_seq = df["heavy"][0]
target_gene = "hv1"
target_score = 0.40
allow_CDR_mutations = False
fixed_imgt_positions = ["1 ", "81 ", "81A", "120 "]
germline_mutated_seq = mutate_seq_to_match_germline_likeness(example_seq, target_gene, target_score,
                                                             allow_CDR_mutations, fixed_imgt_positions)

print(f"GL-score ({target_gene}) of original sequence:\t{get_normalised_germline_likeness_score(example_seq, target_gene):.2f}")
print(f"GL-score ({target_gene}) of mutated sequence:\t{get_normalised_germline_likeness_score(germline_mutated_seq, target_gene):.2f}")
print(f"Edit distance between both sequences:\t{get_edit_distance(example_seq, germline_mutated_seq)}\n")
print(example_seq)
print(highlight_differnces_between_two_seqs(example_seq, germline_mutated_seq))
print(germline_mutated_seq)
```

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

### Get CDR Loop Indices

Source: https://context7.com/oxpig/humatch/llms.txt

Retrieves the indices of CDR loops, which are positions to be protected during humanization. No specific setup is required beyond calling the function.

```python
cdr_indices = get_CDR_loop_indices()
print(f"Number of CDR positions: {len(cdr_indices)}")
```

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

### Get Ordered Amino Acid One-Letter Codes

Source: https://context7.com/oxpig/humatch/llms.txt

Retrieves a list of standard amino acid one-letter codes in a specific order. The first 20 elements typically represent the standard amino acids.

```python
aa_codes = get_ordered_AA_one_letter_codes()
print(f"Standard AAs: {aa_codes[:20]}")  # 20 standard amino acids
```

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

### Get top-scoring V-gene and score

Source: https://context7.com/oxpig/humatch/llms.txt

Extracts the top-scoring heavy and light V-genes and their associated scores from prediction results. Prints the V-gene names and scores, including the paired score.

```python
top_heavy = get_class_and_score_of_max_predictions_only(heavy_preds, "heavy")
top_light = get_class_and_score_of_max_predictions_only(light_preds, "light")

print(f"Heavy V-gene: {top_heavy[0][0]}, Score: {top_heavy[0][1]:.3f}")
print(f"Light V-gene: {top_light[0][0]}, Score: {top_light[0][1]:.3f}")
print(f"Paired score: {paired_preds[0][1]:.3f}")  # Index 1 = "true" class
```

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

### Get Indices of Selected IMGT Positions

Source: https://context7.com/oxpig/humatch/llms.txt

Retrieves indices for specific IMGT positions within the canonical numbering system. Note that spaces are required in the input position strings.

```python
positions_to_fix = ["1 ", "81 ", "81A"]  # Note: spaces are required
indices = get_indices_of_selected_imgt_positions_in_canonical_numbering(positions_to_fix)
print(f"Fixed position indices: {indices}")
```

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

### Classify Humanness of Single Antibody Chains

Source: https://github.com/oxpig/humatch/blob/master/README.md

Use Humatch-classify to predict the humanness of antibody heavy and light chains. The -s flag provides a summary of top-scoring human V-genes. Omit -s to get predictions for all heavy and light V-genes.

```bash
Humatch-classify
    -H EVQLVESGGG...VSS
    -L DIVMTQGALP...EIK
    -s
```

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

### Load Configuration

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

Loads the default configuration settings for Humatch from a YAML file.

```python
example_heavy_seq, example_light_seq = df["heavy"][0], df["light"][0]
with open(os.path.join(root_dir, "Humatch", "configs", "default.yaml")) as f:
    config = yaml.safe_load(f)
```

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

### Initialize Humatch Environment

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Imports necessary modules and suppresses TensorFlow GPU warnings.

```python
import os
import pandas as pd
# supress warnings about having no GPU
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3'

from Humatch.align import get_padded_seq
from Humatch.model import load_cnn
from Humatch.classify import predict_from_list_of_seq_strs, get_class_and_score_of_max_predictions_only
from Humatch.plot import plot_example_boxplot
```

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

### Pre-align sequences from CSV

Source: https://github.com/oxpig/humatch/blob/master/README.md

Use a CSV file to pre-align multiple sequences for improved performance during humanisation trials.

```bash
Humatch-align
    -i data/example.csv
    --vh_col heavy
    --vl_col light
```

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

### Custom Configuration File for Humanisation

Source: https://context7.com/oxpig/humatch/llms.txt

Define custom humanisation parameters such as mutation limits, score thresholds, and CPU usage in a YAML configuration file.

```yaml
# my_config.yaml - Custom humanisation parameters

# Global settings
max_edit:   60        # Maximum total mutations allowed
noise:      0.01      # Noise factor for prediction scaling
num_cpus:   16        # CPUs for parallel processing

# Heavy chain settings
GL_target_score_H:            0.40    # Germline likeness target
GL_allow_CDR_mutations_H:     False   # Protect CDR regions
GL_fixed_imgt_positions_H:    []      # Additional fixed positions
CNN_target_score_H:           0.95    # Target humanness score
CNN_allow_CDR_mutations_H:    False   # CDR protection for CNN phase
CNN_fixed_imgt_positions_H:   []      # e.g. ["1 ", "81 ", "81A", "120 "]
# target_gene_H:              hv3     # Uncomment to force target V-gene

# Light chain settings
GL_target_score_L:            0.40
GL_allow_CDR_mutations_L:     False
GL_fixed_imgt_positions_L:    []
CNN_target_score_L:           0.95
CNN_allow_CDR_mutations_L:    False
CNN_fixed_imgt_positions_L:   []
# target_gene_L:              kv5     # Force specific light V-gene

# Paired chain settings
CNN_target_score_P:           0.95    # Target paired compatibility

```

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

### Import Humatch Library and Dependencies

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

Imports necessary libraries for Humatch functionality, including TensorFlow and Pandas. Suppresses TensorFlow and general logging warnings.

```python
import os
import time
import yaml
import pandas as pd
# suppress warnings about having no GPU
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3'

import tensorflow as tf
import logging
# suppress warnings about tf retracing
tf.get_logger().setLevel('ERROR')
logging.getLogger('tensorflow').setLevel(logging.ERROR)

from Humatch.humanise import humanise
from Humatch.model import load_cnn
from Humatch.germline_likeness import get_normalised_germline_likeness_score, mutate_seq_to_match_germline_likeness
from Humatch.utils import get_edit_distance
from Humatch.plot import highlight_differnces_between_two_seqs
```

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

### Load CNN Classifiers

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Loads pre-trained heavy, light, and paired CNN models from the specified directory.

```python
weights_dir = os.path.join(root_dir, "Humatch", "trained_models")

cnn_heavy = load_cnn(os.path.join(weights_dir, "heavy.weights.h5"), "heavy")
cnn_light = load_cnn(os.path.join(weights_dir, "light.weights.h5"), "light")
cnn_paired = load_cnn(os.path.join(weights_dir, "paired.weights.h5"), "paired")

cnn_heavy.summary()
```

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

### Humanize Sequences with Humatch

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

This snippet demonstrates how to use the `humanise` function from the Humatch library to process protein sequences. It includes timing the operation and printing the results.

```python
start_time = time.time()
humatch_output = humanise(example_heavy_seq, example_light_seq, cnn_heavy, cnn_light, cnn_paired, config, verbose=True)
print(f"Time taken to humanise: {time.time()-start_time:.1f}s")
```

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

### Full Humatch Output

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

This snippet shows the complete output structure from the `humanise` function, detailing the humanized heavy and light chains, edit distance, and CNN scores.

```python
humatch_output
```

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

### Load Humatch CNN Models

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

Loads pre-trained Convolutional Neural Network (CNN) models for heavy, light, and paired antibody chains from specified weight files.

```python
weights_dir = os.path.join(root_dir, "Humatch", "trained_models")

cnn_heavy = load_cnn(os.path.join(weights_dir, "heavy.weights.h5"), "heavy")
cnn_light = load_cnn(os.path.join(weights_dir, "light.weights.h5"), "light")
cnn_paired = load_cnn(os.path.join(weights_dir, "paired.weights.h5"), "paired")
```

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

### Humanise Antibody Sequences from CSV File

Source: https://github.com/oxpig/humatch/blob/master/README.md

Humanise multiple antibody sequences from a CSV file. Specify the input file and the column names for heavy and light chains using -i, --vh_col, and --vl_col. The output CSV will include predicted humanised sequences and associated metrics.

```bash
Humatch-humanise
    -i data/example.csv
    --vh_col heavy
    --vl_col light
```

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

### Batch Humanisation from CSV CLI

Source: https://context7.com/oxpig/humatch/llms.txt

Use the Humatch-humanise command to process a CSV file for antibody humanisation. Specify input, output, and heavy/light chain columns.

```bash
Humatch-humanise \
    -i data/example.csv \
    --vh_col heavy \
    --vl_col light \
    -o humanised_antibodies.csv
```

```bash
Humatch-humanise \
    -i data/example.csv \
    --vh_col heavy \
    --vl_col light \
    --config my_config.yaml
```

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

### Run sequence alignment

Source: https://github.com/oxpig/humatch/blob/master/README.md

Perform sequence alignment on heavy and light chain sequences to determine ANARCI numbering.

```bash
Humatch-align
    -H QVQLVQSGAE...VSS
    -L EIVLTQSPVT...EIK
```

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

### Access Humatch Utility Functions

Source: https://context7.com/oxpig/humatch/llms.txt

Utilize various utility functions from the Humatch library for sequence encoding, CDR index retrieval, edit distance calculation, and V-gene class definitions. These functions support sequence manipulation and analysis.

```python
from Humatch.utils import (
    CANONICAL_NUMBERING,
    HEAVY_V_GENE_CLASSES,
    LIGHT_V_GENE_CLASSES,
    PAIRED_CLASSES,
    seq_to_2D_kidera,
    get_CDR_loop_indices,
    get_edit_distance,
    get_ordered_AA_one_letter_codes,
    get_indices_of_selected_imgt_positions_in_canonical_numbering
)

# V-gene class definitions
print(f"Heavy V-genes: {HEAVY_V_GENE_CLASSES}")   # ['neg', 'hv1', 'hv2', ..., 'hv7']
print(f"Light V-genes: {LIGHT_V_GENE_CLASSES}")   # ['neg', 'lv1', ..., 'lv10', 'kv1', ..., 'kv7']
print(f"Paired classes: {PAIRED_CLASSES}")        # ['fake', 'true']
```

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

### Align Sequences to IMGT Canonical Numbering (Python API)

Source: https://context7.com/oxpig/humatch/llms.txt

Use the `get_padded_seq` and `strip_padding_from_seq` functions to align single or multiple antibody sequences to IMGT canonical numbering. This prepares sequences for CNN input.

```python
from Humatch.align import get_padded_seq, strip_padding_from_seq

# Align a single sequence to IMGT canonical numbering
vh_sequence = "QVQLVQSGAEVKKPGASVKVSCKASGYTFTGYYMHWVRQAPGQGLEWMGWINPNSGGTNYAQKFQGRVTMTRDTSISTAYMELSRLRSDDTAVYYCARGEGIAAAGTLSFYYYYGMDVWGQGTTVTVSS"
vl_sequence = "SYELTQPPSVSVSPGQTARITCSGDALPKQYAYWYQQKPGQAPVLVIYKDSERPSGIPERFSGSSSGTTVTLTISGVQAEDEADYYCQSADSSGTWVFGGGTKLTVL"

# Align to 200 KASearch positions (padded with "-" for missing positions)
aligned_vh = get_padded_seq(strip_padding_from_seq(vh_sequence))
aligned_vl = get_padded_seq(strip_padding_from_seq(vl_sequence))

print(f"Aligned VH length: {len(aligned_vh)}")  # 200
print(f"Aligned VL length: {len(aligned_vl)}")  # 200
print(f"Sample positions: {aligned_vh[:10]}")   # First 10 positions
```

```python
# Batch alignment
from Humatch.utils import CANONICAL_NUMBERING
import pandas as pd

df = pd.read_csv("data/example.csv")
aligned_heavy = [get_padded_seq(strip_padding_from_seq(seq)) for seq in df["heavy"]]
aligned_light = [get_padded_seq(strip_padding_from_seq(seq)) for seq in df["light"]]

# Access canonical numbering positions
print(f"Total IMGT positions: {len(CANONICAL_NUMBERING)}")  # 200
print(f"Sample positions: {CANONICAL_NUMBERING[:5]}")  # ['1 ', '2 ', '3 ', '3A', '4 ']

```

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

### Examine Mutation Locations

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

This code snippet visualizes the differences between the original and humanized sequences by printing them with highlighted mutations. It uses a helper function `highlight_differnces_between_two_seqs`.

```python
humanised_heavy_seq, humanised_light_seq = humatch_output["Humatch_H"], humatch_output["Humatch_L"]
print(f"\nHeavy\n{example_heavy_seq}\n{highlight_differnces_between_two_seqs(example_heavy_seq, humanised_heavy_seq)}\n{humanised_heavy_seq}")
print(f"\nLight\n{example_light_seq}\n{highlight_differnces_between_two_seqs(example_light_seq, humanised_light_seq)}\n{humanised_light_seq}")
```

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

### Humanise Antibody Sequences

Source: https://github.com/oxpig/humatch/blob/master/README.md

Use Humatch-humanise to perform experimental-like humanisation of antibody heavy and light chains. The -v flag shows default config parameters. A custom config file can be specified using --config.

```bash
Humatch-humanise
    -H QVNLLQSGAA...VSA
    -L DTVLTQSPAL...EIK
    -v
```

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

### Align Antibody Sequences with Humatch-align

Source: https://context7.com/oxpig/humatch/llms.txt

Aligns VH/VL sequences to IMGT numbering. Supports single pair processing, batch processing from CSV, and outputting individual IMGT columns.

```bash
Humatch-align \
    -H QVQLVQSGAEVKKPGASVKVSCKASGYTFTGYYMHWVRQAPGQGLEWMGWINPNSGGTNYAQKFQGRVTMTRDTSISTAYMELSRLRSDDTAVYYCARGEGIAAAGTLSFYYYYGMDVWGQGTTVTVSS \
    -L SYELTQPPSVSVSPGQTARITCSGDALPKQYAYWYQQKPGQAPVLVIYKDSERPSGIPERFSGSSSGTTVTLTISGVQAEDEADYYCQSADSSGTWVFGGGTKLTVL
```

```bash
Humatch-align \
    -i data/example.csv \
    --vh_col heavy \
    --vl_col light \
    -o aligned_sequences.csv
```

```bash
Humatch-align \
    -i data/example.csv \
    --vh_col heavy \
    --vl_col light \
    --imgt_cols \
    -o aligned_imgt.csv
```

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

### Humatch citation

Source: https://github.com/oxpig/humatch/blob/master/README.md

BibTeX entry for citing the Humatch publication.

```bibtex
@article{Chinery2024,
  title = {Humatch - fast, gene-specific joint humanisation of antibody heavy and light chains},
  author = {Lewis Chinery, Jeliazko R Jeliazkov, and Charlotte M Deane},
  journal = {bioRxiv},
  year = {2024},
  doi = {10.1101/2024.09.16.613210}
}
```

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

### Load CNN Models and Predict Humanness (Python API)

Source: https://context7.com/oxpig/humatch/llms.txt

Load pre-trained CNN models for heavy, light, and paired chains using the `load_cnn` function. Predict humanness scores for aligned sequences.

```python
from Humatch.model import load_cnn, HEAVY_WEIGHTS, LIGHT_WEIGHTS, PAIRED_WEIGHTS
from Humatch.classify import (
    predict_from_list_of_seq_strs,
    get_class_and_score_of_max_predictions_only
)
from Humatch.align import get_padded_seq, strip_padding_from_seq

# Load CNN models (downloads weights automatically on first run)
cnn_heavy = load_cnn(HEAVY_WEIGHTS, "heavy")   # Heavy chain classifier
cnn_light = load_cnn(LIGHT_WEIGHTS, "light")   # Light chain classifier
cnn_paired = load_cnn(PAIRED_WEIGHTS, "paired")  # Paired VH/VL classifier

# Prepare aligned sequences
vh_seq = "QVQLVQSGAEVKKPGASVKVSCKASGYTFTGYYMHWVRQAPGQGLEWMGWINPNSGGTNYAQKFQGRVTMTRDTSISTAYMELSRLRSDDTAVYYCARGEGIAAAGTLSFYYYYGMDVWGQGTTVTVSS"
vl_seq = "SYELTQPPSVSVSPGQTARITCSGDALPKQYAYWYQQKPGQAPVLVIYKDSERPSGIPERFSGSSSGTTVTLTISGVQAEDEADYYCQSADSSGTWVFGGGTKLTVL"

aligned_vh = get_padded_seq(strip_padding_from_seq(vh_seq))
aligned_vl = get_padded_seq(strip_padding_from_seq(vl_seq))

# Get full predictions (all V-gene probabilities)
heavy_preds = predict_from_list_of_seq_strs([aligned_vh], cnn_heavy)
light_preds = predict_from_list_of_seq_strs([aligned_vl], cnn_light)

# Paired prediction requires concatenated VH + padding + VL
PAD = "----------"
paired_seq = aligned_vh + PAD + aligned_vl
paired_preds = predict_from_list_of_seq_strs([paired_seq], cnn_paired)

```

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

### Humanise Antibody Sequences with Python API

Source: https://context7.com/oxpig/humatch/llms.txt

Programmatically humanise antibody sequences using the `humanise` function. This function jointly optimizes heavy and light chains and requires pre-loaded CNN models and a configuration dictionary.

```python
import yaml
from Humatch.humanise import humanise
from Humatch.model import load_cnn, HEAVY_WEIGHTS, LIGHT_WEIGHTS, PAIRED_WEIGHTS
from Humatch.align import get_padded_seq, strip_padding_from_seq

# Load CNN models
cnn_heavy = load_cnn(HEAVY_WEIGHTS, "heavy")
cnn_light = load_cnn(LIGHT_WEIGHTS, "light")
cnn_paired = load_cnn(PAIRED_WEIGHTS, "paired")

# Load or define configuration
config = {
    "max_edit": 60,
    "num_cpus": 8,
    "GL_target_score_H": 0.40,
    "GL_allow_CDR_mutations_H": False,
    "GL_fixed_imgt_positions_H": [],
    "CNN_target_score_H": 0.95,
    "CNN_allow_CDR_mutations_H": False,
    "CNN_fixed_imgt_positions_H": [],
    "GL_target_score_L": 0.40,
    "GL_allow_CDR_mutations_L": False,
    "GL_fixed_imgt_positions_L": [],
    "CNN_target_score_L": 0.95,
    "CNN_allow_CDR_mutations_L": False,
    "CNN_fixed_imgt_positions_L": [],
    "CNN_target_score_P": 0.95,
}

# Prepare sequences (non-human antibody)
vh_seq = "QVNLLQSGAALVKPGASVKLSCKASGYTFTDYYIHWVKQSHGKSLEWIGYINPNSGYTNYNEKFKSKATLTVDKSTNTAYMELSRLTSEDSATYYCTRENSLYYYSSYPFAYWGQGTLVTVSS"
vl_seq = "DTVLTQSPALAVSPGERVTISCRASESVSTGMHWYQQKPGQQPKLLIYGASNLESGVPARFSGSGSGTDFTLTIDPVEADDTATYFCQQSWNDPLTFGSGTKLEIK"

aligned_vh = get_padded_seq(strip_padding_from_seq(vh_seq))
aligned_vl = get_padded_seq(strip_padding_from_seq(vl_seq))

# Run humanisation
result = humanise(
    heavy_seq=aligned_vh,
    light_seq=aligned_vl,
    cnn_heavy=cnn_heavy,
    cnn_light=cnn_light,
    cnn_paired=cnn_paired,
    config=config,
    verbose=True
)

# Access results
print(f"Humanised VH: {result['Humatch_H'].replace('-', '')}")
print(f"Humanised VL: {result['Humatch_L'].replace('-', '')}")
print(f"Edit distance: {result['Edit']}")
print(f"Target genes: {result['HV']}, {result['LV']}")
print(f"Final scores - H: {result['CNN_H']:.3f}, L: {result['CNN_L']:.3f}, P: {result['CNN_P']:.3f}")
```

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

### Load Pre-aligned Non-Human Sequences

Source: https://github.com/oxpig/humatch/blob/master/notebooks/humanise.ipynb

Loads pre-aligned non-human antibody sequences from a CSV file into a Pandas DataFrame. Filters the DataFrame to include only non-human sequences.

```python
root_dir = os.path.dirname(os.path.abspath(""))
data = os.path.join(root_dir, "data", "example_prealigned.csv")
df = pd.read_csv(data)
df = df[df["is_human"]==0].reset_index(drop=True)
print(df.shape)
df.head(2)
```

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

### Align Sequences

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Applies sequence padding to heavy and light chain columns in the DataFrame.

```python
df["heavy"] = df.apply(lambda x: get_padded_seq(x["heavy"]), axis=1)
df["light"] = df.apply(lambda x: get_padded_seq(x["light"]), axis=1)
df.head(2)
```

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

### Classify Humanness from CSV File

Source: https://github.com/oxpig/humatch/blob/master/README.md

Perform high-throughput humanness classification on a CSV file. Specify the input file and the column names for heavy and light chains using -i, --vh_col, and --vl_col. Output paths can be specified with -o.

```bash
Humatch-classify
    -i data/example.csv
    --vh_col heavy
    --vl_col light
```

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

### Analyze Germline Likeness with Python API

Source: https://context7.com/oxpig/humatch/llms.txt

Analyze and mutate antibody sequences to match human germline likeness patterns using functions like `load_observed_position_AA_freqs` and `mutate_seq_to_match_germline_likeness`. This provides fine-grained control over the initial humanisation phase.

```python
from Humatch.germline_likeness import (
    load_observed_position_AA_freqs,
    get_normalised_germline_likeness_score,
    mutate_seq_to_match_germline_likeness,
    get_most_common_germline_seq
)
from Humatch.align import get_padded_seq, strip_padding_from_seq

# Align sequence
vh_seq = "QVNLLQSGAALVKPGASVKLSCKASGYTFTDYYIHWVKQSHGKSLEWIGYINPNSGYTNYNEKFKSKATLTVDKSTNTAYMELSRLTSEDSATYYCTRENSLYYYSSYPFAYWGQGTLVTVSS"
aligned_vh = get_padded_seq(strip_padding_from_seq(vh_seq))

# Load germline frequency array for target V-gene
target_gene = "hv1"
gl_freqs = load_observed_position_AA_freqs(target_gene)
print(f"Germline array shape: {gl_freqs.shape}")  # (200, 20)

# Calculate germline likeness score
gl_score = get_normalised_germline_likeness_score(aligned_vh, target_gene)
print(f"Original germline likeness: {gl_score:.3f}")

# Get most common germline sequence for reference
germline_consensus = get_most_common_germline_seq(gl_freqs)
print(f"Germline consensus (first 20 chars): {germline_consensus[:20]}")

# Mutate to match germline likeness (preserving CDRs)
mutated_vh = mutate_seq_to_match_germline_likeness(
    seq=aligned_vh,
    target_gene=target_gene,
    target_score=0.40,           # Target germline likeness
    allow_CDR_mutations=False,   # Protect CDR regions
    fixed_imgt_positions=[]      # Additional fixed positions
)

new_gl_score = get_normalised_germline_likeness_score(mutated_vh, target_gene)
print(f"After germline matching: {new_gl_score:.3f}")
```

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

### Convert Sequence to Kidera Encoding

Source: https://context7.com/oxpig/humatch/llms.txt

Converts a short amino acid sequence into Kidera encoding suitable for CNN input. The output is a 2D array representing the encoded sequence.

```python
short_seq = "QVQLVQSG"
kidera_encoded = seq_to_2D_kidera(short_seq)
print(f"Kidera encoding shape: {len(kidera_encoded)} x {len(kidera_encoded[0])}")  # 8 x 10
```

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

### Humanise Antibody Sequences with Humatch-humanise

Source: https://context7.com/oxpig/humatch/llms.txt

Performs joint humanisation of VH/VL pairs by mutating framework residues. Provides standard output or verbose progress tracking.

```bash
Humatch-humanise \
    -H QVNLLQSGAALVKPGASVKLSCKASGYTFTDYYIHWVKQSHGKSLEWIGYINPNSGYTNYNEKFKSKATLTVDKSTNTAYMELSRLTSEDSATYYCTRENSLYYYSSYPFAYWGQGTLVTVSS \
    -L DTVLTQSPALAVSPGERVTISCRASESVSTGMHWYQQKPGQQPKLLIYGASNLESGVPARFSGSGSGTDFTLTIDPVEADDTATYFCQQSWNDPLTFGSGTKLEIK
```

```bash
Humatch-humanise \
    -H QVNLLQSGAALVKPGASVKLSCKASGYTFTDYYIHWVKQSHGKSLEWIGYINPNSGYTNYNEKFKSKATLTVDKSTNTAYMELSRLTSEDSATYYCTRENSLYYYSSYPFAYWGQGTLVTVSS \
    -L DTVLTQSPALAVSPGERVTISCRASESVSTGMHWYQQKPGQQPKLLIYGASNLESGVPARFSGSGSGTDFTLTIDPVEADDTATYFCQQSWNDPLTFGSGTKLEIK \
    -v
```

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

### Read Sequence Data

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Loads antibody sequence data from a CSV file into a pandas DataFrame.

```python
root_dir = os.path.dirname(os.path.abspath(""))
data = os.path.join(root_dir, "data", "example.csv")
df = pd.read_csv(data)
print(df.shape)
df.head(1)
```

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

### Predict Sequence Classifications

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Generates predictions for heavy, light, and paired sequences using the loaded CNN models.

```python
pad_len, pad_char = 10, "-"
joined_seqs = [H + pad_char * pad_len + L for H, L in zip(df["heavy"], df["light"])]
predictions_heavy = predict_from_list_of_seq_strs(df["heavy"].tolist(), cnn_heavy)
predictions_light = predict_from_list_of_seq_strs(df["light"].tolist(), cnn_light)
predictions_paired = predict_from_list_of_seq_strs(joined_seqs, cnn_paired)
```

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

### Classify Antibody Humanness with Humatch-classify

Source: https://context7.com/oxpig/humatch/llms.txt

Predicts humanness scores for antibody sequences using CNN models. Can output summary scores or full V-gene predictions and supports batch processing.

```bash
Humatch-classify \
    -H EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRHGDYWGQGTLVTVSS \
    -L DIQMTQSPSSLSASVGDRVTITCRASQGIRNDLGWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCLQHNSYPLTFGGGTKVEIK \
    -s
```

```bash
Humatch-classify \
    -H EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRHGDYWGQGTLVTVSS \
    -L DIQMTQSPSSLSASVGDRVTITCRASQGIRNDLGWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCLQHNSYPLTFGGGTKVEIK
```

```bash
Humatch-classify \
    -i data/example.csv \
    --vh_col heavy \
    --vl_col light \
    -o classified_antibodies.csv
```

```bash
Humatch-classify \
    -i data/example_prealigned.csv \
    --vh_col VH \
    --vl_col VL \
    --aligned \
    -s
```

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

### Plot Prediction Score Distribution

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Generates a boxplot to compare the distribution of CNN scores between human and non-human sequences.

```python
plot_example_boxplot(df)
```

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

### Extract Top V-Gene Class and Score

Source: https://github.com/oxpig/humatch/blob/master/notebooks/classify.ipynb

Assigns the highest scoring V-gene class and its corresponding score to the dataframe for heavy, light, and paired chains.

```python
df[["top_heavy_class", "top_heavy_score"]] = get_class_and_score_of_max_predictions_only(predictions_heavy, "heavy")
df[["top_light_class", "top_light_score"]] = get_class_and_score_of_max_predictions_only(predictions_light, "light")
df[["top_paired_class", "top_paired_score"]] = get_class_and_score_of_max_predictions_only(predictions_paired, "paired")
df.head(2)
```

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

### Calculate Edit Distance Between Sequences

Source: https://context7.com/oxpig/humatch/llms.txt

Calculates the edit distance (number of mutations) between two amino acid sequences. This is useful for quantifying sequence similarity.

```python
seq1 = "QVQLVQSGAEVK"
seq2 = "EVQLVESGAELK"
edits = get_edit_distance(seq1, seq2)
print(f"Edit distance: {edits}")  # 3 mutations
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.