# illidanlab/mocl-dk architecture

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

- Interactive diagram: https://gitdiagram.com/illidanlab/mocl-dk
- Repository: https://github.com/illidanlab/mocl-dk

## Overview

##### Project type and purpose
- MoCL is an open-source machine-learning toolkit for graph contrastive learning on molecular data. It provides data ingestion, domain-knowledge-driven augmentation, pre-training routines (local and global contrast), and fine-tuning protocols.

##### File structure
- Top-level directories and files:
- dataset/ – stores multiple biomedical datasets in “raw” and “processed” form.
- results/ – holds pretrained model binaries (.pth), rule_indicator and sim_matrix pickles per dataset.
- Core scripts:
- pre_structure.py – builds rule_indicator and sim_matrix.
- loader.py – dataset loader, graph builder.
- splitters.py – train/val/test split logic.
- utils.py – shared utilities (logging, metrics).
- main_cl.py – contrastive pre-training entrypoint.
- main_finetune.py – fine-tuning entrypoint.
- model.py – GNN architecture and contrastive objectives.
- isostere_transformations_new.json – SMARTS-based augmentation rules.

##### Key insights from README
- Double‐contrastive loss combines local and (optionally supervised or contrastive) global objectives.
- Supports linear and non-linear fine-tuning protocols.
- Dependencies: PyTorch, PyTorch-Geometric, RDKit, tensorboardX.

##### Main components
a. Data Ingestion Layer
- Raw molecular CSV/CAN files → SMILES/graph parsing via RDKit
- Output: graph objects
b. Preprocessing & Domain Knowledge Layer
- pre_structure.py
- rule_indicator_new matrix builder (domain augmentation rules)
- sim_matrix builder (global neighbor graph)
c. Data Loader & Splitter
- loader.py (wraps PyG Data objects)
- splitters.py (train/val/test indices)
d. Augmentation Module
- Domain augmentations: DK1–DK5 rules from isostere_transformations_new.json
e. Model & Training Module
- model.py: GNN encoder + projector + contrastive loss functions
- main_cl.py: orchestrates pre-training
- Local contrast branch
- Global contrast branch (supervised or contrastive using sim_matrix)
- main_finetune.py: orchestrates fine-tuning
- Linear protocol (freeze encoder, train classifier)
- Nonlinear protocol (train all layers)
f. Persistence & Monitoring
- results/: stores pre-trained/fine-tuned model weights (.pth) and intermediate matrices (.pkl)
- tensorboardX for logging training metrics

##### Relationships and data flow
- Raw Dataset → Preprocessing → Processed graphs + rule_indicator + sim_matrix
→ Data Loader
→ Augmentation Module (two parallel streams: aug1, aug2)
→ GNN Encoder
→ Contrastive Loss Computation (local vs. global)
→ Weight updates → Persist pretrained weights to results/
→ Fine-tune with labels → Persist fine-tuned weights

##### Architectural patterns and design principles
- Pipeline pattern: clear data flow from raw ingestion to model output
- Modular separation:
- Preprocessing (stateless scripts)
- Data loading & splitting
- Augmentation (plug in new rules easily via JSON)
- Model definition and training loops
- Single-responsibility modules for ease of extension
- Reuse of PyTorch and PyG abstractions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        dataset["dataset/"]:::blue
        raw["Raw molecular files"]:::blue
        loader["loader.py"]:::blue
    end

    %% Preprocessing & Domain Knowledge
    subgraph "Preprocessing & Domain Knowledge"
        pre_structure["pre_structure.py"]:::green
        json["isostere_transformations_new.json"]:::green
        rule_matrix["rule_indicator matrix"]:::green
        sim_matrix["sim_matrix"]:::green
    end

    %% Data Loader & Splitter
    subgraph "Data Loader & Splitter"
        loader2["loader.py"]:::blue
        split["splitters.py"]:::blue
    end

    %% Augmentation Module
    subgraph "Augmentation Module"
        local["Local Augmentation Engine"]:::orange
        domain["Domain Augmentation (DK rules)"]:::orange
    end

    %% Model & Training
    subgraph "Model & Training"
        model["model.py"]:::purple
        pretrain["main_cl.py"]:::purple
        finetune["main_finetune.py"]:::purple
    end

    %% Persistence & Monitoring
    subgraph "Persistence & Monitoring"
        results["results/"]:::gray
        utils["utils.py"]:::gray
        tensorboard["tensorboardX Logging"]:::gray
    end

    %% Data Flow
    raw --> loader
    loader --> pre_structure
    pre_structure --> rule_matrix
    pre_structure --> sim_matrix
    json --> domain

    rule_matrix --> loader2
    sim_matrix --> loader2
    loader2 --> split
    split --> local
    split --> domain

    local --> model
    domain --> model
    model --> pretrain
    pretrain --> results
    pretrain --> tensorboard
    results --> finetune
    finetune --> results
    finetune --> tensorboard

    %% Click Events
    click dataset "https://github.com/illidanlab/mocl-dk/tree/master/dataset/"
    click loader "https://github.com/illidanlab/mocl-dk/blob/master/loader.py"
    click pre_structure "https://github.com/illidanlab/mocl-dk/blob/master/pre_structure.py"
    click json "https://github.com/illidanlab/mocl-dk/blob/master/isostere_transformations_new.json"
    click split "https://github.com/illidanlab/mocl-dk/blob/master/splitters.py"
    click model "https://github.com/illidanlab/mocl-dk/blob/master/model.py"
    click pretrain "https://github.com/illidanlab/mocl-dk/blob/master/main_cl.py"
    click finetune "https://github.com/illidanlab/mocl-dk/blob/master/main_finetune.py"
    click results "https://github.com/illidanlab/mocl-dk/tree/master/results/"
    click utils "https://github.com/illidanlab/mocl-dk/blob/master/utils.py"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404;
    classDef purple fill:#e2d6f3,stroke:#4b0082,color:#4b0082;
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
