# jma712/gear architecture

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

- Interactive diagram: https://gitdiagram.com/jma712/gear
- Repository: https://github.com/jma712/gear

## Overview

##### Project Type and Purpose
- Type: Research‑oriented ML pipeline / open‑source tool for fair graph node embedding.

##### Main Components
A. Data Layer
– Raw datasets (dataset/bail, dataset/credit, dataset/synthetic.mat)
– CSV/edge‑list files and dataset readmes
B. Preprocessing
– Preprocessing.py: cleans, normalizes node features and sensitive attributes
– src/graphFair_subgraph/cf: load true counterfactuals
D. Model Definition
– models.py: GEAR architecture (GNN encoder, fairness loss)
– CFGT.py & CFDA.py: implementations of counterfactual generation/training strategies
E. Training & Evaluation Orchestration
– utils.py & utils_mp.py: multiprocessing, data loaders, metric computations
F. Persistence & Outputs
– models_save/: trained model checkpoints
– logs/metrics (you may add if desired)

##### Relationships & Data Flow
1. Raw Data → Preprocessing
4. Training Iterations ↔ Models & Utils
5. Model Checkpoints → models_save/
6. Evaluation → metrics printed or persisted

##### Architectural Patterns & Design Principles
- Modular separation: each major step lives in its own script/module
- Reproducibility: CLI interface in main.py captures experiment_type and hyperparameters

##### Technologies & Frameworks
- Python 3.6
- PyTorch 1.6.0 + torch‑geometric 1.3.0 (GNN layers, data loaders)
- scikit‑learn (metrics, preprocessing)
- numpy (matrix ops)
- multiprocessing (utils_mp.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RawDatasets(("Raw Datasets")):::data
        Bail["Bail Dataset"]:::data
        Credit["Credit Dataset"]:::data
        Synthetic["Synthetic Dataset"]:::data
    end

    %% Compute Layer
    subgraph "Compute Layer"
        Preprocess["Preprocessing"]:::compute
        SubGenAug["Augmented Subgraph Gen"]:::compute
        SubGenCF["Counterfactual Subgraph Gen"]:::compute
        Subgcon["Subgraph Contrast Sampling"]:::compute
        ModelDef["GEAR Model Definition"]:::model
        CFGT["CFGT Strategy"]:::model
        CFDA["CFDA Strategy"]:::model
        Main["Main Orchestration"]:::model
        Utils["Utils"]:::util
        UtilsMP["Utils_mp"]:::util
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        SubCacheAug(("Aug Subgraph Cache")):::persist
        SubCacheCF(("CF Subgraph Cache")):::persist
        ModelStore(("Model Store")):::persist
    end

    %% Connections
    RawDatasets -->|invokes Preprocessing.py| Preprocess
    Preprocess -->|generates| SubGenAug
    Preprocess -->|generates| SubGenCF
    SubGenAug -->|stores .pkl| SubCacheAug
    SubGenCF -->|stores .pkl| SubCacheCF
    SubGenAug -->|invokes sampling| Subgcon
    SubGenCF -->|invokes sampling| Subgcon
    Subgcon -->|samples subgraphs| SubCacheAug
    Subgcon -->|samples subgraphs| SubCacheCF
    SubGenAug -->|feeds| Main
    SubGenCF -->|feeds| Main
    SubCacheAug -->|loads .pkl| Main
    SubCacheCF -->|loads .pkl| Main
    Main -->|"uses"| ModelDef
    Main -->|"uses"| CFGT
    Main -->|"uses"| CFDA
    Main <-->|"calls"| Utils
    Main <-->|"calls"| UtilsMP
    Main -->|saves checkpoints| ModelStore

    %% Click Events
    click RawDatasets "https://github.com/jma712/gear/tree/main/dataset/"
    click Bail "https://github.com/jma712/gear/blob/main/dataset/bail/Bail_Data_1978.csv"
    click Credit "https://github.com/jma712/gear/blob/main/dataset/credit/credit.csv"
    click Synthetic "https://github.com/jma712/gear/blob/main/dataset/synthetic.mat"
    click Preprocess "https://github.com/jma712/gear/blob/main/src/Preprocessing.py"
    click SubGenAug "https://github.com/jma712/gear/blob/main/src/subgraphs.py"
    click SubGenCF "https://github.com/jma712/gear/tree/main/src/graphFair_subgraph/cf/"
    click Subgcon "https://github.com/jma712/gear/blob/main/src/subgcon.py"
    click ModelDef "https://github.com/jma712/gear/blob/main/src/models.py"
    click CFGT "https://github.com/jma712/gear/blob/main/src/CFGT.py"
    click CFDA "https://github.com/jma712/gear/blob/main/src/CFDA.py"
    click Main "https://github.com/jma712/gear/blob/main/src/main.py"
    click Utils "https://github.com/jma712/gear/blob/main/src/utils.py"
    click UtilsMP "https://github.com/jma712/gear/blob/main/src/utils_mp.py"
    click SubCacheAug "https://github.com/jma712/gear/blob/main/src/graphFair_subgraph/aug/*.pkl"
    click SubCacheCF "https://github.com/jma712/gear/blob/main/src/graphFair_subgraph/cf/*.pkl"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef persist fill:#ADD8E6,stroke:#333,stroke-width:1px;
```
