ieumseo/vdm-lookup

Purpose and Entry Points

vdmlookup is a Python CLI for finding atomic contacts in a PDB structure, mapping them to COMBS-compatible chemical-group (CG) interactions, and scoring them against an external read-only vdM parquet database. Primary commands are implemented in src/vdmlookup/cli.py; package metadata and console entry points are defined by pyproject.toml. A separate cluster-export workflow is provided by src/vdmlookup/cluster_export.py.

Input Preparation and PDB Boundary

The lookup pipeline begins with PDB parsing and ligand normalization. src/vdmlookup/pdb_io.py owns structure I/O, while src/vdmlookup/ligand_preparation.py prepares every nonstandard HETATM ligand before contact detection. It resolves CCD definitions through src/vdmlookup/ccd.py, retrieves/cache CCD records from RCSB, and uses RDKit to add explicit ligand hydrogens. Failure to retrieve chemical definitions is a hard boundary rather than guessing chemistry.

Contact Detection via Probe

Prepared structures are passed to the external Probe binary through src/vdmlookup/probe_runner.py; its output is decoded by src/vdmlookup/probe_parser.py and normalized into contact records by src/vdmlookup/contacts.py. Probe is built separately by scripts/build_probe.sh and expected under vendor/probe/probe. This subprocess boundary isolates geometric contact detection from the Python matching pipeline.

CG Identification and Virtual Ligands

Protein CG candidates are driven by shared CG dictionaries and definitions in src/vdmlookup/cg_dicts.py and src/vdmlookup/cg_definitions.json. Ligand substructure matching is implemented in src/vdmlookup/ligand_cg.py: it applies graph templates, bond connectivity, and hydrogen-gating constraints to prepared ligands. Matching ligand fragments become virtual CG residues with canonical amino-acid-style atom naming, allowing protein and ligand candidates to enter the same downstream matcher while preserving origin and restoring original ligand identifiers in output.

Structural Context and Candidate Assembly

src/vdmlookup/structure_features.py derives residue-level structural context, including backbone and ABPLE-related features needed for context-specific scoring. Candidate construction combines Probe contacts, residue/CG identity, target filters, and CG mappings. Shared constants and geometry-facing conventions reside in src/vdmlookup/constants.py and src/vdmlookup/geometry.py. The critical boundary here is between raw atom contacts and valid (contact residue, CG residue) lookup candidates.

Cluster Matching and Scoring

src/vdmlookup/cluster_match.py reads CG- and contact-residue-specific parquet data from the user-supplied vdM database. It aligns observed candidate coordinates to stored cluster centroids using Kabsch-style geometry from src/vdmlookup/geometry.py, selects exact or nearest cluster matches, and emits RMSD/max-distance plus C-score variants. The database is not bundled or mutated; its required directory structure is an external runtime dependency.

Cluster Inspection Export

src/vdmlookup/cluster_export.py independently reads the same vdM parquet database and exports all members of a requested cluster as a multi-model PDB for PyMOL. This path uses lookup result identifiers (CG_type, contact residue name, cluster number) but does not require the original input structure or rerun matching.

Runtime and External Dependencies

The main runtime is Python with NumPy/Pandas and no ProDy dependency. Material external services are RCSB CCD download (files.rcsb.org, cached under a platform/user cache directory or VDMLOOKUP_CACHE_DIR), RDKit and gemmi for ligand preparation, the locally built Probe executable, and the externally supplied vdM parquet database. Reference-validation support is isolated in scripts/validate_against_combs.py.