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 and remove salts/fragments/charges/stereochemistry; canonicalize tautomers	70—95%
2	Descriptors	Compute 28 physicochemical descriptors and filter by threshold ranges	25—40%
3	Structural Filters	Apply medicinal chemistry alerts, complexity checks, and structural rules	15—30%
4	Synthesis Feasibility	Evaluate synthetic accessibility (SA, SYBA, RA scores) and retrosynthesis feasibility	35—60%
5	Molecular Docking	Dock surviving molecules into the target protein binding site	50—75%
6	Three-Dimensional Filters	Filter docked 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/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. When you request any stage other than mol_prep, HEDGEHOG still run mol_prep first, so downstream stages operate on standardized molecules. 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 `filtered/filtered_molecules.csv`
`struct_filters`	Descriptor or molecule table	Descriptors output, then prerpocessing 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