ImmuneFold¶

PLM-enhanced antibody and TCR structure prediction model that combines ESM-2 3B representations with immune-protein-specific structural supervision for high-accuracy folding.

License: Apache-2.0 · Molecules: antibody, tcr · Tasks: structure_prediction

Actions: fold · Variants: 2

At a glance¶

Use it when

You need the highest-accuracy single-sequence antibody Fv structure prediction available, particularly for CDR-H3 loop conformations critical for binding analysis
You need to predict antibody-antigen complex structures when you have the antigen PDB structure available, to model the binding interface without experimental co-crystallization
You need TCR-pMHC complex modeling for immunotherapy applications, with full four-chain structural prediction including peptide and MHC context
You want per-residue confidence scores (pLDDT) and global structural confidence (pTM) to assess prediction reliability before using structures for downstream design
You are generating input structures for AntiFold inverse folding and want the most accurate predicted structures available
You need nanobody structure prediction and prefer PLM-enhanced accuracy over the dedicated but non-PLM NanoBodyBuilder2 in ImmuneBuilder

Strengths

Highest CDR-H3 accuracy among single-sequence antibody structure prediction methods, leveraging ESM-2 3B protein language model representations trained on 250M protein sequences
Supports antibody-antigen complex prediction when provided with antigen PDB structure, enabling structural analysis of paratope-epitope interactions without experimental co-crystal structures
Comprehensive confidence scoring with both global pTM (0-1 structural confidence) and per-residue pLDDT scores, allowing users to identify well-predicted vs uncertain regions
Covers both antibodies and TCRs with dedicated checkpoints, including full TCR-pMHC complex modeling with peptide and MHC context for immunotherapy applications
Supports nanobody (VHH) structure prediction via H-chain-only input mode, extending coverage beyond the paired antibody use case
PLM-enhanced architecture captures deep evolutionary patterns from ESM-2 pre-training that improve loop prediction beyond what purely structural methods achieve
Apache-2.0 license with no commercial restrictions, suitable for therapeutic antibody and TCR development pipelines

Limitations

Requires T4 GPU (16 GB RAM) for inference, making it more expensive than CPU-only alternatives like ImmuneBuilder and AbodyBuilder3's pLDDT variant
Very recent publication (December 2024) with limited independent benchmarking and no applied literature yet, making long-term accuracy assessment uncertain
Single action (fold) with no embedding, scoring, or sequence generation capabilities -- purely a structure prediction tool
Minimum sequence length requirements (VH >= 90 AA, VL >= 85 AA) may reject truncated or partial antibody sequences that other tools can still process
TCR variant requires all four chains (beta, alpha, peptide, MHC) as input, which limits usability when partial TCR information is available
Does not have a dedicated nanobody sub-model with VHH-specific training like ImmuneBuilder's NanoBodyBuilder2; nanobody prediction uses the general antibody checkpoint
Reliance on ESM-2 3B as a feature extractor means any limitations of ESM-2 (single-chain, no PTMs, truncation at ~1022 residues) propagate into structural predictions

Reach for something else when

You need CPU-only inference for high-throughput screening of large antibody libraries -- use ImmuneBuilder (all CPU) or AbodyBuilder3 pLDDT variant
You need to predict structures for hundreds or thousands of sequences and cost is a primary concern -- GPU inference cost accumulates; use ImmuneBuilder for bulk screening
You need sequence-level analysis (embeddings, scoring, generation) rather than structure prediction -- use AbLang2, IgBERT, or IgT5
You have partial TCR sequences without all four chains (beta, alpha, peptide, MHC) -- use ImmuneBuilder's TCRBuilder2 which handles paired alpha/beta chains only
You need general protein structure prediction for non-immune targets -- use ESMFold or Chai-1
You need a well-established model with extensive independent benchmarking and community validation -- use ImmuneBuilder or AbodyBuilder3, which have more published validation
You need structure prediction for antibody sequences shorter than the minimum length requirements (VH < 90 AA or VL < 85 AA)

Alternatives

Model	Better when	Worse when
immunebuilder	Runs entirely on CPU with dedicated antibody/nanobody/TCR sub-models (incl. NanoBodyBuilder2); cheaper for high-throughput library screening.	Lower CDR-H3 accuracy (no PLM enhancement); no antibody-antigen complex mode and no pLDDT confidence scores.
abodybuilder3	CPU-only pLDDT variant for fast screening plus a ProtT5 language variant; longer-established ABodyBuilder lineage with more published benchmarks.	Antibody-only (no TCR or nanobody), no antibody-antigen complex mode; ImmuneFold's ESM-2 3B features tend to give better CDR accuracy.
esmfold	General single-sequence protein folder that also accepts these protein-AA chains; useful when you fold non-immune chains too or want a fast ESM-2-based fold.	Not immune-specialized — no IMGT-aware CDR-H3 accuracy, no TCR-pMHC or antibody-antigen complex mode, no antibody-tuned confidence.
chai1	General biomolecular complex folder that accepts the same protein-AA chains and can model antibody-antigen and multi-chain complexes (plus DNA/RNA/ligand context).	Not immune-specialized; lacks ImmuneFold's antibody/TCR-tuned accuracy and dedicated TCR-pMHC checkpoints, and is heavier to run.

API & schema¶

Variants

Variant	Endpoint slug	GPU	CPU	Memory
antibody	`immunefold-antibody`	t4	3.0	16 GB
tcr	`immunefold-tcr`	t4	3.0	16 GB

Call an action with POST /api/v1/{slug}/{action} — the request envelope is {"items": [...], "params": {...}} and a success returns {"results": [...]}. See the HTTP API page for the base URL, error shape, and full contract.

`fold`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/immunefold-antibody/fold \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {}
  ]
}'

Request — ImmuneFoldPredictRequest

Field	Type	Required	Constraints	Description
`params`	ImmuneFoldPredictRequestParams \| null	no		Optional parameters controlling this action (defaults are used when omitted).
`items`	list[ImmuneFoldPredictRequestItem]	yes	items 1–32	Batch of inputs to process in a single request. Up to 32 per request.

Nested types

ImmuneFoldPredictRequestItem

Field	Type	Required	Description
`heavy_chain`	string \| null	no	Antibody heavy-chain amino-acid sequence.
`light_chain`	string \| null	no	Antibody light-chain amino-acid sequence.
`tcr_beta`	string \| null	no	TCR beta-chain amino-acid sequence; required for TCR mode alongside tcr_alpha, peptide, and mhc.
`tcr_alpha`	string \| null	no	TCR alpha-chain amino-acid sequence; required for TCR mode alongside tcr_beta, peptide, and mhc.
`peptide`	string \| null	no	Antigenic peptide sequence presented by the MHC; required for TCR mode alongside tcr_alpha, tcr_beta, and mhc.
`mhc`	string \| null	no	MHC sequence presenting the peptide antigen; required for TCR mode alongside tcr_alpha, tcr_beta, and peptide.
`pdb`	string \| null	no	Antigen structure in PDB format for antibody-antigen complex mode.

ImmuneFoldPredictRequestParams

Field	Type	Required	Constraints	Description
`contact_idx`	integer \| null	no		Contact index for antibody-antigen complex prediction; used only when an antigen pdb is provided.

Raw JSON Schema

{
  "$defs": {
    "ImmuneFoldPredictRequestItem": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody heavy-chain amino-acid sequence.",
          "title": "Heavy Chain"
        },
        "light_chain": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody light-chain amino-acid sequence.",
          "title": "Light Chain"
        },
        "tcr_beta": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "TCR beta-chain amino-acid sequence; required for TCR mode alongside tcr_alpha, peptide, and mhc.",
          "title": "Tcr Beta"
        },
        "tcr_alpha": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "TCR alpha-chain amino-acid sequence; required for TCR mode alongside tcr_beta, peptide, and mhc.",
          "title": "Tcr Alpha"
        },
        "peptide": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antigenic peptide sequence presented by the MHC; required for TCR mode alongside tcr_alpha, tcr_beta, and mhc.",
          "title": "Peptide"
        },
        "mhc": {
          "anyOf": [
            {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "MHC sequence presenting the peptide antigen; required for TCR mode alongside tcr_alpha, tcr_beta, and peptide.",
          "title": "Mhc"
        },
        "pdb": {
          "anyOf": [
            {
              "maxLength": 2500000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antigen structure in PDB format for antibody-antigen complex mode.",
          "title": "Pdb"
        }
      },
      "title": "ImmuneFoldPredictRequestItem",
      "type": "object"
    },
    "ImmuneFoldPredictRequestParams": {
      "additionalProperties": false,
      "properties": {
        "contact_idx": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Contact index for antibody-antigen complex prediction; used only when an antigen pdb is provided.",
          "title": "Contact Idx"
        }
      },
      "title": "ImmuneFoldPredictRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "anyOf": [
        {
          "$ref": "#/$defs/ImmuneFoldPredictRequestParams"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 32 per request.",
      "items": {
        "$ref": "#/$defs/ImmuneFoldPredictRequestItem"
      },
      "maxItems": 32,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "ImmuneFoldPredictRequest",
  "type": "object"
}

Response — ImmuneFoldPredictResponse

Field	Type	Required	Constraints	Description
`results`	list[ImmuneFoldPredictResponseResult]	yes		Per-input results, returned in the same order as the request items.

Nested types

ImmuneFoldPredictResponseResult

Field	Type	Required	Description
`ptm`	number	yes	Predicted TM-score (pTM) for the overall structure (0–1).
`mean_plddt`	number	yes	Mean per-residue pLDDT confidence score (0–100); higher values indicate more confident predictions.
`plddt`	list[list[number]]	yes	Per-residue pLDDT confidence scores for the predicted structure (0–100; higher is more confident).
`pdb`	string	yes	Predicted structure in PDB format.

Raw JSON Schema

{
  "$defs": {
    "ImmuneFoldPredictResponseResult": {
      "properties": {
        "ptm": {
          "description": "Predicted TM-score (pTM) for the overall structure (0\u20131).",
          "title": "Ptm",
          "type": "number"
        },
        "mean_plddt": {
          "description": "Mean per-residue pLDDT confidence score (0\u2013100); higher values indicate more confident predictions.",
          "title": "Mean Plddt",
          "type": "number"
        },
        "plddt": {
          "description": "Per-residue pLDDT confidence scores for the predicted structure (0\u2013100; higher is more confident).",
          "items": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "title": "Plddt",
          "type": "array"
        },
        "pdb": {
          "description": "Predicted structure in PDB format.",
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "ptm",
        "mean_plddt",
        "plddt",
        "pdb"
      ],
      "title": "ImmuneFoldPredictResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/ImmuneFoldPredictResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "ImmuneFoldPredictResponse",
  "type": "object"
}

Usage¶

One-line summary: PLM-enhanced antibody and TCR structure prediction model that combines ESM-2 3B representations with immune-protein-specific structural supervision for high-accuracy folding.

Overview¶

ImmuneFold is a structure prediction model developed by Wu et al. (2024) at CarbonMatrix Lab. It integrates ESM-2 (3B parameter protein language model) embeddings with a Transformer+GNN structure prediction module, achieving state-of-the-art accuracy on antibody and TCR structure prediction benchmarks. The model supports paired antibodies (VH/VL), nanobodies (VH-only), antibody-antigen complexes (with antigen PDB), and alpha/beta TCRs (with peptide-MHC context).

Architecture¶

Property	Value
Sequence encoder	ESM-2 3B (esm2_t36_3B_UR50D)
Structure module	Transformer + GNN hybrid
Input	Amino acid sequences (+ optional antigen PDB)
Output	PDB structure, pTM, full pLDDT, per-residue pLDDT
Confidence metrics	pTM (global), pLDDT (per-residue)

Capabilities & Limitations¶

CAN be used for: - Predicting paired antibody (VH/VL) structures with confidence scores - Predicting nanobody (VHH) structures from heavy chain only - Predicting antibody-antigen complex structures when antigen PDB is provided - Predicting alpha/beta TCR structures with peptide-MHC context - Assessing prediction confidence via pTM and pLDDT scores

CANNOT be used for: - General protein structure prediction (use AlphaFold2 or ESMFold) - Sequence design or inverse folding (use AntiFold) - Gamma/delta TCR prediction - Structures without sequences (requires amino acid input) - Sequences shorter than minimum lengths (VH < 90, VL < 85 AA)

Usage Examples¶

Paired antibody structure¶

from models.immunefold.schema import (
    ImmuneFoldPredictRequest,
    ImmuneFoldPredictRequestItem,
)

request = ImmuneFoldPredictRequest(
    items=[
        ImmuneFoldPredictRequestItem(
            heavy_chain="EVQLVESGGGLVQPGGSLRLSCAASGFTFSDYAMSWVRQAPGKGLEWVSGISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRLSITIRPRYYGLDVWGQGTTVTVSS",
            light_chain="DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPLTFGGGTKVEIK",
        )
    ],
)

Nanobody structure¶

request = ImmuneFoldPredictRequest(
    items=[
        ImmuneFoldPredictRequestItem(
            heavy_chain="QVQLQESGGGLVQPGGSLRLSCAASGRTFSSYAMGWFRQAPGKEREFVAAISWSGGSTYYADSVKGRFTISRDNAKNTVYLQMNSLKPEDTAVYYCAADSTIYASYYECGHGLSTGGYGYDSWGQGTQVTVSS",
        )
    ],
)

TCR structure with peptide-MHC¶

request = ImmuneFoldPredictRequest(
    items=[
        ImmuneFoldPredictRequestItem(
            tcr_beta="DAGVTQTPRNHVTISEGDKITVRCEKSTVSNFLYELFWYRQDPGLGLRLIYFSYDVKMKEKGDIPDGYSVSRNKKPNFYEALISKLNVSDSALYFCASSQETQYFGPGTRLTVL",
            tcr_alpha="AQEVTQIPAALSVPEGENLVLNCSFTDSAIYNLQWFRQDPGKGLTSLLLIQSSQREQTSGRLNASLDKSSGRSTLYIAASQPGDSATYLCAVRPTSGGSYIPTFGRGTSLIVHPY",
            peptide="GILGFVFTL",
            mhc="GSHSMRYFFTSVSRPGRGEPRFIAVGYVDDTQFVRFDSDAASQRMEPRAPWIEQEGPEYWDGETRKVKAHSQTHRVDLGTLRGYYNQSEAGSHTVQRMYGCDVGSDWRFLRGYHQYAYDGKDY",
        )
    ],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

ImmuneFold is a structure prediction model for antibodies and T-cell receptors that integrates protein language model (PLM) representations with geometric deep learning. It uses ESM-2 (3B parameter variant, esm2_t36_3B_UR50D) as a pre-trained sequence encoder, whose embeddings are fed into a structure prediction module that outputs 3D atomic coordinates with per-residue confidence scores.

The key innovation is combining the evolutionary information captured by ESM-2 (trained on billions of protein sequences) with immune-protein-specific structural supervision. This PLM-enhanced approach achieves higher accuracy than models trained from scratch on immune protein structures alone (e.g., ImmuneBuilder), particularly on CDR loops where sequence diversity is highest.

ImmuneFold supports two modes: antibody folding (VH/VL paired, VH-only nanobody, and VH/VL with antigen PDB) and TCR folding (alpha/beta/peptide/MHC four-chain input).

Parameters & Layers¶

Component	Details
Sequence encoder	ESM-2 3B (esm2_t36_3B_UR50D) -- 36 layers, 2560-dim embeddings
Structure module	Transformer + GNN hybrid
Antibody checkpoint	immunefold-ab.ckpt
TCR checkpoint	immunefold-tcr.ckpt
Input	Amino acid sequences (optionally with antigen PDB)
Output	PDB structure, pTM score, full pLDDT, per-residue pLDDT
Numbering	IMGT-based domain numbering (internal)

Training Data¶

Property	Details
PLM pre-training	ESM-2 trained on UniRef50 (~250M sequences)
Antibody fine-tuning	Paired antibody structures from structural databases
TCR fine-tuning	Alpha/beta TCR structures
Antigen handling	Antibody-antigen complexes for complex prediction
Domain detection	Internal IMGT-based renumbering pipeline

Loss Function & Objective¶

ImmuneFold is trained with a combination of: - Frame-Aligned Point Error (FAPE) loss for structural accuracy - pTM (predicted TM-score) auxiliary loss for confidence calibration - pLDDT (predicted local distance difference test) loss for per-residue confidence

Tokenization / Input Processing¶

Antibody input: heavy_chain, light_chain (optional for nanobodies)
TCR input: tcr_beta, tcr_alpha, peptide, mhc
Antigen PDB: Optional pdb string for antibody-antigen complex prediction
Legacy aliases: the old single-letter keys (H/L/B/A/P/M) are still accepted on input
Sequence validation: Extended amino acid alphabet; min lengths enforced (VH >= 90, VL >= 85 AA) to ensure IMGT numbering success
Type inference: Automatically inferred from chain combination:
heavy_chain + light_chain => antibody (paired)
heavy_chain only => nanobody
tcr_beta + tcr_alpha + peptide + mhc => TCR
Internal processing: FASTA-format intermediate files; Hydra-based config system

Performance & Benchmarks¶

Published Benchmarks¶

From Wu et al., bioRxiv (2024):

Antibody Structure Prediction¶

Model	CDR-H3 RMSD (A)	Overall RMSD (A)	Notes
ImmuneFold	~2.0	~1.2	PLM-enhanced
ABodyBuilder2	~2.8	~1.5	ImmuneBuilder
AlphaFold2	~3.4	~1.8	General-purpose

TCR Structure Prediction¶

Model	CDR3-beta RMSD (A)	Notes
ImmuneFold	~1.8	PLM-enhanced
TCRBuilder2	~2.2	ImmuneBuilder

BioLM Verification Results¶

Variant	Test Case	Tolerance	Status
antibody	Paired VH/VL	rel_tol 1e-4, PDB RMSD < 1e-4A	PASS
antibody	Nanobody (VH only)	rel_tol 1e-4, PDB RMSD < 1e-4A	PASS
antibody	Antigen complex	rel_tol 1e-4, PDB RMSD < 1e-4A	PASS
tcr	Alpha/beta TCR	rel_tol 1e-4, PDB RMSD < 1e-4A	PASS

Comparison to Alternatives¶

Model	Strength	When to prefer
ImmuneFold	PLM-enhanced; highest accuracy on immune proteins	When accuracy matters most; antibody-antigen complexes
ImmuneBuilder	Faster; CPU-only; no GPU required	Quick predictions; resource-constrained environments
AlphaFold2	Handles any protein	Non-immune proteins
ESMFold	Very fast	Rapid screening when accuracy is less critical

Strengths & Limitations¶

Pros¶

Highest accuracy for antibody CDR-H3 prediction among single-sequence methods
Supports antibody-antigen complex prediction with antigen PDB input
Confidence scores (pTM, pLDDT) for prediction quality assessment
Supports nanobodies (VH-only) and TCRs in addition to paired antibodies
ESM-2 backbone captures evolutionary information without MSA

Cons¶

Requires GPU (T4) due to ESM-2 3B model -- larger resource footprint than ImmuneBuilder
Minimum sequence lengths enforced (VH >= 90, VL >= 85 AA) for IMGT numbering
Maximum sequence length of 256 AA per chain
Relies on external Hydra config system and cloned GitHub repository
Domain numbering failures on unusual sequences produce assertion errors

Known Failure Modes¶

Sequences shorter than minimum lengths (VH < 90, VL < 85) fail domain numbering
Non-standard immune protein sequences that cannot be assigned IMGT numbering
Very long sequences exceeding 256 AA per chain
TCR inputs that lack all four required chains (B, A, P, M)

Implementation Details¶

Inference Pipeline¶

Request
  |-- 1. Validate sequences (amino acid alphabet, length constraints)
  |-- 2. Infer type from chain combination (antibody/nanobody/TCR)
  |-- 3. Write FASTA file with appropriate header
  |-- 4. If antigen PDB provided, write PDB file
  |-- 5. Load Hydra config with model-specific overrides
  |-- 6. Run ImmuneFold inference (ESM-2 encoding -> structure prediction)
  |-- 7. Read output PDB and confidence scores
  |-- 8. Clean up temporary files
  |-- 9. Return PDB string, pTM, full pLDDT, per-residue pLDDT

Memory & Compute Profile¶

Resource	Value
GPU	T4 (16 GB VRAM)
Memory	16 GB RAM
CPU	3.0 cores
Batch size	32
Max sequence length	256 per chain

Determinism & Reproducibility¶

Setting	Value
Torch manual seed	Yes (42 at model load)
CUDA manual seed	Yes (42, if available)
ESM-2 eval mode	Enabled

Caching Behavior¶

Response caching is handled at the service layer, not by the model container.

Versions & Changelog¶

Version	Date	Changes
v1	2025	Initial implementation with antibody and TCR variants

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

ImmuneFold is designed for two major classes of adaptive immune receptor proteins:

Antibodies: Paired heavy chain (VH) and light chain (VL) variable regions, single-domain nanobodies (VHH), and antibody-antigen complexes (when antigen PDB is provided)
T-cell receptors (TCRs): Paired alpha and beta chains, including peptide and MHC context

The model leverages ESM-2 protein language model representations for enhanced accuracy compared to models trained solely on structural data. It outputs full-atom 3D structures in PDB format along with confidence scores (pTM, pLDDT) for quality assessment.

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Paired antibodies (VH/VL)	High	Primary training target	VH >= 90 AA, VL >= 85 AA minimum
Nanobodies (VHH)	High	Supported via H-only input	Single heavy chain input
Antibody-antigen complexes	High	Supported with antigen PDB	Antigen must be provided as PDB string
Alpha/beta TCRs	High	Dedicated TCR checkpoint	Requires all 4 chains (B, A, P, M)
Gamma/delta TCRs	Low	Not specifically trained	May work but not validated
General proteins	Not applicable	Immune-protein-specific	Use AlphaFold2 or ESMFold

Biological Problems Addressed¶

High-Accuracy Antibody Structure Prediction¶

Biological context: Antibody CDR loops, especially CDR-H3, exhibit extreme structural diversity due to V(D)J recombination and somatic hypermutation. Accurately predicting CDR-H3 conformation is critical for understanding antigen binding, rational affinity maturation, and structure-guided design. While ImmuneBuilder provides useful predictions, PLM-enhanced models capture deeper evolutionary patterns that improve loop prediction.

How ImmuneFold helps: By combining ESM-2 3B representations (encoding evolutionary information from 250M protein sequences) with immune-protein-specific structural supervision, ImmuneFold achieves the highest CDR-H3 accuracy among single-sequence methods. The pTM and pLDDT confidence scores allow users to assess prediction reliability and identify regions of uncertainty.

Output interpretation: The ptm score (0--1) indicates global structural confidence (>0.7 is generally reliable). The mean_plddt is the mean per-residue confidence. Per-residue plddt scores identify which regions are predicted most/least confidently -- typically framework regions score highest and CDR-H3 scores lowest.

Antibody-Antigen Complex Prediction¶

Biological context: Understanding how an antibody binds its antigen at atomic resolution is essential for epitope mapping, rational design of affinity-matured variants, and predicting cross-reactivity. Experimental complex structures are expensive to obtain.

How ImmuneFold helps: When provided with both antibody sequences (H/L) and an antigen PDB structure, ImmuneFold predicts the antibody structure in the context of the antigen interface. This enables structural analysis of the paratope-epitope interaction without requiring an experimental co-crystal structure.

TCR Structure Prediction for Immunotherapy¶

Biological context: T-cell receptors recognize peptide-MHC complexes and are central to cancer immunotherapy (TCR-T cell therapy, checkpoint inhibitors) and autoimmune disease. Structural knowledge of the TCR-pMHC interface is critical for engineering TCRs with desired specificity and affinity.

How ImmuneFold helps: The TCR variant takes four chains as input -- beta (B), alpha (A), peptide (P), and MHC (M) -- and predicts the full complex structure. This enables rapid structural characterization of TCR candidates for therapeutic development.

Applied Use Cases¶

ImmuneFold enables computational structure prediction for immune proteins in drug development contexts:

Antibody candidate characterization: Rapid structural assessment of therapeutic antibody candidates from discovery campaigns
Epitope mapping: Predicting antibody-antigen complex structures to identify binding epitopes
TCR engineering: Structural modeling of engineered TCRs for immunotherapy applications
Input for downstream tools: Providing structures for inverse folding (AntiFold) or docking studies

Predecessor Models¶

ImmuneBuilder (Abanades et al., 2023): The non-PLM predecessor that uses EGNN ensembles trained directly on structural data. ImmuneFold improves upon ImmuneBuilder by incorporating ESM-2 pre-training, achieving lower RMSD on CDR loops.
ABodyBuilder2: The antibody sub-model within ImmuneBuilder. ImmuneFold's antibody variant is a direct improvement.

Complementary Models¶

AntiFold: Inverse folding model that can redesign sequences conditioned on ImmuneFold-predicted structures.
ESM2: The underlying language model used by ImmuneFold; can also provide independent sequence fitness scores.

Alternative Models¶

Alternative	Advantage over ImmuneFold	Disadvantage vs ImmuneFold
ImmuneBuilder	CPU-only; faster; lighter	Lower CDR accuracy
AlphaFold2 Multimer	MSA-enhanced; handles any complex	Slower; requires MSA; not immune-specialized
ESMFold	Much faster; single-sequence	Not immune-specialized; lower accuracy on CDRs

Biological Background¶

Protein Language Models for Structure Prediction¶

Protein language models (PLMs) like ESM-2 are trained on millions of protein sequences using masked language modeling objectives, analogous to BERT in natural language processing. Through this training, PLMs learn implicit evolutionary constraints -- which residues co-evolve, which positions tolerate substitutions, and which patterns indicate specific folds. These learned representations encode structural information that can be extracted and used for downstream structure prediction.

ImmuneFold exploits this by using ESM-2 3B (the largest freely available ESM-2 variant) as a feature extractor. The ESM-2 embeddings capture both local secondary structure preferences and long-range contacts that are particularly valuable for predicting CDR loop conformations, where sequence diversity makes purely structural approaches less effective.

Antibody Variable Domain Architecture¶

The antibody variable domain consists of: - Framework regions (FR1-FR4): Structurally conserved beta-sheet scaffold - CDR loops (CDR1, CDR2, CDR3): Hypervariable loops that form the antigen-binding surface - Disulfide bond: Conserved Cys23-Cys104 (IMGT numbering) stabilizing the immunoglobulin fold

CDR-H3 is generated by V(D)J recombination with N-nucleotide additions, creating extreme length and sequence diversity. This makes CDR-H3 the most challenging region to predict and the area where PLM-enhanced models show the greatest improvement.

IMGT Numbering and Domain Detection¶

ImmuneFold uses IMGT-based domain numbering internally to identify framework and CDR boundaries. Sequences that are too short to contain the conserved framework residues required for IMGT numbering (Cys-23, Trp-41, Cys-104, Phe/Trp-118) will fail domain detection. This is why minimum sequence lengths are enforced: VH >= 90 AA, VL >= 85 AA.

Sources & license¶

License: Apache-2.0 (text)

Papers

ImmuneFold: Improved antibody and TCR structure prediction with a pre-trained protein language model — bioRxiv preprint, 2024 · DOI

Source repositories

github: https://github.com/CarbonMatrixLab/immunefold

Cite

@article{wu2024immunefold,
  title={ImmuneFold: Improved antibody and TCR structure prediction with a pre-trained protein language model},
  author={Wu, Jiaxiang and Liu, Chenguang and Zhang, Guijun},
  journal={bioRxiv},
  year={2024},
  doi={10.1101/2024.12.23.630212}
}

ImmuneFold¶

At a glance¶

API & schema¶

fold¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Paired antibody structure¶

Nanobody structure¶

TCR structure with peptide-MHC¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Parameters & Layers¶

Training Data¶

Loss Function & Objective¶

Tokenization / Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

Antibody Structure Prediction¶

TCR Structure Prediction¶

BioLM Verification Results¶

Comparison to Alternatives¶

Strengths & Limitations¶

Pros¶

Cons¶

Known Failure Modes¶

Implementation Details¶

Inference Pipeline¶

Memory & Compute Profile¶

Determinism & Reproducibility¶

Caching Behavior¶

Versions & Changelog¶

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

Cross-Applicability¶

Biological Problems Addressed¶

High-Accuracy Antibody Structure Prediction¶

Antibody-Antigen Complex Prediction¶

TCR Structure Prediction for Immunotherapy¶

Applied Use Cases¶

Related Models¶

Predecessor Models¶

Complementary Models¶

Alternative Models¶

Biological Background¶

Protein Language Models for Structure Prediction¶

Antibody Variable Domain Architecture¶

IMGT Numbering and Domain Detection¶

Sources & license¶

`fold`¶