Three-Dimensional Filters

Stage 6 applies a cascade of pose quality checks, then deduplicates to unique molecules. When inputs are SDF, model-provided coordinates are the primary pose source.

Coordinate Sources

For SDF model inputs, HEDGEHOG preserves original coordinates in input/ligands.sdf, intersects their mol_idx values with the latest completed upstream stage, and evaluates those poses in the main Stage 6 output.

Set evaluate_docked_coordinates: true in the master config or pass --evaluate-docked-coordinates to also evaluate docking output under stages/06_docking_filters/docked/. That option requires docking.run: true and at least one selected docking tool.

Every pose-level table and SDF carries pose_source as input or docked. At molecule level, the two branches use pass-if-either semantics; a molecule that passes both is marked input+docked in the root filtered_molecules.csv. For non-SDF inputs, docking output remains the available primary coordinate source.

Filter Cascade

When aggregation.mode is all (default), early filters can short-circuit: poses that fail skip later heavy filters.

Checks that the pose lies inside the docking search box.

Parameter	Default	Description
`enabled`	`true`	Enable this filter
`max_outside_fraction`	`0.0`	Maximum fraction of atoms allowed outside the box
`short_circuit`	`true`	Skip later filters on fail when `mode` is `all`

The box comes from docking config: explicit center/size, or autobox_ligand + autobox_add.

Filter 2: Pose Quality (posecheck-fast)

Fast intermolecular checks from LigandPro/posecheck-fast : clash, volume overlap, and protein distance.

Parameter	Default	Description
`enabled`	`true`	Enable this filter
`clash_cutoff`	`0.75`	Relative VDW distance cutoff for clash detection
`volume_clash_cutoff`	`0.075`	ShapeTverskyIndex overlap threshold
`max_distance`	`5.0`	Maximum minimum ligand–protein distance (Å)
`short_circuit`	`true`	Skip later filters on fail when `mode` is `all`

Legacy PoseCheck keys such as strain_forcefield and clash_tolerance are not used. This stage runs posecheck-fast only.

Filter 3: Interaction Analysis (ProLIF)

Uses ProLIF interaction fingerprints.

Parameter	Default	Description
`enabled`	`true`	Enable this filter
`reference_ligand`	`null`	SDF path for fingerprint similarity; required when `similarity_threshold` > 0
`min_hbonds`	`0`	Minimum hydrogen bonds required
`required_residues`	`[]`	Residues that must have at least one interaction
`forbidden_residues`	`[]`	Residues that must not interact
`interaction_types`	`[HBDonor, HBAcceptor, Hydrophobic, VdWContact]`	Interaction types to detect
`reporting.enabled`	`true`	Write interaction reporting artifacts
`similarity_threshold`	`0.0`	Tanimoto to the reference ProLIF fingerprint (`0` disables similarity)

similarity_threshold and reference_ligand are a pair:

similarity_threshold: 0.0 — similarity check off.
similarity_threshold > 0 with a valid SDF — Tanimoto is computed on ProLIF bits vs the reference.
similarity_threshold > 0 without reference_ligand — warning only; the similarity gate does not filter.

Residue identifiers must match ProLIF column labels for your prepared receptor (for example SER45 or SER:45). Inspect the interaction report before locking required_residues.

Filter 4: Shepherd-Score (3D Shape Similarity)

Gaussian-overlap shape Tanimoto vs a reference ligand.

Parameter	Default	Description
`enabled`	`false`	Requires a reference ligand
`backend`	`auto`	`auto` = worker → in-process → soft-skip; `worker`; `inprocess`
`auto_install_worker`	`true`	Auto-install `.venv-shepherd-worker` when missing
`worker_python`	`null`	Optional interpreter for auto-install
`reference_ligand`	`null`	Path to reference ligand SDF
`min_shape_score`	`0.5`	Minimum shape Tanimoto
`alpha`	`0.81`	Gaussian width
`align_before_scoring`	`true`	Align each pose onto the reference with RDKit `AlignMol` / `GetBestRMS` before scoring; `false` scores unaligned coordinates

If no Shepherd backend is available, HEDGEHOG soft-skips this filter (warning; pass_shepherd_score=true).


uv run hedgehog setup shepherd-worker --yes

Filter 5: Conformer Deviation

Generates ETKDG conformers and measures RMSD to the evaluated pose.

Parameter	Default	Description
`enabled`	`true`	Enable this filter
`use_nvmolkit`	`true`	Prefer nvMolKit when available; fall back to RDKit
`backend`	`symmetry_rmsd`	`symmetry_rmsd` or `naive`
`num_conformers`	`50`	Number of conformers
`conformer_method`	`ETKDGv3`	`ETKDG`, `ETKDGv2`, or `ETKDGv3`
`max_rmsd_to_conformer`	`3.0`	Maximum RMSD (Å) to the closest conformer
`random_seed`	`42`	Conformer seed
`include_hydrogens`	`false`	Include hydrogens in RMSD matching
`max_matches`	`10000`	Cap for `GetBestRMS` symmetry matching
`early_stop_on_pass`	`true`	Stop once any conformer passes
`optimize_conformers`	`false`	UFF-relax generated ETKDG conformers before RMSD, not the docked pose. Failed UFF steps are skipped; they are not fatal

High minimum RMSD means the pose is far from accessible low-energy conformers.


uv run hedgehog setup nvmolkit-worker

Output Files

File	Description
`filtered_molecules.csv`	Unique molecules (best pose per molecule) passing filters
`filtered_poses.csv`	All passing poses with metrics
`filtered_poses.sdf`	Passing poses as SDF
`metrics.csv`	Per-pose metrics for the primary coordinate branch
`docked/`	Optional docked-coordinate artifacts

After filtering, poses are sorted by affinity and deduplicated to one best pose per mol_idx. SMILES are taken from the original ligand table, not regenerated from 3D.

Usage


uv run hedgehog
uv run hedgehog --stage docking_filters --mols input/generated_3d.sdf
uv run hedgehog --mols input/generated_3d.sdf --evaluate-docked-coordinates
uv run hedge --stage docking_filters