Prepare protein structures for docking with protonation and binding site detection (PDB2PQR, P2Rank).

Difficulty

intermediate

Prerequisites

A PDB file (max 2 MB) or PDB ID, Authenticated CLI (ivybloom auth login)

Protein preparation makes raw PDB structures docking-ready by assigning protonation states (PDB2PQR/PROPKA) and detecting binding sites (P2Rank). Use these commands in scripted pipelines to prepare structures before docking, rather than preparing each protein by hand. For the full CLI command set, see the CLI overview.

Protein Preparation (since v0.8.10)

Prepare protein structures with PDB2PQR protonation and P2Rank binding site detection.

Overview

The proteinprep command group runs the same jobs as the web chat:

Command	Job	Backend	Input
`run`	PDB2PQR protonation + optional P2Rank	PDB2PQR/PROPKA + P2Rank	PDB file or ID
`protonate`	PDB2PQR protonation only	PDB2PQR/PROPKA	PDB file or ID
`sites`	P2Rank binding site detection	P2Rank	PDB file, ID, or UniProt
`status`	Poll a job by ID	—	Job ID

Note: Structure quality checks are not available; the server has no quality backend. Upload structures up to 2 MB. Use the web chat if you need visual inspection before submission.

Full Preparation (run)

Protonate a structure and optionally detect binding sites:

# Basic protonation
ivybloom proteinprep run structure.pdb --output prepared.pqr

# With binding site detection
ivybloom proteinprep run structure.pdb --ph 7.4 --detect-sites --output prepared.pqr

# Use a PDB ID instead of a file
ivybloom proteinprep run 1ABC --detect-sites

# Don't wait for completion (starts job in background)
ivybloom proteinprep run structure.pdb --wait=false

Parameters

[pdb-file|pdb-id]stringrequired

Local PDB file (uploaded on submit, max 2 MB) or a 4-character PDB ID (e.g., 1ABC). Positional argument.

--phfloatdefault: 7.4

pH for protonation state assignment (0–14). Controls histidine, aspartate, glutamate, and lysine charge.

--force-fieldstringdefault: AMBER

Force field for protonation: AMBER, CHARMM, or PARSE.

--keep-heteroatomsbooldefault: false

Keep ligands, ions, and water molecules. By default they are removed.

--detect-sitesbooldefault: false

Also run P2Rank binding site detection on the same structure.

--outputstring

Save the protonated structure as PQR to this file (short form -o). Only works when --wait=true.

--overwritebooldefault: false

Overwrite an existing --output file instead of failing.

--waitbooldefault: true

Wait for the jobs to finish and return results. Set to false to submit and return job IDs only.

--detailedbooldefault: false

Show the per-residue protonation table for human output.

--min-volumefloatdefault: 0

Hide pockets smaller than this volume in Ų (applied locally, doesn't affect server results).

Protonation Only (protonate)

Assign protonation states at a target pH without detecting binding sites:

ivybloom proteinprep protonate structure.pdb --ph 7.4 --output protonated.pqr
ivybloom proteinprep protonate 1ABC --ph 5.0 --detailed

Parameters

[pdb-file|pdb-id]stringrequired

Local PDB file (max 2 MB) or PDB ID.

--phfloatdefault: 7.4

Target pH (0–14).

--force-fieldstringdefault: AMBER

Force field: AMBER, CHARMM, or PARSE.

--keep-heteroatomsbooldefault: false

Keep ligands, ions, and waters.

--outputstring

Save protonated structure as PQR (short form -o).

--overwritebooldefault: false

Overwrite an existing output file.

--waitbooldefault: true

Wait for the job to finish.

--detailedbooldefault: false

Show the per-residue protonation table.

Binding Site Detection (sites)

Identify druggable binding pockets on a protein surface using P2Rank:

# Detect sites from a PDB file
ivybloom proteinprep sites structure.pdb

# Keep the five best sites
ivybloom proteinprep sites structure.pdb --top 5

# From a PDB ID
ivybloom proteinprep sites 1ABC --top 10

# From a UniProt accession (sites only)
ivybloom proteinprep sites --uniprot P00533 --model alphafold --top 5

Parameters

[pdb-file|pdb-id]string

Local PDB file, PDB ID, or UniProt accession. One is required unless --uniprot is used.

--uniprotstring

UniProt accession (e.g., P00533). Only this command accepts UniProt.

--pdb-idstring

Explicit PDB ID flag (alternative to positional argument).

--topintdefault: 0

Return only the top N highest-scoring pockets. Omit or set to 0 to return all.

--modelstringdefault: default

P2Rank model: default or alphafold. The alphafold model works better on predicted structures.

--visualizationbooldefault: false

Generate pocket visualization files (PML, trajectory, etc.).

--waitbooldefault: true

Wait for the job to finish.

--min-volumefloatdefault: 0

Hide pockets smaller than this volume in Ų (applied locally, doesn't affect server results).

P2Rank: Machine learning-based pocket prediction optimized for druggability scoring. This is the only method available. Fpocket and DoGSiteScorer are not supported by the CLI.

Job Status (status)

Check the status of a submitted protonation or binding site job:

ivybloom proteinprep status 3f1c0e9a-...

# Save a completed protonation job's PQR to disk
ivybloom proteinprep status 3f1c0e9a-... --output prepared.pqr

# Show detailed residue info
ivybloom proteinprep status 3f1c0e9a-... --detailed

Parameters

job-idstringrequired

Job ID returned by a previous run, protonate, or sites command.

--outputstring

Save a completed protonation job's PQR to this file (short form -o).

--overwritebooldefault: false

Overwrite an existing output file.

--detailedbooldefault: false

Show the per-residue protonation table.

Workflow Examples

PDB File to Docking-Ready Structure

# 1. Protonate and detect sites
ivybloom proteinprep run receptor.pdb \
  --ph 7.4 \
  --detect-sites \
  --output prepared.pqr \
  --wait

# 2. Dock a ligand to the prepared structure
ivybloom run diffdock \
  receptor_pdb=prepared.pqr \
  ligand_smiles="CC(=O)Oc1ccccc1C(=O)O" \
  --follow

Batch Preparation with Polling

# Submit multiple structures without waiting
JOB_IDS=()
for pdb in *.pdb; do
  RESULT=$(ivybloom proteinprep run "$pdb" --wait=false --agent)
  JOB_ID=$(echo "$RESULT" | jq -r '.data.protonation_job_id // .data.job_id')
  JOB_IDS+=("$JOB_ID")
done

# Poll each job
for job_id in "${JOB_IDS[@]}"; do
  while true; do
    STATUS=$(ivybloom proteinprep status "$job_id" --agent)
    STATE=$(echo "$STATUS" | jq -r '.data.status')
    [ "$STATE" = "completed" ] && break
    sleep 5
  done
  echo "$job_id done"
done

AlphaFold Structure to Binding Sites

When you have a predicted structure (e.g., from ESMFold):

# 1. Fold the protein
ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAII... --wait

# 2. Download the structure
ivybloom jobs download JOB_ID --output ./structure/

# 3. Detect binding sites using the alphafold model
ivybloom proteinprep sites ./structure/predicted_structure.pdb \
  --model alphafold \
  --top 5

# 4. Review the top 5 pockets

Troubleshooting

Job failed: Check the error message in the status. Common issues:

File is corrupted or not a valid PDB format
File is too large (max 2 MB)
Invalid pH range (must be 0–14)
Invalid force field (use AMBER, CHARMM, or PARSE)

PQR file is empty: Protonation jobs return PQR (not PDB) on success. Use --output filename.pqr, not .pdb.

Binding sites not detected: The structure may have unusual chains or be very small. Try the full structure without filtering by --top.

Protein Preparation

Difficulty

Prerequisites

Protein Preparation (since v0.8.10)

Overview

Full Preparation (run)

Parameters

Protonation Only (protonate)

Parameters

Binding Site Detection (sites)

Parameters

Job Status (status)

Parameters

Workflow Examples

PDB File to Docking-Ready Structure

Batch Preparation with Polling

AlphaFold Structure to Binding Sites

Troubleshooting

Read next

On this page