How omicsml/focus works
Project type and purpose
• This is a specialized machine‐learning research framework for Graph Contrastive Learning on subcellular‐resolution spatial transcriptomics data. It ingests raw spatial transcriptomics files, constructs cell‐neighborhood graphs, and trains contrastive graph neural networks to improve cell‐type annotation.
File structure
• Top‐level:
• dataset/ – raw CSV and mapping files (external data)
• focus/ – core library, subdivided into:
· data/ – graph‐building and preprocessing scripts
· dataloader/ – PyTorch Dataset and DataLoader utilities
· model/ – model definitions, layers, losses, encoder, view (contrast) generator
· module/ – higher‐level wrapper modules for encoder & view generator
· preprocess/ – auxiliary gene‐mapping scripts
· task/ – downstream task scripts (cell‐type classification)
· train/ – training plans and orchestration
· utils/ – generic utilities
• run_all.py – entry point for distributed training
• README.md – project overview and instructions
Extract architecture hints from the README
• Preprocessing stage: KNN‐based graph construction and dataset splitting
• Training stage: multi‐GPU launch via torchrun calling run_all.py
• Dependencies: PyTorch, PyTorch‐Geometric, NetworkX, scikit‐learn
Main components
a. Raw Data Layer
– dataset/ CSV and mapping.json (CosMx, MERFISH, Xenium files)
b. Preprocessing Pipeline
– focus/preprocess/map_genes.py
– focus/data/knn_data_*.py
– focus/data/build_graph_datasets_*.py
– focus/data/preprocess/_knn_radius_graph.py
c. Dataset & DataLoader
– focus/data/data_process.py (graph‐structured data objects)
– focus/dataloader/_focus_datasets.py
– focus/dataloader/_datacollator.py & utils
d. Model Definition
– focus/model/graph_encoder.py
– focus/model/view_generator.py
– focus/model/layers.py, losses.py, GCN_adj.py, ResGCN.py
e. Contrastive Module Wrappers
– focus/module/_encoder_module.py
– focus/module/_view_generator.py
– focus/module/nets/*.py (GAT, GCN, SimCLR, MLP variants)
f. Task & Training Orchestration
– focus/task/celltype_classfication.py (evaluation)
– focus/train/trainingplans.py & view_graph_trainplan.py
– run_all.py (distributed training launcher)
g. Utilities & External Dependencies
– PyTorch, PyG, NetworkX, scikit‐learn, torch‐scatter, torch‐sparse, torch‐cluster
Relationships & data flows
• Raw Data → Preprocessing Scripts → Graph‐structured Dataset Files
• Graph Data Files → DataLoader (collation, batching) → PyTorch DataLoader
• DataLoader → Contrastive Model Module (encoder + view generator)
• Model Module → Loss functions (contrastive loss) → Trainer
• Trainer & TrainingPlans → run_all.py → multi‐GPU job
• Trained Model → Task script → cell‐type predictions & metrics
Architectural patterns & design principles
• Pipeline separation: raw data, preprocessing, dataset, dataloader, model, training
• Module encapsulation: low‐level tensor ops in focus/model; high‐level training logic in focus/module & focus/train
• Plug‐and‐play: nets folder contains interchangeable GNN backbones (GAT, GCN, ResGCN, DenseGINConv)
• Single entry point for experiments (run_all.py)