medlp — Medicine-Likeness Profiler

A Python pipeline for scoring antibody developability using structural, sequence, aggregation and immunogenicity descriptors. Produces medicine-likeness scores normalized against a marketed-antibody reference panel.

Overview

medlp evaluates antibody candidates on their structural and sequence descriptors:

Category	Descriptor	Tool
Structural	Structure prediction	ImmuneBuilder (default) or MOE (optional)
	Structure descriptors (BSA, pI, hydrophobicity, patch ratio, HI)	FreeSASA + BioPython (default) or MOE (optional)
Sequence	Humanness	IgBLAST
	CDR annotation	ANARCI (default, Chothia/IMGT/Kabat/Martin schemes) or MOE (optional)
	Aggregation propensity	TANGO (optional, licensed)
	Immunogenicity	NetMHCII / IEDB (optional, licensed)

The final output is a CSV of normalized scores with structure, sequence, and total scores plus percentiles relative to a marketed-antibody reference.

Requirements

• Python 3.12
• pixi (recommended) or uv for package management
• IgBLAST ≥ 1.22 (auto-installed via pixi/bioconda)
• HMMER ≥ 3.3 (required by ANARCI; auto-installed via pixi/bioconda)

Optional / Licensed Tools

Tool	License	How to provide
MOE	Commercial	Set MOE_PATH env-var or --moe-path CLI flag
TANGO	Commercial	Set TANGO_PATH env-var or --tango-path CLI flag
NetMHCII (IEDB MHC_II)	Free for academic use (download)	Set NETMHCII_PATH env-var or --netmhcii-path CLI flag

Note: MOE, TANGO and NetMHCii require purchased licenses and are not bundled with this package. If not provided, the pipeline uses open-source alternatives (ImmuneBuilder for structure, FreeSASA/BioPython for descriptors, ANARCI for CDR). TANGO and NetMHCII steps are skipped if unavailable.

---

Installation

Option A: pixi (recommended — installs everything including IgBLAST)

The default environment (pixi install) includes IgBLAST, HMMER, ImmuneBuilder, and all dev/test tools on CPU. A separate medlp-cuda environment adds CUDA support for faster ImmuneBuilder inference using GPU.

Environment	Use when	Install
default	CPU machine or laptop (Linux, macOS)	pixi install
medlp-cuda	NVIDIA GPU server (faster ImmuneBuilder, Linux only)	pixi install -e medlp-cuda

# Clone the repository
git clone <repo-url> med-lp
cd med-lp

# CPU (default)
pixi install
pixi run medlp check

# GPU (Linux + NVIDIA GPU)
pixi install -e medlp-cuda
pixi run -e medlp-cuda medlp check

Use pixi run <task> (default env) or pixi run -e medlp-cuda <task> for all commands.

Option B: uv (Python-only — you must install IgBLAST separately)

cd med-lp

# Create venv and install (includes ImmuneBuilder)
uv pip install -e ".[structure]"

# Ensure igblastp and hmmscan are on PATH
# (Install via conda/bioconda or system package manager)

Option C: pip

cd med-lp
pip install -e ".[structure]"

# Ensure igblastp and hmmscan are on PATH

---

Quick Start

1. Prepare Input

FASTA mode — Create a directory containing one or more FASTA files, where each file includes one or more records with paired VH and VL antibody sequences:

input_fastas/
├── antibody1.fasta
├── antibody2.fasta
└── antibody3.fasta

Each FASTA file should contain paired sequences with _VH and _VL suffixes:

>antibodyA_VL
DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQK...
>antibodyA_VH
EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQA...
>antibodyB_VL
DIQMTQSPSSLSASVGDRVTITCFASQSISSYLNWYQQK...
>antibodyB_VH
EVQLVESGGGLVQPGGSLRLSCAFSGFNIKDTYIHWVRQA...

PDB mode — Create a directory with PDB files (one per antibody). Chains do not need to be labelled L/H — the pipeline extracts all chains and uses IgBLAST to automatically identify VH and VL:

input_pdbs/
├── 1FL5.pdb
├── trastuzumab.pdb
└── adalimumab.pdb

2. Run the Pipeline

# Minimal run from FASTA (open-source tools only)
medlp run -i input_fastas/ -o results/

# With marketed-antibody reference for normalization
medlp run -i input_fastas/ -o results/ -m marketed_scores.csv

# With all optional tools
medlp run -i input_fastas/ -o results/ \
  -m marketed_scores.csv \
  --moe-path /path/to/moebatch \
  --tango-path /path/to/agadirwrapper \
  --netmhcii-path /path/to/mhc_II_binding.py \
  --hla-alleles /path/to/hla_ref_set.class_ii.txt

# Run from pre-computed PDB structures
medlp run-from-pdb -i input_pdbs/ -o results/

# Self-normalize (generate reference from input)
medlp run -i input_fastas/ -o results/ --generate-reference

Persistent preferences: Tool paths supplied via --tango-path, --moe-path, etc. are automatically saved to ~/.config/medlp/prefs.json and reused on subsequent runs. Use medlp config to view or medlp config --clear to reset.

3. Output Structure

results/
├── validated/                    # Validated FASTA files
├── samples/
│   └── <sampleID>/
│       ├── igblast/              # IgBLAST humanness results
│       ├── structure/            # PDB structures
│       ├── descriptors/          # Structural descriptor CSVs
│       ├── cdr/                  # CDR annotation CSVs
│       ├── tango/                # TANGO aggregation results
│       ├── netmhcii/             # NetMHCII immunogenicity
│       └── scored/               # Per-sample scored CSV
├── results/
│   ├── newScoredAntibodies.csv          # All samples concatenated
│   └── normalizedNewAntibodies.csv      # Normalized with percentiles
└── logs/
    └── medlp.log                        # Run log

---

CLI Reference

medlp run

Run the full end-to-end pipeline from FASTA input.

Flag	Default	Description
-i, --input-dir	(required)	Directory of input FASTA files
-o, --output-dir	medlp_output	Output directory
-m, --marketed-scores	—	Marketed antibody CSV for normalization
--moe-path	—	Path to MOE moebatch binary
--use-moe-structure	false	Use MOE for structure (not ImmuneBuilder)
--skip-moe	false	Disable MOE even if found
--skip-moe-descriptors	false	Skip all MOE SVL scripts; use open-source tools for descriptors and CDR
--igblast-db	(auto-download)	IgBLAST germline DB prefix
--num-alignments	5	IgBLAST V-gene alignments
--evalue	1.0	IgBLAST E-value
--species	human	IgBLAST species for germline DB
--numbering-scheme	chothia	ANARCI numbering scheme for CDR extraction (chothia, imgt, kabat, martin)
--tango-path	—	Path to TANGO agadirwrapper binary
--tango-options	(auto-detected)	Path to TANGO Options.txt file
--skip-tango	false	Skip TANGO aggregation analysis
--netmhcii-path	—	Path to mhc_II_binding.py
--netmhcii-method	netmhciipan_el	NetMHCII prediction method
--netmhcii-lengths	15	Peptide length for NetMHCII
--rank-filter	1.0	NetMHCII percentile rank cutoff
--hla-alleles	(bundled)	HLA alleles file for NetMHCII
--skip-netmhcii	false	Skip NetMHCII immunogenicity analysis
--generate-reference	false	Self-normalize input
--max-workers	0 (auto = half CPU count)	Max parallel processes
--moe-workers	8	Max concurrent MOE licence slots
--gpu-workers	2	Max concurrent ImmuneBuilder GPU workers
--use-gpu / --no-gpu	auto-detect	Force GPU on/off for ImmuneBuilder
--force-rerun	false	Ignore existing outputs and rerun all steps
-v, --verbose	false	Debug logging

medlp run-from-pdb

Run the pipeline from pre-computed PDB structures. Sequences are extracted directly from the PDB file; all chains are run through IgBLAST to automatically identify VH and VL — no manual chain labelling or FASTA input is required. Structure prediction is skipped entirely.

Flag	Default	Description
-i, --input-dir	(required)	Directory of input PDB files
-o, --output-dir	medlp_output	Output directory
-m, --marketed-scores	—	Marketed antibody CSV for normalization
--moe-path	—	Path to MOE moebatch binary
--skip-moe	false	Disable MOE even if found
--skip-moe-descriptors	false	Skip all MOE SVL scripts; use open-source tools for descriptors and CDR
--igblast-db	(auto-download)	IgBLAST germline DB prefix
--num-alignments	5	IgBLAST V-gene alignments
--evalue	1.0	IgBLAST E-value
--species	human	IgBLAST species for germline DB
--numbering-scheme	chothia	ANARCI numbering scheme for CDR extraction (chothia, imgt, kabat, martin)
--tango-path	—	Path to TANGO agadirwrapper binary
--tango-options	(auto-detected)	Path to TANGO Options.txt file
--skip-tango	false	Skip TANGO aggregation analysis
--netmhcii-path	—	Path to mhc_II_binding.py
--netmhcii-method	netmhciipan_el	NetMHCII prediction method
--netmhcii-lengths	15	Peptide length for NetMHCII
--rank-filter	1.0	NetMHCII percentile rank cutoff
--hla-alleles	(bundled)	HLA alleles file for NetMHCII
--skip-netmhcii	false	Skip NetMHCII immunogenicity analysis
--generate-reference	false	Self-normalize input
--max-workers	0 (auto = half CPU count)	Max parallel processes
--moe-workers	8	Max concurrent MOE licence slots
--gpu-workers	2	Max concurrent ImmuneBuilder GPU workers
--use-gpu / --no-gpu	auto-detect	Force GPU on/off for ImmuneBuilder
--force-rerun	false	Ignore existing outputs and rerun all steps
-v, --verbose	false	Debug logging

Note: --use-moe-structure is not available in PDB mode since structures are already provided.

medlp validate

Validate FASTA files without running analysis.

medlp validate -i input_fastas/ -o validated/

medlp normalize

Normalize pre-scored antibodies against a reference.

medlp normalize -s scored.csv -m marketed.csv -o output/

medlp setup-db

Download the IgBLAST IMGT germline database.

medlp setup-db --species human

medlp check

Verify all tools are available. Shows a table with status for required and optional dependencies (both CLI tools and Python packages).

medlp check

medlp visualize

Generate distribution plots for top-scoring antibodies.

medlp visualize -s normalized.csv -m marketed.csv -o plots/ --top-n 5

medlp config

Show or clear saved tool-path preferences.

# Show saved preferences
medlp config

# Clear all saved preferences
medlp config --clear

Tool paths supplied via --tango-path, --moe-path, --netmhcii-path, and --tango-options are automatically saved to ~/.config/medlp/prefs.json and reused on subsequent runs. The resolution order is: CLI flag → environment variable → saved preference → PATH lookup.

---

Environment Variables

Variable	Description
MOE_PATH	Path to MOE moebatch binary
TANGO_PATH	Path to TANGO agadirwrapper binary
TANGO_OPTIONS	Path to TANGO Options.txt file
NETMHCII_PATH	Path to IEDB mhc_II_binding.py
IGBLAST_DB	Path prefix for IgBLAST germline database
XDG_DATA_HOME	Base directory for cached data (default: ~/.local/share)
XDG_CONFIG_HOME	Base directory for saved preferences (default: ~/.config)

---

Scored Antibody Columns

Raw Descriptors

Column	Description
BSA_LC_HC	Buried surface area (LC–HC interface)
pro_pI_3D	Isoelectric point (3D)
dip_hyd_ratio	RM = pro_dipole_moment / pro_hyd_moment
patch_ratio	RP = (pro_patch_pos + pro_patch_neg) / pro_patch_hyd
HI	Hydrophobicity index
light_seq / heavy_seq	VL / VH sequences
humanness_light / humanness_heavy	Per-chain humanness scores
average_humanness	Mean humanness
germline_light / germline_heavy	Closest germline V-gene
chem_liabilities	Chemical liability penalty score
total_agg	Normalized aggregation propensity
total_immuno	Fraction of residues in immune epitopes

Normalized Scores (added by normalization)

Column	Description
*_norm	Z-score normalized descriptor
structure_score	Sum of structural descriptor Z-scores
seq_score	Sum of sequence descriptor Z-scores
total_score	structure_score + seq_score
percentile	Percentile rank vs marketed antibodies (if marketed scores provided)

---

Development

# Install (use medlp-cuda instead on a GPU server)
pixi install

# Run all tests (unit + integration)
pixi run test

# Run integration tests only
pixi run test-integration

# Lint / format
pixi run lint
pixi run format

---

Author

Farbod Mahmoudinobar — fmahmoudinobar@modernatx.com