ImmuneBuilder

To use ImmuneBuilder, you must install the core package along with py3Dmol for visualization. The environment also requires conda for managing specialized bioinformatics and molecular dynamics tools like ANARCI (for sequence numbering) and OpenMM (for Amber refinement).

In a notebook environment, the following commands are used to set up the environment:

# Install core packages
pip install ImmuneBuilder
pip install py3Dmol

# Install OpenMM for Amber refinement via conda
conda install -y -q -c conda-forge openmm=7.7.0 pdbfixer

# Install ANARCI and related tools via bioconda
conda install -y -q anarci hmmer biopython -c bioconda --no-deps --solver=classic

# Note: The notebook uses a bash script to automate this.
# pip install ImmuneBuilder
# pip install py3Dmol
# conda install -y -q -c conda-forge openmm=7.7.0 pdbfixer
# conda install -y -q anarci hmmer biopython -c bioconda --no-deps --solver=classic

You can predict antibody structures using either the Python API or the Command Line Interface (CLI). Using the Python API is recommended for batch processing as it avoids reloading models for every prediction.

Python API

Use the ABodyBuilder2 class. The predict method accepts a dictionary of sequences where keys are chain identifiers (e.g., 'H' for heavy, 'L' for light).

CLI

Run the ABodyBuilder2 command directly on a FASTA file.

ABodyBuilder2 --fasta_file my_antibody.fasta -v

from ImmuneBuilder import ABodyBuilder2
predictor = ABodyBuilder2()

output_file = "my_antibody.pdb"
sequences = {
  'H': 'EVQLVESGGGVVQPGGSLRLSCAASGFTFNSYGMHWVRQAPGKGLEWVAFIRYDGGNKYYADSVKGRFTISRDNSKNTLYLQMKSLRAEDTAVYYCANLKDSRYSGSYYDYWGQGTLVTVS',
  'L': 'VIWMTQSPSSLSASVGDRVTITCQASQDIRFYLNWYQQKPGKAPKLLISDASNMETGVPSRFSGSGTDFTFTISSLQPEDIATYYCQQYDNLPFTFGPGTKVDFK'
}

antibody = predictor.predict(sequences)
antibody.save(output_file)

Predict T-Cell receptor structures using the TCRBuilder2 class.

Note on Weights: By default, TCRBuilder2 uses the updated TCRBuilder2+ weights. To use the original weights, set use_TCRBuilder2_PLUS_weights=False in the Python constructor or use the --original_weights flag in the CLI.

Python API

The predict method accepts a dictionary of sequences where keys are chain identifiers (typically 'A' for alpha and 'B' for beta).

CLI

TCRBuilder2 --fasta_file my_tcr.fasta -v

from ImmuneBuilder import TCRBuilder2
predictor = TCRBuilder2()

output_file = "my_tcr.pdb"
sequences = {
"A": "AQSVTQLGSHVSVSEGALVLLRCNYSSSVPPYLFWYVQYPNQGLQLLLKYTSAATLVKGINGFEAEFKKSETSFHLTKPSAHMSDAAEYFCAVSEQDDKIIFGKGTRLHILP",
"B": "ADVTQTPRNRITKTGKRIMLECSQTKGHDRMYWYRQDPGLGLRLIYYSFDVKDINKGEISDGYSVSRQAQAKFSLSLESAIPNQTALYFCATSDESYGYTFGSGTRLTVV"
}

tcr = predictor.predict(sequences)
tcr.save(output_file)

Once a structure is predicted and saved as a .pdb file, you can visualize it using py3Dmol. The notebook implementation supports several coloring modes:

• chain: Colors chains specifically (e.g., Heavy chain 'H' as purple, Light chain 'L' as green).
• rainbow: Uses a standard spectrum coloring.
• predicted_error: Colors the structure by the B-factor, which represents the residue-level error estimate (calculated by comparing model agreement). A gradient from red to blue (roygb) is used, where the scale is mapped from min: 5 to max: 0.

You can also toggle the visibility of sidechains and mainchains.

import py3Dmol

view = py3Dmol.view()
view.addModel(open('ImmuneBuilder_model.pdb', 'r').read(), 'pdb')
view.zoomTo()
view.setBackgroundColor('white')

# Example: Color by predicted error (B-factor)
view.setStyle({'cartoon': {'colorscheme': {'prop':'b','gradient': 'roygb','min':5,'max':0}}})

# Example: Show sidechains
view.addStyle({'and':[{'resn':["GLY","PRO"],'invert':True},{'atom':['C','O','N'],'invert':True}]},
              {'stick':{'colorscheme':'WhiteCarbon','radius':0.3}})

view.show()

ImmuneBuilder provides three distinct predictor classes depending on the type of immune protein you are modeling. You must first instantiate the appropriate predictor and then pass a dictionary where keys are the chain identifiers (determined via anarci.number) and values are the amino acid sequences.

Predictor Classes

• ABodyBuilder2(): For Antibodies.
• NanoBodyBuilder2(): For Nanobodies.
• TCRBuilder2(): For T-Cell Receptors.

Usage Pattern

1. Identify chain IDs using anarci.number(sequence).
2. Construct an input dictionary: {chain_id: sequence}.
3. Call .predict(input) on the predictor instance.
4. Use .save(filename) to export the result as a PDB file.

from ImmuneBuilder import ABodyBuilder2, NanoBodyBuilder2, TCRBuilder2
from anarci import number

# 1. Initialize predictor
predictor = ABodyBuilder2()

# 2. Prepare input (example for antibody with two chains)
_, chain1 = number(sequence_1)
_, chain2 = number(sequence_2)

input_dict = {}
if chain1: input_dict[chain1] = sequence_1
if chain2: input_dict[chain2] = sequence_2

# 3. Predict and save
try:
    predictor.predict(input_dict).save('output.pdb')
except KeyError as e:
    print(f"ERROR: Missing sequence for chain {str(e)}")