Three-Dimensional Filters

The docking filters stage applies a cascade of quality checks to docked poses, removing those with steric clashes, implausible geometries, or missing key interactions. It then deduplicates poses to produce a list of unique molecules.

Filter Cascade

When the aggregation mode is all (default), the search-box filter can short-circuit evaluation: poses that fail it skip all subsequent filters.

Filter 1: Search-Box Containment

Verifies that the docked pose lies within the configured docking search box. This catches poses that drifted outside the binding site during optimization.

The search box is resolved from the docking configuration: either explicit center/size coordinates, or computed from autobox_ligand + autobox_add (the same reference ligand used for docking).

Filter 2: Pose Quality

Fast pose-quality check from LigandPro/posecheck-fast  for protein-ligand clashes, volume overlap, and protein distance. The legacy optional backend is posecheck, which exposes strain-energy parameters.

Clashes indicate that the ligand overlaps with protein atoms in a physically impossible way. High strain energy means the ligand is in an energetically unfavorable conformation.

Filter 3: Interaction Analysis (ProLIF)

Uses ProLIF  to compute a protein-ligand interaction fingerprint and check for required/forbidden contacts.

This filter is especially useful when you know the binding mode should involve specific residues (e.g., a catalytic aspartate) or should avoid certain contacts (e.g., a cysteine that causes covalent binding).

Residue identifiers are matched against ProLIF interaction column labels. Depending on your prepared receptor and ProLIF naming, identifiers may look different, e.g., ["SER45"], or ["SER:45"] so inspect the generated interaction report before finalizing required_residues.

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

Compares the 3D molecular shape of each pose to a reference ligand using Gaussian overlap Tanimoto.

This filter is disabled by default because it requires a known reference ligand for comparison. Enable it when you have a co-crystallized ligand or known active compound and want to ensure poses adopt a similar shape. For reproducible setup, install an isolated worker environment:

uv run hedgehog setup shepherd-worker --yes

If no Shepherd backend is available at runtime, HEDGEHOG soft-skips this filter (logs a warning and marks pass_shepherd_score=true).

Filter 5: Conformer Deviation

Checks if the docked pose is geometrically plausible by generating multiple low-energy conformers and measuring the RMSD between the docked pose and the closest conformer.

A high minimum RMSD indicates that the docking engine placed the ligand in a conformation that is energetically unlikely for the molecule to adopt in solution. This catches docking artifacts where the scoring function found a favorable protein-ligand interaction at the cost of internal strain. For isolated setup of optional nvMolKit dependencies:

uv run hedgehog setup nvmolkit-worker

Output Files

For each tool, values are taken from the best pose per molecule (minimum affinity).

Usage

# Run docking filters as part of the full pipeline
uv run hedgehog
 
# Run docking filters stage only (requires docking output to exist)
uv run hedgehog --stage docking_filters
 
# Short alias
uv run hedge --stage docking_filters