LigandMPNN

LigandMPNN outputs both .fasta and .pdb files. It is recommended to use the .pdb files as they preserve chain letters and residue indices.

Confidence Metrics in FASTA files

The model writes two confidence metrics to the FASTA files:

• overall_confidence: The average confidence/probability (with $T=1.0$) over the redesigned residues, calculated as exp[-mean_over_residues(log_probs)]. Values range from 0.0 to 1.0. Higher values indicate higher model confidence.
• ligand_confidence: Reflects the confidence specifically regarding the ligand.

Sequence recovery is calculated only over the redesigned residues.

When adding bias, fixing residues, or selecting residues for redesign, you can use direct residue index notation. The format follows [Chain][ResidueIndex][InsertionCode].

Examples:

• A23: Chain A, residue index 23.
• B42D: Chain B, residue 42, insertion code D.

Execute the run.py script to perform sequence redesign. You must provide a PDB path and an output folder.

python run.py \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/default"

When retraining LigandMPNN, you must provide JSON files containing PDB IDs for the training, validation, and testing sets. The expected file structure is:

• Training set: train.json
• Validation set: valid.json
• Test sets (split by type):
  • Small molecules: test_small_molecule.json
  • Nucleotides: test_nucleotide.json
  • Metals: test_metal.json

To use LigandMPNN, clone the repository, download the model parameters, and set up a Python environment with the required dependencies.

1. Clone the repository

git clone https://github.com/dauparas/LigandMPNN.git
cd LigandMPNN

2. Download model parameters

Run the provided script to download the necessary model weights:

bash get_model_params.sh "./model_params"

3. Set up the environment

It is recommended to use a Conda environment. The project requires Python >= 3.0, PyTorch, Numpy, and ProDy for PDB file handling.

conda create -n ligandmpnn_env python=3.11
# Activate the environment
conda activate ligandmpnn_env
pip3 install -r requirements.txt

Use score.py with --single_aa_score 1 to get probabilities/scores using the logic: $p(AA_i|backbone, AA_{all ext{ except } AA_i})$.

Note: These probabilities depend on the decoding order. It is highly recommended to set --number_of_batches to at least 10. Use --use_sequence 1 to include sequence information or --use_sequence 0 for backbone-only information.

# Single amino acid score with sequence info
python score.py \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --single_aa_score 1\
        --pdb_path "./outputs/ligandmpnn_default/backbones/1BC8_1.pdb" \
        --out_folder "./outputs/single_aa_score_w_seq" \
        --use_sequence 1\
        --batch_size 1 \
        --number_of_batches 10

Use score.py with --autoregressive_score 1 to get probabilities/scores using the chain: $p(AA_1|backbone), p(AA_2|backbone, AA_1)$, etc.

Note: These probabilities depend on the decoding order. It is highly recommended to set --number_of_batches to at least 10 to ensure stability. Use --use_sequence 1 to include sequence information or --use_sequence 0 for backbone-only information.

# Autoregressive with sequence info
python score.py \
        --model_type "ligand_mpnn" \
        --seed 111 \
        --autoregressive_score 1\
        --pdb_path "./outputs/ligandmpnn_default/backbones/1BC8_1.pdb" \
        --out_folder "./outputs/autoregressive_score_w_seq" \
        --use_sequence 1\
        --batch_size 1 \
        --number_of_batches 10

To run the basic LigandMPNN design process, use run.py with a PDB path and an output folder. By default, if no --model_type is specified, it runs ProteinMPNN.

python run.py \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --out_folder "./outputs/default"

When running score.py, the resulting output dictionary (out_dict) contains the following keys used to evaluate backbone-sequence pairs or backbone-only structures:

• logits: raw logits from the model
• probs: softmax(logits)
• log_probs: log_softmax(logits)
• decoding_order: the decoding order used (note: logits depend on this order)
• native_sequence: parsed input sequence in integers
• mask: mask for missing residues (usually all ones)
• chain_mask: controls which residues are decoded first
• alphabet: amino acid alphabet used
• residue_names: dictionary mapping integers to residue names (e.g., {0: "C10", 1: "C11"})
• sequence: parsed input sequence in alphabet
• mean_of_probs: averaged probabilities over batch_size * number_of_batches, shape [protein_length, 21]
• std_of_probs: standard deviation of probabilities, same shape as mean_of_probs

Use --omit_AA to restrict the output to a specific set of amino acids. This is functionally equivalent to setting a large negative bias for all other amino acids.

python run.py \
        --seed 111 \
        --pdb_path "./inputs/1BC8.pdb" \
        --omit_AA "CDFGHILMNPQRSTVWY" \
        --out_folder "./outputs/global_omit"