---
title: Protein Preparation
description: >-
  Prepare protein structures for docking with protonation and binding site
  detection (PDB2PQR, P2Rank).
tags:
  - protein
  - preparation
  - docking
  - pdb
  - binding-sites
---

  intermediate
  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](/docs/cli).

## 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:

```bash
# 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]` (string) —
Local PDB file (uploaded on submit, max 2 MB) or a 4-character PDB ID (e.g., `1ABC`). Positional argument.

- `--ph` (float) —
pH for protonation state assignment (0–14). Controls histidine, aspartate, glutamate, and lysine charge.

- `--force-field` (string) —
Force field for protonation: `AMBER`, `CHARMM`, or `PARSE`.

- `--keep-heteroatoms` (bool) —
Keep ligands, ions, and water molecules. By default they are removed.

- `--detect-sites` (bool) —
Also run P2Rank binding site detection on the same structure.

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

- `--overwrite` (bool) —
Overwrite an existing `--output` file instead of failing.

- `--wait` (bool) —
Wait for the jobs to finish and return results. Set to `false` to submit and return job IDs only.

- `--detailed` (bool) —
Show the per-residue protonation table for human output.

- `--min-volume` (float) —
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:

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

### Parameters

- `[pdb-file|pdb-id]` (string) —
Local PDB file (max 2 MB) or PDB ID.

- `--ph` (float) —
Target pH (0–14).

- `--force-field` (string) —
Force field: `AMBER`, `CHARMM`, or `PARSE`.

- `--keep-heteroatoms` (bool) —
Keep ligands, ions, and waters.

- `--output` (string) —
Save protonated structure as PQR (short form `-o`).

- `--overwrite` (bool) —
Overwrite an existing output file.

- `--wait` (bool) —
Wait for the job to finish.

- `--detailed` (bool) —
Show the per-residue protonation table.

---

## Binding Site Detection (sites)

Identify druggable binding pockets on a protein surface using P2Rank:

```bash
# 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.

- `--uniprot` (string) —
UniProt accession (e.g., `P00533`). Only this command accepts UniProt.

- `--pdb-id` (string) —
Explicit PDB ID flag (alternative to positional argument).

- `--top` (int) —
Return only the top N highest-scoring pockets. Omit or set to 0 to return all.

- `--model` (string) —
P2Rank model: `default` or `alphafold`. The `alphafold` model works better on predicted structures.

- `--visualization` (bool) —
Generate pocket visualization files (PML, trajectory, etc.).

- `--wait` (bool) —
Wait for the job to finish.

- `--min-volume` (float) —
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:

```bash
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-id` (string) —
Job ID returned by a previous `run`, `protonate`, or `sites` command.

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

- `--overwrite` (bool) —
Overwrite an existing output file.

- `--detailed` (bool) —
Show the per-residue protonation table.

---

## Workflow Examples

### PDB File to Docking-Ready Structure

```bash
# 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

```bash
# 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):

```bash
# 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`.

---

## Read next

- [Job Management](/docs/cli/jobs) — Monitor preparation and docking jobs
- [Batch Processing](/docs/cli/batch) — Screen multiple structures in parallel
- [Recipes](/docs/cli/recipes) — Complete drug discovery workflows