# drorlab/combind architecture

> Architecture diagram of the GitHub repository drorlab/combind, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drorlab/combind
- Repository: https://github.com/drorlab/combind

## Overview

##### Main Components
- Data Curation & Preparation: Show how raw structural data and ligand files enter the pipeline. Note that the README details requirements for a “structures/raw” directory (even though it isn’t in the provided tree, it is implicitly expected) and how split files (protein and ligand) are managed.
- Structural Preprocessing: Include a module for structure preparation (e.g., the “chembl” directory, which likely handles data curation for chemical structures, and “dock” for structural alignment and grid generation).
- Ligand Preparation (LigPrep): Clearly represent the ligand processing stage (this is invoked via the “combind ligprep” command).
- Docking: Represent the docking component as a dedicated module (from the “dock” directory) where the prepared ligands are docked into a protein grid.
- Scoring & Pose Prediction: Include a module for “score” where the predicted poses are compared, scored, and benchmarked.
- Visualization: Represent the “pymol” component that handles visualization and interaction analysis (often used to view complexes and poses).
- Benchmarking & Statistics: Add a separate component to indicate benchmarking and reference statistics (using data in the “stats_data” directory).

##### Relationships and Data Flow
- Move to Docking: From the preprocessing nodes, show data flows into the Docking stage (the “dock” modules) where a docking grid and docked poses are generated.
- Proceed to Scoring & Pose Prediction: From featurization, indicate that data flows into the scoring modules (score directory) which compute binding affinities and predict the best poses.
- Optional Virtual Screening (ComBindVS): Include a branch for the ComBindVS workflow where a similar but adjusted pipeline (with options like --multiplex and --screen) is applied for virtual screening.
- Finally, Visualization & Post-processing: Finally, show an optional path that flows into visualization (using pymol modules) and external Schrodinger utilities (such as glide_sort) for final analysis.

##### Architectural Patterns and Design Principles
- Pipeline-Based Modular Architecture: Emphasize that each step (curation, docking, featurization, scoring) is a separate module that can be executed individually or as part of an end-to-end pipeline.
- Command-Line Orchestration: Note that the tool is controlled via command-line instructions (“combind <subcommand> …”) which ties the modules together.
- Integration with External Tools: Highlight that external libraries and tools (Schrodinger’s Glide, Schrodinger Python API, numpy, scipy, pandas, lmdb, etc.) are essential parts of the system.
- Test and Benchmark Components: Recognize that testing (as seen in score/tests) and benchmarking (stats_data) are integral for ensuring reliability and performance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    RawData["Raw Structural Data & Ligands"]:::data
    DataCuration["Data Curation & Preparation"]:::processing

    %% Data Flow from Raw Data to Data Curation
    RawData -->|"ingest"| DataCuration

    %% Structural Preprocessing Subgraph
    subgraph "Structural Preprocessing"
        SA["Structure Alignment"]:::processing
        SP["Structure Processing"]:::processing
        SA -->|"process"| SP
    end

    %% Ligand Preparation Node
    LP["Ligand Preparation (LigPrep)"]:::processing

    %% Data Curation flows to Structural Preprocessing and Ligand Preparation
    DataCuration -->|"curates"| SA
    DataCuration -->|"extracts"| LP

    %% Docking Node: combines outputs from Structure Processing and LigPrep
    Docking["Docking"]:::processing
    SP -->|"prepared structure"| Docking
    LP -->|"prepared ligand"| Docking

    %% Optional Virtual Screening Branch
    VS["Virtual Screening (ComBindVS)"]:::processing
    Docking -.->|"optional branch"| VS
    VS -->|"screen results"| Scoring

    %% Featurization Node
    Featurization["Featurization"]:::processing
    Docking -->|"docked poses"| Featurization

    %% Scoring & Pose Prediction Node
    Scoring["Scoring & Pose Prediction"]:::processing
    Featurization -->|"features computed"| Scoring

    %% Visualization and Benchmarking Nodes from Scoring
    Visualization["Visualization (PyMOL)"]:::external
    Benchmarking["Benchmarking & Statistics"]:::external
    Scoring -->|"pose evaluation"| Visualization
    Scoring -->|"benchmark data"| Benchmarking

    %% Click Events
    click DataCuration "https://github.com/drorlab/combind/tree/main/chembl/"
    click SA "https://github.com/drorlab/combind/blob/main/dock/struct_align.py"
    click SP "https://github.com/drorlab/combind/blob/main/dock/struct_process.py"
    click LP "https://github.com/drorlab/combind/blob/main/dock/ligprep.py"
    click Docking "https://github.com/drorlab/combind/tree/main/dock/"
    click Featurization "https://github.com/drorlab/combind/tree/main/features/"
    click Scoring "https://github.com/drorlab/combind/tree/main/score/"
    click Visualization "https://github.com/drorlab/combind/tree/main/pymol/"
    click Benchmarking "https://github.com/drorlab/combind/tree/main/stats_data/"

    %% Styles
    classDef data fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef processing fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
