An automated, pocket-guided molecular docking and protein–ligand interaction analysis workflow for structure-based virtual screening.
The pipeline integrates ligand retrieval, receptor and ligand preparation, binding-pocket prediction, batch molecular docking, docking-score ranking, ligand-efficiency analysis, docked-pose interaction profiling, visualization, experiment archiving, and automated scientific reporting into a reproducible Python workflow.
Molecular docking studies often require repetitive manual work across multiple tools: downloading compounds, preparing ligands, converting structures, identifying a binding pocket, configuring docking coordinates, running each ligand separately, extracting scores, ranking compounds, and analyzing protein–ligand interactions.
This project automates those stages into a single workflow.
- A receptor structure in PDB format
- A list of PubChem compound IDs
Protein Structure + Compound List
|
v
Input Validation
|
v
Previous Run Archiving
|
v
Output Cleanup
|
v
Protein Preparation
|
v
Automatic Ligand Retrieval
|
v
Receptor Conversion
|
v
Ligand Preparation
|
v
Binding-Pocket Prediction
P2Rank
|
v
Automatic Docking-Box Setup
|
v
Batch Molecular Docking
AutoDock Vina
|
v
Docking Score Parsing
|
v
Ligand Ranking
|
v
Docking Statistics
|
v
Ligand Efficiency
|
v
Protein-Ligand Interaction Analysis
ProLIF
|
v
Interaction Fingerprints
|
v
Binding-Residue Identification
|
v
Visualization + Scientific Reporting
PubChem compound IDs are read from:
data/ligands/compound_list.txt
The requested compounds are automatically retrieved and assembled into a ligand dataset for downstream preparation.
The receptor structure is processed before docking.
The pipeline also summarizes structural information including:
- atom count
- residue count
- chain count
- heteroatom count
P2Rank is used to identify predicted ligand-binding pockets.
The highest-ranked predicted pocket is automatically selected and converted into an AutoDock Vina search box.
This reduces manual docking-box configuration.
Prepared ligands are automatically docked against the receptor using AutoDock Vina.
The pipeline:
- runs docking for every prepared ligand
- stores docked poses
- extracts Vina binding affinities
- ranks compounds by docking score
The pipeline automatically calculates summary statistics for a docking experiment, including:
- best binding affinity
- worst binding affinity
- mean affinity
- median affinity
- standard deviation
Ligand-efficiency analysis is included as an additional compound-evaluation metric.
This provides a size-normalized complement to raw docking affinity when comparing docked ligands.
Validated Vina docked poses are analyzed using ProLIF.
The interaction-analysis stage detects:
- hydrogen bonds
- hydrophobic contacts
- π–π stacking
- π–cation interactions
- salt bridges
- metal interactions
- halogen bonds
- binding residues
Interaction fingerprints are generated for every successfully analyzed ligand.
Interaction-analysis failures are not silently replaced with zero-valued results.
For every ranked ligand, the pipeline requires:
- a valid docked pose
- successful ProLIF worker execution
- complete interaction data
- a generated interaction fingerprint
- a generated LigNetwork file
If one or more ligands fail interaction analysis, the interaction stage raises an error and the pipeline is not reported as successfully completed.
ProLIF LigNetwork HTML files are generated for analyzed docked poses.
These interactive networks provide atom-level ligand visualization and residue-level interaction information.
The pipeline automatically generates a PyMOL script for visualization of:
- the receptor
- ranked docked ligand poses
This allows docking results to be inspected in a molecular visualization environment.
The reporting system automatically generates:
- ranked docking CSV
- interaction-analysis CSV
- structured Excel workbook
- JSON report
- HTML dashboard
- PDF interaction report
- SVG interaction-profile figures
- 600 DPI PNG interaction-profile figures
- ProLIF interaction fingerprints
- interactive LigNetwork HTML files
- PyMOL visualization script
The static SVG and PNG interaction-profile figures summarize interaction counts.
They should not be interpreted as structural 2D ligand–residue diagrams.
Structural interaction visualization is provided by the ProLIF LigNetwork output.
Before the library is screened, the docking protocol is validated by re-docking the co-crystallized reference ligand and measuring a symmetry-aware RMSD to the crystal pose.
The pipeline distinguishes:
- reproduction of the crystal pose as the top-ranked pose
- reproduction only as a sampled (non-top) pose
- targets with no co-crystal ligand, where redocking is not applicable
The result gates the run, so a screen is never reported without disclosing whether its protocol can reproduce a known binding pose.
Docked poses can be rescored with a second scoring function and fused into a consensus ranking using Exponential Consensus Ranking.
- Vinardo rescoring uses the same Vina binary (no extra installation)
- smina and gnina are used automatically when their executables are configured
- the Vina ranking is never replaced; a separate
consensus_report.csvis added
With only Vina available the consensus equals the Vina ranking, so the stage is safe to leave enabled.
Docked poses are optionally screened with PoseBusters for physical plausibility, including bond lengths, bond angles, steric clashes, and planarity.
Physically implausible poses are flagged and can optionally be excluded from the consensus ranking.
The ligand library is profiled independently of the target:
- drug-likeness rule sets (Lipinski, Veber, Egan, Ghose, Muegge)
- QED and key physicochemical descriptors
- structural-alert catalogues (PAINS, Brenk, NIH)
- optional ADMET-AI machine-learning endpoints (hERG, AMES, CYP, DILI, BBB, and others)
Results are written to admet_report.csv to support multi-parameter hit prioritization.
For targets without a co-crystal ligand, the protocol can instead be validated by enrichment: known actives are docked against property-matched decoys through the same protocol.
The validator reports ROC-AUC, enrichment factor (EF) at 1/5/10%, and BEDROC — the evidence that a screen separates binders from non-binders.
The top-ranked ligands can be re-docked under multiple random seeds to quantify how robust each rank is.
For every evaluated compound the pipeline reports the score mean and 95% confidence interval, the rank standard deviation, and Kendall's W for the set — distinguishing a real rank from search noise.
A single PDF merges the ranking, consensus, ADMET, interaction, and validation outputs and interprets them automatically.
- assigns each compound a molecular-dynamics-readiness tier
- names a recommended candidate with an explicit rationale
- flags greasy, reactive, or physically invalid hits
- states what the validation result means for the run
This removes the need to cross-reference separate output files by hand.
Receptor preparation uses Meeko. When Meeko's polymer builder rejects a structure — for example disulfides, modified residues, or unusual connectivity — preparation automatically falls back to a template-free converter (ADFR prepare_receptor or OpenBabel) instead of aborting the run.
The Meeko error and the fallback used are recorded in the preparation provenance.
Every run records a machine-readable manifest containing tool and library versions, the random seed and sampling parameters, and SHA-256 hashes of the configuration and every input file.
This makes a completed run traceable and repeatable.
AutoDock-Pipeline/
|
|-- config/
| |-- config.yaml
| |-- targets.yaml
| `-- tools.yaml
|
|-- data/
| |-- ligands/
| | `-- compound_list.txt
| |
| `-- proteins/
| `-- receptor.pdb
|
|-- src/
| |
| |-- analysis/
| | |-- interaction_analyzer.py
| | |-- ligand_efficiency.py
| | |-- prolif_worker.py
| | |-- ranking.py
| | |-- score_parser.py
| | `-- statistics.py
| |
| |-- chemistry/
| |
| |-- core/
| | |-- config_loader.py
| | |-- exceptions.py
| | |-- logger.py
| | |-- pipeline_manager.py
| | |-- run_archiver.py
| | `-- run_cleaner.py
| |
| |-- databases/
| |
| |-- docking/
| | |-- base_engine.py
| | |-- batch_docking.py
| | `-- vina_engine.py
| |
| |-- plugins/
| |
| |-- preparation/
| | |-- ligand_fetcher.py
| | |-- ligand_preparation.py
| | |-- pocket_detector.py
| | |-- protein_converter.py
| | `-- protein_preparation.py
| |
| |-- reporting/
| | |-- csv_report.py
| | |-- excel_report.py
| | |-- html_report.py
| | |-- interaction_report.py
| | `-- json_report.py
| |
| |-- utils/
| |
| `-- visualization/
| |-- pose_export.py
| `-- pymol_generator.py
|
|-- environment.yml
|-- requirements.txt
|-- run_pipeline.py
`-- README.md
Generated outputs, experiment archives, and external software installations are excluded from version control.
The workflow uses:
- Python
- AutoDock Vina 1.2.7
- P2Rank
- Meeko
- ProLIF
- RDKit
- MDAnalysis
- Open Babel
- pandas
- matplotlib
- openpyxl
- ReportLab
- PyMOL
AutoDock Vina and P2Rank are treated as external tools and are not bundled with this repository.
Their local executable paths are configured in:
config/tools.yaml
Clone the repository:
git clone https://github.com/RahulRoktim/AutoDock-Pipeline.git
cd AutoDock-PipelineCreate the primary Conda environment:
conda env create -f environment.yml
conda activate autodock_pipelineAutoDock Vina and P2Rank must be installed separately.
The default project-relative tool locations are:
tools/AutoDockVina/vina.exe
tools/p2rank/prank.bat
Alternative locations can be configured in:
config/tools.yaml
The current implementation executes ProLIF interaction analysis through an isolated Python environment to avoid binary dependency conflicts encountered during development.
The ProLIF worker is executed as a subprocess by the main pipeline.
The interaction-analysis Python executable must therefore be configured for the local system before reproducing the complete workflow.
Place the receptor structure at:
data/proteins/receptor.pdb
Add one PubChem CID per line to:
data/ligands/compound_list.txt
Example:
2244
3672
5280343
969516
The ligand dataset is generated automatically and is not tracked by Git.
Activate the primary environment:
conda activate autodock_pipelineRun:
python run_pipeline.pyThe workflow then executes the configured docking and interaction-analysis stages.
Pipeline results are written to:
output/
|
|-- cache/
|-- docking/
|-- figures/
| `-- interactions/
|
|-- interactions/
|-- logs/
|-- pdbqt/
|-- pockets/
|-- poses/
|-- prepared/
|-- pymol/
`-- reports/
The workflow stores:
- prepared receptor structures
- prepared ligand structures
- PDBQT files
- predicted pocket information
- docked poses
- ranked docking results
For every successfully analyzed ligand:
*_fingerprint.pkl
*_interactions.json
*_lignetwork.html
The reporting stage generates:
ranked_results.csv
interaction_results.csv
consensus_report.csv
admet_report.csv
uncertainty_report.csv
Docking_Report.xlsx
Docking_Report.json
Docking_Report.html
Interaction_Report.pdf
Campaign_Report.pdf
provenance_manifest.json
Interaction-profile figures are generated in:
output/figures/interactions/
in both SVG and 600 DPI PNG formats.
Previous experiment results are archived before a new run.
Timestamped experiment directories preserve relevant inputs and generated results for later inspection.
This reduces the risk of mixing files from separate docking experiments and improves workflow traceability.
Generated experiment archives are excluded from Git version control.
This pipeline is designed for automated structure-based virtual screening and post-docking interaction analysis.
The workflow does not claim that docking scores represent experimental binding affinity.
It does not independently establish:
- biological activity
- clinical efficacy
- compound safety
- pharmacokinetic suitability
- therapeutic effectiveness
The pipeline does not replace:
- experimental binding assays
- biological validation
- toxicity studies
- molecular dynamics simulations where conformational dynamics are required
AutoDock Vina scores are treated as computational ranking metrics within the limitations of the docking scoring function.
Predicted protein–ligand interactions are derived from computationally generated docked poses and therefore depend on docking-pose quality.
The workflow runs end to end — from receptor and compound input through docking, interaction analysis, and report generation — and has been exercised across several protein–ligand systems.
Crystallographic redocking validation is now implemented. Each run re-docks the co-crystallized reference ligand, computes a symmetry-aware RMSD to the crystal pose, and gates the run on the result. On validated targets the protocol reproduces the crystal pose as the top-ranked pose; for apo targets with no reference ligand, retrospective enrichment (known actives versus property-matched decoys) is provided as the alternative validation route.
Docking scores are treated as approximate ranking metrics, not experimental affinities. This repository remains a computational screening and workflow project and does not replace experimental validation.
Implemented since the initial release:
- co-crystallized ligand redocking with RMSD-based pose reproduction
- consensus rescoring, PoseBusters pose validity, and replicate rank-uncertainty
- integrated drug-likeness / ADMET triage and multi-parameter hit prioritization
- an interpreted campaign report and a reproducibility manifest
Future scientific development includes:
- broader redocking and enrichment validation across additional protein–ligand systems
- docking-workflow benchmarking against reference datasets
- coupling to molecular dynamics and binding free-energy estimation (MM-PBSA / MM-GBSA)
- an orthogonal machine-learning rescorer at screening scale
- standardized cross-pipeline data exchange and QSAR integration
The objective of this project is to reduce repetitive manual operations in molecular docking studies while preserving modular analysis stages, traceable outputs, and reproducible experiment organization.
The project was developed as part of my training in computational drug discovery and computer-aided drug design.
Rahul Roktim
BPharm Student
Research interests:
- Computer-Aided Drug Design
- AI-Driven Drug Discovery
- Molecular Docking
- Virtual Screening
- QSAR
- Computational Chemistry
- Machine Learning for Drug Discovery
This software is intended for research and educational use.
Computational predictions and molecular docking results generated by this workflow should not be interpreted as clinical, therapeutic, or experimental evidence without appropriate scientific validation.