# jimmyjbling/sgc-del-ml-wdr91 architecture

> Architecture diagram of the GitHub repository jimmyjbling/sgc-del-ml-wdr91, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jimmyjbling/sgc-del-ml-wdr91
- Repository: https://github.com/jimmyjbling/sgc-del-ml-wdr91

## Overview

##### Project type and purpose
- This is a command-line ML screening pipeline for small-molecule SMILES.
- It provides two main functions:
- train.py – builds fingerprint-based ensemble models and pickles them under models/
- nominate.py (screening) – loads those models to predict binder probability (“PRED”) and confidence (“CONF”) on new SMILES inputs, writing results into nominations/

##### File structure
- Top-level directories:
- models/ – serialized ensemble models (pickles) named by fingerprint sets and ensemble size
- nominations/ – output CSV and .PREDS files for screening results
- scripts/ – two entry-point scripts: train.py (model training) and nominate.py (screening)
- readme.md – high-level description of model use and confidence metric
- requirements.txt – Python dependencies (e.g., scikit-learn, RDKit)

##### README for additional insights
- Describes two screening workflows: initial (beCFP6 ensemble) and rescreening (combined fingerprints)
- Explains “PRED” vs. “CONF” and why both matter (entropy-based confidence)
- Notes that train.py also contains fingerprinting functions (chemical featurization via RDKit)

##### Components
a. Main components:
- Data Input (SMILES files or lists)
- Fingerprint Generator (module within train.py & nominate.py)
- Model Training (train.py → ensemble trainer → models/*.pkl)
- Model Storage (models directory)
- Screening Engine (nominate.py / screen_smiles function)
- Output Writer (nominations/*.csv and .PREDS)
- External Dependencies (RDKit for fingerprints, scikit-learn for modeling)
b. Relationships & interactions:
- Data Input → Fingerprint Generator → Model Training → Model Storage
- Data Input → Fingerprint Generator → Screening Engine (loads models) → Output Writer
- Both scripts read requirements.txt (implicit) and import shared fingerprinting code
c. Architectural patterns / design principles:
- Modular separation: training vs. inference
- File-based persistence (pickles and CSV outputs)
- Single-process CLI tools (no microservices or databases)
- Reuse of fingerprinting code across train.py & nominate.py
d. Key technologies / libraries:
- Python 3.x
- RDKit – chemical fingerprint generation
- scikit-learn – ensemble classifiers & confidence (entropy)
- Pickle – model serialization
- CSV/.PREDS – output formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Training Pipeline
    subgraph "Training Pipeline"
        DI["Data Input (.smi)"]:::training
        FT["Fingerprint Generator"]:::training
        MT["Model Training"]:::training
        MS["Model Storage"]:::storage
        IM["Initial Ensemble Model (.pkl)"]:::storage
        RM["Rescreening Ensemble Model (.pkl)"]:::storage
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        DI2["Data Input (.smi)"]:::inference
        FT2["Fingerprint Generator"]:::inference
        SE["Screening Engine\n(PRED & CONF)"]:::inference
        OW["Output Writer (.csv / .PREDS)"]:::storage
    end

    %% External & Documentation
    EX["External Dependencies\n(RDKit, scikit-learn)"]:::external
    DOC["High-Level Documentation"]:::doc

    %% Connections - Training
    DI -->|"reads .smi"| FT
    FT -->|"fingerprint vectors"| MT
    MT -->|"saves .pkl"| MS
    MS --> IM
    MS --> RM

    %% Connections - Inference
    DI2 -->|"reads .smi"| FT2
    FT2 -->|"fingerprint vectors"| SE
    SE -->|"writes .csv/.PREDS"| OW

    %% Dependencies & Docs links
    EX -.-> DI
    EX -.-> FT
    EX -.-> FT2
    DOC -.-> MT
    DOC -.-> SE

    %% Click Events
    click DI "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/train.py"
    click DI "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/nominate.py"
    click FT "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/train.py"
    click FT "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/nominate.py"
    click MT "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/train.py"
    click MS "https://github.com/jimmyjbling/sgc-del-ml-wdr91/tree/main/models/"
    click SE "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/scripts/nominate.py"
    click OW "https://github.com/jimmyjbling/sgc-del-ml-wdr91/tree/main/nominations/"
    click IM "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/models/WDR91_bECFP6_E5.pkl"
    click RM "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/models/WDR91_bECFP6_ECFP6_AtomPair_E5.pkl"
    click EX "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/requirements.txt"
    click DOC "https://github.com/jimmyjbling/sgc-del-ml-wdr91/blob/main/readme.md"

    %% Styles
    classDef training fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef inference fill:#ccccff,stroke:#333,stroke-width:1px;
    classDef storage fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcccc,stroke:#333,stroke-width:1px;
    classDef doc fill:#ffffcc,stroke:#333,stroke-width:1px;
```
