# ieumseo/vdm-lookup architecture

> Architecture diagram of the GitHub repository ieumseo/vdm-lookup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ieumseo/vdm-lookup
- Repository: https://github.com/ieumseo/vdm-lookup

## Overview

#### 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`.

Main entry points: [`src/vdmlookup/ligand_preparation.py`](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_preparation.py) (Ligand preparation), [`src/vdmlookup/cluster_export.py`](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cluster_export.py) (Cluster export CLI), [`src/vdmlookup/pdb_io.py`](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/pdb_io.py) (PDB structure I/O), [`src/vdmlookup/ligand_cg.py`](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_cg.py) (Ligand CG matcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_pyproject["Package entry points<br/>Python packaging<br/>[pyproject.toml]"]
  node_cli["Lookup CLI<br/>Python CLI<br/>[cli.py]"]
  node_cluster_export["Cluster export CLI<br/>Python workflow<br/>[cluster_export.py]"]
end

subgraph group_prepare["Structure preparation"]
  node_pdb_io["PDB structure I/O<br/>structure boundary<br/>[pdb_io.py]"]
  node_ligand_prep["Ligand preparation<br/>normalization"]
  node_ccd["CCD resolution<br/>chemical definitions<br/>[ccd.py]"]
end

subgraph group_contacts["Contact and CG pipeline"]
  node_probe_runner["Probe runner<br/>subprocess adapter<br/>[probe_runner.py]"]
  node_probe_parser["Probe output parser<br/>[probe_parser.py]"]
  node_contacts_model["Normalized contacts<br/>contact records<br/>[contacts.py]"]
  node_cg_defs["CG definitions<br/>shared dictionaries<br/>[cg_dicts.py]"]
  node_ligand_cg["Ligand CG matcher<br/>substructure matching<br/>[ligand_cg.py]"]
  node_features["Structural context<br/>residue features"]
  node_candidates["Lookup candidates<br/>candidate assembly"]
end

subgraph group_matching["Database matching"]
  node_cluster_match["Cluster matcher and scorer<br/>parquet matching<br/>[cluster_match.py]"]
  node_geometry["Geometry alignment<br/>Kabsch geometry<br/>[geometry.py]"]
  node_pymol_pdb["Cluster multi-model PDB<br/>export artifact"]
end

subgraph group_external["External dependencies"]
  node_ccd_service[("RCSB CCD and cache<br/>external service")]
  node_probe_build["Probe build script<br/>[build_probe.sh]"]
  node_probe{{"Probe executable<br/>subprocess"}}
  node_vdm_db[("External vdM parquet DB<br/>read-only database")]
end

node_pyproject -->|"registers"| node_cli
node_pyproject -->|"registers"| node_cluster_export
node_cli -->|"reads input"| node_pdb_io
node_pdb_io -->|"structures"| node_ligand_prep
node_ligand_prep -->|"resolves ligands"| node_ccd
node_ccd -->|"fetches/caches"| node_ccd_service
node_ligand_prep -->|"prepared structure"| node_probe_runner
node_probe_build -->|"builds"| node_probe
node_probe_runner -->|"invokes"| node_probe
node_probe -->|"contact output"| node_probe_parser
node_probe_parser -->|"normalizes"| node_contacts_model
node_ligand_prep -->|"prepared ligands"| node_ligand_cg
node_cg_defs -->|"templates"| node_ligand_cg
node_pdb_io -->|"residue structure"| node_features
node_contacts_model -->|"raw contacts"| node_candidates
node_ligand_cg -->|"virtual CGs"| node_candidates
node_features -->|"context"| node_candidates
node_cg_defs -->|"protein CGs"| node_candidates
node_candidates -->|"valid pairs"| node_cluster_match
node_geometry -->|"alignment"| node_cluster_match
node_vdm_db -->|"cluster parquet"| node_cluster_match
node_cluster_export -->|"reads cluster"| node_vdm_db
node_cluster_export -->|"exports"| node_pymol_pdb

click node_pyproject "https://github.com/ieumseo/vdm-lookup/blob/main/pyproject.toml"
click node_cli "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cli.py"
click node_cluster_export "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cluster_export.py"
click node_pdb_io "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/pdb_io.py"
click node_ligand_prep "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_preparation.py"
click node_ccd "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ccd.py"
click node_probe_build "https://github.com/ieumseo/vdm-lookup/blob/main/scripts/build_probe.sh"
click node_probe_runner "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/probe_runner.py"
click node_probe_parser "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/probe_parser.py"
click node_contacts_model "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/contacts.py"
click node_cg_defs "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cg_dicts.py"
click node_ligand_cg "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_cg.py"
click node_features "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/structure_features.py"
click node_cluster_match "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cluster_match.py"
click node_geometry "https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/geometry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pyproject,node_cli,node_cluster_export toneBlue
class node_pdb_io,node_ligand_prep,node_ccd toneAmber
class node_probe_runner,node_probe_parser,node_contacts_model,node_cg_defs,node_ligand_cg,node_features,node_candidates toneMint
class node_cluster_match,node_geometry,node_pymol_pdb toneRose
class node_ccd_service,node_probe_build,node_probe,node_vdm_db toneIndigo
```

## Components

### Entry points

- [Package entry points](https://github.com/ieumseo/vdm-lookup/blob/main/pyproject.toml): Python packaging · Defines console commands and package metadata. · `pyproject.toml`
- [Lookup CLI](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cli.py): Python CLI · Orchestrates the primary lookup workflow. · `src/vdmlookup/cli.py`
- [Cluster export CLI](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cluster_export.py): Python workflow · Exports one stored cluster as multi-model PDB. · `src/vdmlookup/cluster_export.py`

### Structure preparation

- [PDB structure I/O](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/pdb_io.py): structure boundary · `src/vdmlookup/pdb_io.py`
- [Ligand preparation](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_preparation.py): normalization · Prepares every nonstandard HETATM ligand. · `src/vdmlookup/ligand_preparation.py`
- [CCD resolution](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ccd.py): chemical definitions · Retrieves or caches required CCD definitions; failures stop preparation. · `src/vdmlookup/ccd.py`

### Contact and CG pipeline

- [Probe runner](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/probe_runner.py): subprocess adapter · `src/vdmlookup/probe_runner.py`
- [Probe output parser](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/probe_parser.py): parser · `src/vdmlookup/probe_parser.py`
- [Normalized contacts](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/contacts.py): contact records · `src/vdmlookup/contacts.py`
- [CG definitions](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cg_dicts.py): shared dictionaries · Protein chemical-group definitions and templates. · `src/vdmlookup/cg_dicts.py`
- [Ligand CG matcher](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/ligand_cg.py): substructure matching · Creates canonical virtual CG residues while retaining ligand origin. · `src/vdmlookup/ligand_cg.py`
- [Structural context](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/structure_features.py): residue features · Derives backbone and ABPLE-related context. · `src/vdmlookup/structure_features.py`
- **Lookup candidates**: candidate assembly · Valid contact-residue/CG pairs filtered for database lookup.

### Database matching

- [Cluster matcher and scorer](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/cluster_match.py): parquet matching · Aligns candidates to centroids and emits match distances and C-scores. · `src/vdmlookup/cluster_match.py`
- [Geometry alignment](https://github.com/ieumseo/vdm-lookup/blob/main/src/vdmlookup/geometry.py): Kabsch geometry · `src/vdmlookup/geometry.py`
- **Cluster multi-model PDB**: export artifact · PyMOL-ready cluster-member export.

### External dependencies

- **RCSB CCD and cache**: external service · CCD records are downloaded and cached outside the repository.
- [Probe build script](https://github.com/ieumseo/vdm-lookup/blob/main/scripts/build_probe.sh): build script · `scripts/build_probe.sh`
- **Probe executable**: subprocess · Performs geometric atomic contact detection.
- **External vdM parquet DB**: read-only database · User-supplied CG and contact-residue-specific cluster data.

## Connections

- Package entry points → Lookup CLI: registers
- Package entry points → Cluster export CLI: registers
- Lookup CLI → PDB structure I/O: reads input
- PDB structure I/O → Ligand preparation: structures
- Ligand preparation → CCD resolution: resolves ligands
- CCD resolution → RCSB CCD and cache: fetches/caches
- Ligand preparation → Probe runner: prepared structure
- Probe build script → Probe executable: builds
- Probe runner → Probe executable: invokes
- Probe executable → Probe output parser: contact output
- Probe output parser → Normalized contacts: normalizes
- Ligand preparation → Ligand CG matcher: prepared ligands
- CG definitions → Ligand CG matcher: templates
- PDB structure I/O → Structural context: residue structure
- Normalized contacts → Lookup candidates: raw contacts
- Ligand CG matcher → Lookup candidates: virtual CGs
- Structural context → Lookup candidates: context
- CG definitions → Lookup candidates: protein CGs
- Lookup candidates → Cluster matcher and scorer: valid pairs
- Geometry alignment → Cluster matcher and scorer: alignment
- External vdM parquet DB → Cluster matcher and scorer: cluster parquet
- Cluster export CLI → External vdM parquet DB: reads cluster
- Cluster export CLI → Cluster multi-model PDB: exports