# omicsml/focus architecture

> Architecture diagram of the GitHub repository omicsml/focus, 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/omicsml/focus
- Repository: https://github.com/omicsml/focus

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Raw Data Layer
    subgraph "Raw Data Layer"
        direction TB
        RawCSV1(("dataset/kidney_annot_3D_tx_100.csv")):::data
        RawMap(("dataset/mapping.json")):::data
        RawDir(["dataset/"]):::data
    end

    %% Preprocessing Pipeline
    subgraph "Preprocessing Pipeline" 
        direction TB
        MapGenes["map_genes.py"]:::data
        KNNCosKidney["knn_data_cosmx_kidney.py"]:::data
        KNNCosLung["knn_data_cosmx_lung.py"]:::data
        BuildKidney["build_graph_datasets_kidney.py"]:::data
        KNRG["knn_radius_graph.py"]:::data
        KNRGPreproc["_knn_radius_graph.py"]:::data
    end

    %% Dataset & DataLoader
    subgraph "Dataset & DataLoader"
        direction TB
        DataProcess["data_process.py"]:::dataset
        FocusDatasets["_focus_datasets.py"]:::dataset
        DataCollator["_datacollator.py"]:::dataset
        DataLoaderFile["_dataloader.py"]:::dataset
        DLUtils["utils.py"]:::dataset
    end

    %% Model Definition & Modules
    subgraph "Model & Modules"
        direction TB
        subgraph "Model Definition"
            direction TB
            GraphEnc["graph_encoder.py"]:::model
            ViewGen["view_generator.py"]:::model
            Layers["layers.py"]:::model
            Losses["losses.py"]:::model
            GCNAdj["GCN_adj.py"]:::model
            ResGCN["ResGCN.py"]:::model
            BaseModel["_base_model.py"]:::model
        end
        subgraph "Contrastive Module Wrappers"
            direction TB
            EncModule["_encoder_module.py"]:::model
            ViewModule["_view_generator.py"]:::model
            subgraph "Nets"
                direction TB
                Gat["_gat.py"]:::model
                GCNAdjNet["_gcnadj.py"]:::model
                ResGcnNet["_resgcn.py"]:::model
                DenseGin["_denseginconv.py"]:::model
                MLP["_mlp.py"]:::model
                SimCLR["_simclr.py"]:::model
                GraphConv["_graphconvolution.py"]:::model
            end
        end
    end

    %% Training & Task
    subgraph "Training & Task" 
        direction TB
        CellType["celltype_classfication.py"]:::train
        TrainPlans["trainingplans.py"]:::train
        ViewPlan["view_graph_trainplan.py"]:::train
        RunAll["run_all.py"]:::train
    end

    %% Utilities & Constants
    subgraph "Utilities & Constants"
        direction TB
        UtilsAll["utils.py"]:::util
        Const["_constants.py"]:::util
        ModelUtils["focus/model/utils.py"]:::util
        ModuleUtils["focus/module/utils.py"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch(("PyTorch")):::external
        PyG(("PyTorch-Geometric")):::external
        NX(("NetworkX")):::external
        SKL(("scikit-learn")):::external
        TS(("torch-scatter/sparse/cluster")):::external
    end

    %% Data Flows
    RawDir -->|"contains"| RawCSV1
    RawDir --> RawMap
    RawCSV1 -->|construct KNN graph| KNNCosKidney
    RawCSV1 -->|construct KNN graph| KNNCosLung
    RawMap --> MapGenes
    KNNCosKidney --> BuildKidney
    KNNCosLung --> BuildKidney
    KNRG --> KNRGPreproc
    BuildKidney --> DataProcess
    DataProcess --> FocusDatasets
    FocusDatasets --> DataCollator
    DataCollator --> DataLoaderFile
    DataLoaderFile --> ViewEncFlow["Contrastive Model Module"]
    ViewEncFlow --> EncModule
    ViewEncFlow --> ViewModule
    EncModule --> GraphEnc
    ViewModule --> ViewGen
    GraphEnc --> Layers
    GraphEnc --> BaseModel
    Layers --> Losses
    ViewGen --> Losses
    Losses --> TrainPlans
    TrainPlans --> ViewPlan
    ViewPlan --> RunAll
    RunAll -->|launch via torchrun| PyTorch

    %% Dependencies
    EncModule -.-> GraphEnc
    ViewModule -.-> ViewGen
    Gat -.-> EncModule
    GCNAdjNet -.-> EncModule
    ResGcnNet -.-> EncModule
    DenseGin -.-> EncModule
    MLP -.-> EncModule
    SimCLR -.-> EncModule
    GraphConv -.-> EncModule

    %% External Links
    GraphEnc -->|uses| PyG
    ViewGen -->|uses| PyG
    TrainPlans -->|requires| NX
    TrainPlans -->|requires| SKL
    TrainPlans -->|requires| TS

    %% Click Events
    click RawDir "https://github.com/omicsml/focus/tree/main/dataset/"
    click RawCSV1 "https://github.com/omicsml/focus/blob/main/dataset/kidney_annot_3D_tx_100.csv"
    click RawMap "https://github.com/omicsml/focus/blob/main/dataset/mapping.json"
    click MapGenes "https://github.com/omicsml/focus/blob/main/focus/preprocess/map_genes.py"
    click KNNCosKidney "https://github.com/omicsml/focus/blob/main/focus/data/knn_data_cosmx_kidney.py"
    click KNNCosLung "https://github.com/omicsml/focus/blob/main/focus/data/knn_data_cosmx_lung.py"
    click BuildKidney "https://github.com/omicsml/focus/blob/main/focus/data/build_graph_datasets_kidney.py"
    click KNRG "https://github.com/omicsml/focus/blob/main/focus/data/knn_radius_graph.py"
    click KNRGPreproc "https://github.com/omicsml/focus/blob/main/focus/data/preprocess/_knn_radius_graph.py"
    click DataProcess "https://github.com/omicsml/focus/blob/main/focus/data/data_process.py"
    click FocusDatasets "https://github.com/omicsml/focus/blob/main/focus/dataloader/_focus_datasets.py"
    click DataCollator "https://github.com/omicsml/focus/blob/main/focus/dataloader/_datacollator.py"
    click DataLoaderFile "https://github.com/omicsml/focus/blob/main/focus/dataloader/_dataloader.py"
    click DLUtils "https://github.com/omicsml/focus/blob/main/focus/dataloader/utils.py"
    click GraphEnc "https://github.com/omicsml/focus/blob/main/focus/model/graph_encoder.py"
    click ViewGen "https://github.com/omicsml/focus/blob/main/focus/model/view_generator.py"
    click Layers "https://github.com/omicsml/focus/blob/main/focus/model/layers.py"
    click Losses "https://github.com/omicsml/focus/blob/main/focus/model/losses.py"
    click GCNAdj "https://github.com/omicsml/focus/blob/main/focus/model/GCN_adj.py"
    click ResGCN "https://github.com/omicsml/focus/blob/main/focus/model/ResGCN.py"
    click BaseModel "https://github.com/omicsml/focus/blob/main/focus/model/base/_base_model.py"
    click EncModule "https://github.com/omicsml/focus/blob/main/focus/module/_encoder_module.py"
    click ViewModule "https://github.com/omicsml/focus/blob/main/focus/module/_view_generator.py"
    click Gat "https://github.com/omicsml/focus/blob/main/focus/module/nets/_gat.py"
    click GCNAdjNet "https://github.com/omicsml/focus/blob/main/focus/module/nets/_gcnadj.py"
    click ResGcnNet "https://github.com/omicsml/focus/blob/main/focus/module/nets/_resgcn.py"
    click DenseGin "https://github.com/omicsml/focus/blob/main/focus/module/nets/_denseginconv.py"
    click MLP "https://github.com/omicsml/focus/blob/main/focus/module/nets/_mlp.py"
    click SimCLR "https://github.com/omicsml/focus/blob/main/focus/module/nets/_simclr.py"
    click GraphConv "https://github.com/omicsml/focus/blob/main/focus/module/nets/_graphconvolution.py"
    click CellType "https://github.com/omicsml/focus/blob/main/focus/task/celltype_classfication.py"
    click TrainPlans "https://github.com/omicsml/focus/blob/main/focus/train/trainingplans.py"
    click ViewPlan "https://github.com/omicsml/focus/blob/main/focus/train/view_graph_trainplan.py"
    click RunAll "https://github.com/omicsml/focus/blob/main/run_all.py"
    click UtilsAll "https://github.com/omicsml/focus/blob/main/focus/utils/utils.py"
    click Const "https://github.com/omicsml/focus/blob/main/focus/_constants.py"
    click ModelUtils "https://github.com/omicsml/focus/blob/main/focus/model/utils.py"
    click ModuleUtils "https://github.com/omicsml/focus/blob/main/focus/module/utils.py"

    %% Styles
    classDef data fill:#D0E7FF,stroke:#0091FF,stroke-width:1px
    classDef dataset fill:#DFFFE0,stroke:#57A300,stroke-width:1px
    classDef model fill:#FFE7C0,stroke:#FF8C00,stroke-width:1px
    classDef train fill:#F0D0FF,stroke:#A000FF,stroke-width:1px
    classDef util fill:#E0E0E0,stroke:#555555,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#CCCCCC,stroke-width:1px,stroke-dasharray: 5 5
```
