Pipeline Overview

HEDGEHOG implements a sequential molecular filtering pipeline that progressively narrows a large set of generated molecules down to high-quality drug candidates. Each stage applies domain-specific filters, and only molecules that pass all enabled stages reach the final output.

Pipeline Stages

Retention rates are approximate and depend heavily on the input molecule set and configuration thresholds.

#	Stage	Purpose	Typical Retention
1	Preprocessing	Standardize molecules; remove salts/fragments; preserve charge and stereo by default	70—95%
2	Descriptors	Compute physicochemical descriptors and filter by threshold ranges	25—40%
3	Structural Filters	Calculate liability diagnostics; enforce the configured hard gate (default: PAINS + NIBR + Lilly160 + MolGraph + protecting groups + undefined stereo)	15—30%
4	Synthesis Feasibility	Evaluate synthetic accessibility scores and optional AiZynthFinder retrosynthesis	35—60%
5	Molecular Docking	Dock surviving molecules into the target protein binding site	50—75%
6	Three-Dimensional Filters	Filter poses by search-box containment, clashes, interactions, and conformer deviation	35—60%
7’	Final Descriptors	Recompute descriptors on the final molecule set for reporting	100% (no filtering)

Data Flow


input/sampled_molecules.csv
        |
        v
 [Stage 1: Mol Prep]
        |  filtered_molecules.csv
        v
 [Stage 2: Descriptors]
        |  filtered_molecules.csv
        v
 [Stage 3: Structural Filters]
        |  filtered_molecules.csv
        v
 [Stage 4: Synthesis Analysis]
        |  filtered_molecules.csv
        v
 [Stage 5: Molecular Docking]
        |  gnina/gnina_out.sdf, smina/smina_out.sdf, matcha/matcha_out.sdf
        v
 [Stage 6: Docking Filters]
        |  filtered_molecules.csv
        v
 [Stage 7': Final Descriptors]
        |
        v
 output/final_molecules.csv

Sequential Filtering Approach

The pipeline is designed as a funnel: cheap, fast filters run first (descriptors, structural alerts), and expensive operations (retrosynthesis, docking) run later on a smaller molecule set. This ordering minimizes computational cost while maximizing coverage.

Any stage can be requested with --stage <name>, which is useful for debugging or re-running a single step. Only the selected stages run; Mol Prep is not forced automatically. Include --stage mol_prep if you want standardization first. All configuration files are snapshotted into a configs/ directory at the start of each run, and a RUN_INFO.md is generated at completion.

Every stage config includes a run: true/false flag that controls whether it executes. See the Configuration Reference for full details.

output/final_molecules.csv is the final filtered output file.

.RUN_INCOMPLETE is a transient marker file written at the start of a run. It is removed on successful completion. If it remains in the run folder, the pipeline was interrupted or failed and the run log should be reviewed.

Stage Dependencies

Stage	Needs	Reads From by Default	Writes
`mol_prep`	Raw molecule table	`generated_mols_path` or sampled input	`stages/01_mol_prep/filtered_molecules.csv`
`descriptors`	Molecule table	preprocessing output, sampled input	`stages/02_descriptors_initial/metrics/` and `stages/02_descriptors_initial/filtered_molecules.csv`
`struct_filters`	Descriptor or molecule table	Descriptors output, then preprocessing or sample fallback	`stages/03_structural_filters_post/filtered_molecules.csv`
`synthesis`	Molecule table	Structural filters, descriptors, preprocessing output, or sampled input	`stages/04_synthesis/filtered_molecules.csv`
`docking`	Molecules plus receptor or reference ligand	Latest usable filtered table	`stages/05_docking/{tool}/{tool}_out.sdf`
`docking_filters`	Docking poses	`stages/05_docking/...`	`stages/06_docking_filters/filtered_molecules.csv`
`final_descriptors`	Final survivor table	Docking filters or latest usable filtered table	`stages/07_descriptors_final/...`

Stage Configuration

Each stage has its own YAML configuration file referenced from the master config.yml:


config_mol_prep: src/hedgehog/configs/config_mol_prep.yml
config_descriptors: src/hedgehog/configs/config_descriptors.yml
config_structFilters: src/hedgehog/configs/config_structFilters.yml
config_synthesis: src/hedgehog/configs/config_synthesis.yml
config_docking: src/hedgehog/configs/config_docking.yml
config_docking_filters: src/hedgehog/configs/config_docking_filters.yml
config_moleval: src/hedgehog/configs/config_moleval.yml
config_weighted_score: src/hedgehog/configs/config_weighted_score.yml