protein-docking-hdock

Submits protein-protein docking jobs to the HDOCK server and retrieves the resulting Docking Score, Confidence Score, ligand RMSD and ranked complex models. Uses plain HTTP form submission against the

SKILL.md

GitHub

HDOCK Protein Docking

Overview

This skill submits protein-protein docking jobs to the HDOCK server (http://hdock.phys.hust.edu.cn/) and collects the results: Docking Score, Confidence Score, ligand RMSD, and the ranked complex models.

It uses HTTP, not a browser

HDOCK publishes no REST API — only a web interface. The natural assumption is that this therefore requires Selenium. It does not.

The submission page is a standard HTML form POST. There is no CSRF token, no hidden field, no JavaScript-computed signature, and no session cookie. The form posts to runhdock.php, and the results page is an ordinary HTML table. Everything the old Selenium scripts did is reachable with requests.

The one thing worth knowing is that the form's action attribute is empty, and the real target is set by JavaScript at submit time:

if( ! sym.value ){
    document.form1.action = "runhdock.php";     // ordinary docking
}else{
    document.form1.action = "runhsymdock.php";  // symmetric multimer
}

Posting to the homepage instead of runhdock.php returns a byte-identical copy of the homepage — HTTP 200, no error, no result. This is the single most likely way to waste an hour of debugging.

Submission and retrieval are separate steps

HDOCK's own documentation says a job "can normally complete within 30 min". Baking the wait into the submission command means the user stares at a blank terminal for half an hour. This skill therefore splits the workflow:

submit_docking.py     →  returns a job URL in ~2 seconds
        ↓ (minutes to tens of minutes, server-side)
fetch_docking_results.py →  reads the score

Submitted jobs are appended to jobs.csv, so a batch can be collected later in one pass.

When to Use This Skill

  • Predicting a protein-protein complex structure with HDOCK
  • Getting the Docking Score / Confidence Score for a candidate complex
  • Screening many receptor-ligand pairs through the HDOCK server
  • Downloading the top-ranked docked models for further analysis

Quick Start

export PYTHONPATH="$PWD/packages"

# 用 PDB ID:ChainID 提交(最快,不用准备文件)
python scripts/submit_docking.py \
    --receptor-pdb-id 1CGI:E --ligand-pdb-id 1CGI:I \
    --job-name my_docking --output-dir results/

# 用 FASTA 序列提交
python scripts/submit_docking.py \
    --receptor-seq receptor.fasta --ligand-seq ligand.fasta \
    --output-dir results/

# 稍后取结果(查一次)
python scripts/fetch_docking_results.py \
    --url http://hdock.phys.hust.edu.cn/data/xxxxxxxxxxxx/ \
    --output-dir results/

# 批量收集所有已提交作业
python scripts/fetch_docking_results.py \
    --jobs-file results/jobs.csv --output-dir results/ --download-models

Workflow

Submission

  1. Provide one input per molecule. Each of the receptor and the ligand accepts exactly one of four input forms: a PDB file, a PDBID:ChainID string, a FASTA sequence, or a FASTA file. The --*-seq arguments accept either inline sequence text or a path to a FASTA file — the skill detects which.
  2. Submit. The skill GETs the homepage first (matching browser behaviour), then POSTs the multipart form to runhdock.php — or runhsymdock.php when --symmetry is given.
  3. Record. The job name, ID and URL are appended to jobs.csv and jobs.json in the output directory. The command returns immediately.

Retrieval

  1. Read the page. The result page has three possible states, which the skill distinguishes explicitly:

    State Marker on the page Reported status
    Queued is QUEUED queued
    Finished Docking Score table present done
    Failed ERROR: message failed

    This distinction matters. The old script treated "not ready yet" as "failed" and aborted the whole batch on the first unfinished job.

  2. Parse the ranking matrix. The results page is a matrix: rows are metrics (Docking Score, Ligand rmsd), columns are ranks 1–10. The skill extracts the full row, so the top-10 scores are all available, not just the best one.

  3. Compute Confidence Score if needed. HDOCK's documentation gives the closed form:

    Confidence_score = 1.0 / [1.0 + e^(0.02 * (Docking_Score + 150))]
    

    When the page does not include the column, the skill computes it from the Docking Score. The formula is public and exact — there is no reason to wait for an element that may never appear.

  4. Optionally download models. --download-models fetches the top-ranked complex models.

Parameters

submit_docking.py

Parameter Default Description
--receptor-pdb-id — Receptor as PDBID:ChainID (e.g. 1CGI:E)
--receptor-seq — Receptor FASTA sequence, inline text or file path
--receptor-pdb — Receptor PDB file path
--ligand-pdb-id — Ligand as PDBID:ChainID
--ligand-seq — Ligand FASTA sequence, inline text or file path
--ligand-pdb — Ligand PDB file path
--job-name timestamp Job label
--email none Notification address; the server emails you when the job finishes
--ligand-type protein protein, rna, dna, rna.d, ssdna
--symmetry none Symmetry such as C2 or D3; switches to the symmetric endpoint
--receptor-site none Receptor binding-site residues, comma separated
--ligand-site none Ligand binding-site residues, comma separated
--restraint none Residue distance restraints
--output-dir hdock_results Output directory for the job records
--timeout 180 Per-request timeout in seconds

fetch_docking_results.py

Parameter Default Description
--url — Single job result URL
--jobs-file — Job record CSV to process in batch
--output-dir hdock_results Output directory for the results
--wait off Poll until the job finishes instead of checking once
--poll-interval 20 Polling interval in seconds
--max-wait 3600 Maximum wait in seconds
--download-models off Download the top-ranked complex models
--top-n 5 How many models to download
--timeout 60 Per-request timeout in seconds

Outputs

File Content
jobs.csv / jobs.json Submitted jobs: name, ID, URL, status
results.csv / results.json Results: status, Docking Score, Confidence Score, error

Validation

  • A Docking Score is not a binding affinity. HDOCK's documentation is explicit: the score comes from a knowledge-based iterative scoring function and "should not be treated as the true binding affinity of two molecules because it has not been calibrated to the experimental data." It is useful for ranking candidate poses, not for predicting a Kd.
  • A more negative score is better. For comparison, complexes in the PDB normally score around −200 or better.
  • Confidence Score above 0.7 means "likely to interact". The score is a monotone function of the Docking Score, so it adds no information beyond the score itself — it just puts the result on an interpretable scale.
  • A queued job is not a failed job. status=queued means the server is still computing. HDOCK jobs commonly take 5–30 minutes; re-run the retrieval command later rather than resubmitting.
  • "No structure found" means the input was unusable, not that the interaction is impossible. Common causes: a chain ID that does not exist in that PDB entry, a sequence containing characters other than the 20 standard amino acids, or a PDB file that the server cannot parse. Check the chain ID format (1CGI:E — four-character PDB ID, colon, chain).
  • Results are stored for two weeks by the server. Retrieve them within that window or resubmit.
  • Sequence input is modelled, not docked as-is. HDOCK builds a structure from the sequence first (via homology modelling), then docks it. Upload PDB structures when you have them — the accuracy is better and the job is faster.
  • Bind the score to the job, not to the URL alone. Job names are normalised by the server (spaces become underscores); the job_id in the URL is the stable identifier.

References