HEDGEHOG: Hierarchical Evaluation of Drug GEnerators tHrOugh riGorous filtration.
Quick Start
HEDGEHOG is a stage-based molecular design evaluation pipeline for:
- molecule preparation
- descriptor calculation
- structural filtering
- retrosynthesis filtering
- docking
- docking pose filtering
- final reports
The full pipeline can require optional external tools and receptor inputs. Start with the safe smoke run below to verify the Python environment, bundled example molecules, descriptor calculation, and structural filters before enabling retrosynthesis or docking.
Recommended install: source checkout
git clone https://github.com/LigandPro/hedgehog.git
cd hedgehog
uv sync
This is the recommended way to run HEDGEHOG end to end. The repository checkout contains the editable configs, bundled examples, TUI sources, and the modules/ workspace used to store optional tool assets such as AiZynthFinder public data.
Requirements:
- Python 3.10+
uv- optional: Node.js >= 18 and npm for the TUI
- optional: AiZynthFinder for retrosynthesis
- optional: GNINA, SMINA, or Matcha for docking
PyPI install
python -m pip install hedgehog
hedgehog --help
Use the PyPI package only if you already manage your own config files and input paths. The default quick start, hedgehog setup ... workflows, and TUI usage are designed around a source checkout.
First safe run
uv run hedgehog --stage descriptors --stage struct_filters --force-new
This avoids docking and retrosynthesis. Use it as the first validation that the local environment, bundled examples, descriptor calculation, and structural filters are working.
Full pipeline
uv run hedgehog setup aizynthfinder
uv run hedgehog --auto-install
Full pipeline execution may require AiZynthFinder, GNINA/SMINA/Matcha, valid receptor structures, reference ligands, and enough CPU/GPU resources.
Input Format
Recommended molecule input is CSV/TSV with a smiles header:
smiles,model_name
CCO,demo
CCN,demo
c1ccccc1,demo
Required:
smiles
Optional:
model_nameornamemol_idx
If mol_idx is missing, HEDGEHOG assigns a stable ID and uses it to join stage
outputs, docking scores, and report data.
Common Commands
# Safe smoke run
uv run hedgehog --stage descriptors --stage struct_filters --force-new
# Full pipeline after optional tools are available
uv run hedgehog --auto-install
# Run with your own molecules
uv run hedgehog --mols input/my_molecules.csv
# Run a single stage
uv run hedgehog --stage descriptors
# Run multiple selected stages
uv run hedgehog --stage descriptors --stage struct_filters
# Run docking with a live progress bar
uv run hedgehog --stage docking --progress
# Run docking without progress bar (default)
uv run hedgehog --stage docking
# Regenerate report for an existing run
uv run hedgehog report results/run_10
# Show stages / version
uv run hedgehog info
uv run hedgehog version
# Launch terminal UI
uv run hedgehog tui
Progress bar behavior in CLI runs:
- Enabled: add
--progress - Disabled: omit
--progress(default)
Results
Results are written under the configured output directory, usually as an auto-numbered run folder:
results/run_N/
├── stages/
├── output/
└── report.html
Benchmark Results
Filtering pass rates by model class
Percentages are computed relative to the initial set for each model class. Unconditional and protein-based models each start from 8,000 molecules, and ligand-based models start from 6,000 molecules.
| Stage / Pass Rate | Unconditional | Ligand-based | Protein-based | |||
|---|---|---|---|---|---|---|
| #mols | % | #mols | % | #mols | % | |
| Initial | 1000.0 ± 0.0 | 100.00 ± 0.00 | 1000.0 ± 0.0 | 100.00 ± 0.00 | 1000.0 ± 0.0 | 100.00 ± 0.00 |
| Preprocessing / Init | 802.2 ± 254.4 | 80.22 ± 25.44 | 682.6 ± 349.6 | 68.26 ± 34.96 | 653.8 ± 292.8 | 65.38 ± 29.28 |
| Descriptors / Init | 660.9 ± 311.2 | 66.09 ± 31.12 | 573.4 ± 303.9 | 57.34 ± 30.39 | 481.2 ± 268.2 | 48.12 ± 26.82 |
| Structural Filters / Init | 450.0 ± 276.7 | 45.00 ± 27.67 | 342.1 ± 241.5/td> | 34.20 ± 24.15 | 276.6 ± 203.3 | 27.66 ± 20.33 |
| Synthesis Feasibility / Init | 286.5 ± 244.9 | 28.65 ± 24.49 | 58.2 ± 53.0 | 5.82 ± 5.30 | 104.1 ± 157.1 | 10.41 ± 15.71 |
| Docking / Init | 198.9 ± 162.6 | 19.89 ± 16.26 | 42.8 ± 42.0 | 4.28 ± 4.20 | 70.0 ± 95.2 | 7.00 ± 9.52 |
| 3D Filters / Init | 55.2 ± 43.1 | 5.52 ± 4.31 | 17.4 ± 22.2 | 1.74 ± 2.22 | 29.1 ± 43.0 | 2.91 ± 4.30 |
Top generators by final pass count
Best-performing generators within each model class, ranked by the number of molecules that pass the full HEDGEHOG pipeline.
| Rank | Unconditional | Ligand-based | Protein-based | |||
|---|---|---|---|---|---|---|
| Generator | Final | Generator | Final | Generator | Final | |
| 1 | REINVENT4 | 102.0 ± 5.0 | REINVENT4 (P) | 61.3 ± 11.9 | Dragonfly | 127.0 ± 18.1 |
| 2 | MoLeR | 92.7 ± 9.7 | PGMG | 24.3 ± 2.3 | DrugFlow | 58.0 ± 8.5 |
| 3 | HierGraphVAE | 91.7 ± 9.5 | MolFinder (TL) | 12.0 ± 0.0 | Pocket2Mol | 31.0 ± 11.5 |
| 4 | JT-VAE | 74.7 ± 12.0 | GCPG | 3.3 ± 1.5 | Dragonfly (b) | 9.7 ± 3.1 |
| 5 | MolGPT | 73.0 ± 6.6 | GENTRL | 3.3 ± 1.5 | ProtoBind-Diff | 6.0 ± 2.6 |
| 6 | ShEPhERD | 4.0 ± 1.0 | REINVENT4 (TL) | 0.0 ± 0.0 | DiffSBDD | 0.7 ± 1.2 |
| 7 | TGM-DLM | 3.0 ± 0.0 | — | — | TargetDiff | 0.3 ± 0.6 |
| 8 | EDM | 0.3 ± 0.6 | — | — | ResGen | 0.0 ± 0.0 |
Documentation
For full details, use the documentation instead of this README:
- Public documentation
- Introduction
- Getting Started
- CLI Reference
- TUI
- Pipeline Stages
- Configuration
- Reporting
- Advanced Topics
- TUI README
To run the docs site locally:
cd docs
pnpm install
pnpm dev
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hedgehog-1.1.44.tar.gz.
File metadata
- Download URL: hedgehog-1.1.44.tar.gz
- Upload date:
- Size: 11.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5fd225a50e32816d87fd423ea81d903fd476d7d45f81ea1bd6d40bd9fe6e6d46
|
|
| MD5 |
906ecbd1ecedcb14f05cc001611c3e8e
|
|
| BLAKE2b-256 |
ab03e3aca5813f7a692cac80d409db6384b9ef89d35f3596a9c4f728b9d52b87
|
File details
Details for the file hedgehog-1.1.44-py3-none-any.whl.
File metadata
- Download URL: hedgehog-1.1.44-py3-none-any.whl
- Upload date:
- Size: 11.9 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cf3173db10b810f7415e6c8c8bfb351537ecd4c5a87505adc8f926af274523d9
|
|
| MD5 |
6144dff7551d55d6dcba533e62bb0341
|
|
| BLAKE2b-256 |
0b53c77ee17b1657a7244abfe4fdfb38c53a9a3b25bcfb0e8a272dcded7bb547
|
