How illidanlab/mocl-dk works
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