# silencex12138/protogate architecture

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

- Interactive diagram: https://gitdiagram.com/silencex12138/protogate
- Repository: https://github.com/silencex12138/protogate

## Overview

##### Project type and purpose
- This repo is an open-source research codebase (Python/PyTorch) implementing ProtoGate, a prototype-based neural network with global-to-local feature selection for tabular biomedical data, along with benchmark methods (KNN, LASSO, MLP, RF, TabNet). It provides end-to-end experiment orchestration (data loading → training → evaluation → logging).

##### File structure
- Top level
- data/ – tabular biomedical datasets (e.g. Metabric samples)
- scripts/ – per-method experiment folders (KNN, LASSO, MLP, PROTOGATE, RF, TABNET) each containing shell scripts to launch experiments
- src/ – core library:
– _config.py, _shared_imports.py for global settings
– dataset.py for data loading and preprocessing
– custom_models/ (MLP, ProtoGate implementations)
– models.py for “vanilla” or wrapper model definitions
– lookahead_optimizer.py – custom optimizer
– param_tune.py – hyperparameter tuning logic
– run_experiment.py – main training/evaluation loop
– utils.py – logging, checkpoint utilities
- protogate_colab.ipynb & colab_requirements.txt – Colab setup
- requirements.txt – dependencies (PyTorch, scikit-learn, wandb, etc.)

##### README for additional insights
- Confirms PyTorch implementation, optional LightGBM support, WandB for logging
- Describes experiment scripts and parameter overrides
- Details usage on local vs Google Colab

a. Main components
- Data Layer
– Local CSV files in data/
– External dataset sources (TabZilla, scikit-feature)
- Data Ingestion & Preprocessing
– src/dataset.py
- Model Zoo
– Benchmark methods (KNN, LASSO, RF, TabNet in src/models & custom_models)
– ProtoGate implementation (src/custom_models/protogate/ProtoGate.py)
- Training & Evaluation Engine
– run_experiment.py orchestrates:
- Parameter parsing (from scripts or CLI)
- Model instantiation
- Optimizer & scheduler setup (including lookahead_optimizer)
- Training loop, validation, checkpointing (via utils)
- Hyperparameter Tuning
– param_tune.py for grid search or custom tuning
- Experiment Runner
– scripts/*/*.sh invoking run_experiment.py with method-specific flags
- Logging & Tracking
– WandB integration in utils or run_experiment
- Interactive Interface
– protogate_colab.ipynb for Colab users

b. Relationships & interactions
2. Engine → (calls) Data Ingestion → Loads raw CSVs → Feeds mini-batches
3. Engine → (instantiates) Model from Model Zoo → Feeds data
4. Engine → (uses) Optimizer → Updates model parameters
5. Engine → (logs) metrics to WandB or stdout → persisted via utils
6. Optional: Engine → param_tune to loop over hyperparameters
7. Notebook → (can call) the same Python modules interactively

c. Architectural patterns & design principles
- Modular separation of concerns: data, models, training, tuning, scripts
- Plugin-style Model Zoo allows adding new models without touching core engine
- Reproducible experiments via shell scripts capturing CLI parameters
- Config file for global settings to ensure consistency

d. Key technologies & frameworks
- Python 3.9+, PyTorch
- Scikit-learn, pandas, numpy for data utilities
- Optional LightGBM for benchmarking
- WandB for experiment tracking
- Shell scripts for reproducible workflows
- Jupyter Notebook for interactive experiments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DL_FILES[("Local CSV files\ndata/Metabric_samples/...")]:::data
        EXT_DS[("External Dataset Sources\nTabZilla, scikit-feature")]:::external
    end

    %% Core Library
    subgraph "Core Library"
        GC["Global Config & Shared Imports\n(src/_config.py,\n src/_shared_imports.py)"]:::module
        CI["Data Ingestion & Preprocessing Module\n(src/dataset.py)"]:::module
        MODEL_VAN["Benchmark Model Zoo\n(src/models.py)"]:::module
        MLP["MLP Implementation\n(src/custom_models/mlp/MLP.py)"]:::module
        PG["ProtoGate Implementation\n(src/custom_models/protogate/ProtoGate.py)"]:::module
        OPT["Custom Optimizer (Lookahead)\n(src/lookahead_optimizer.py)"]:::module
        ENGINE["Training & Evaluation Engine\n(src/run_experiment.py)"]:::module
        TUNE["Hyperparameter Tuning Engine\n(src/param_tune.py)"]:::module
        UTIL["Utilities (logging, checkpointing,\nWandB integration)\n(src/utils.py)"]:::module
    end

    %% Experiment Runner Scripts
    subgraph "Experiment Runner Scripts"
        KNN["KNN Scripts\n(scripts/KNN)"]:::script
        LASSO["LASSO Scripts\n(scripts/LASSO)"]:::script
        MLP_S["MLP Scripts\n(scripts/MLP)"]:::script
        PG_S["ProtoGate Scripts\n(scripts/PROTOGATE)"]:::script
        RF_S["RF Scripts\n(scripts/RF)"]:::script
        TB_S["TabNet Scripts\n(scripts/TABNET)"]:::script
    end

    %% Notebook & Resources
    NOTEBOOK["Interactive Colab Notebook\n(protogate_colab.ipynb)"]:::notebook
    RES["Dependencies & Docs\nrequirements.txt\nREADME.md, LICENSE"]:::resource

    %% Connections
    KNN -->|"CLI args"| ENGINE
    LASSO -->|"CLI args"| ENGINE
    MLP_S -->|"CLI args"| ENGINE
    PG_S -->|"CLI args"| ENGINE
    RF_S -->|"CLI args"| ENGINE
    TB_S -->|"CLI args"| ENGINE

    ENGINE -->|"calls"| CI
    CI -->|"loads data"| DL_FILES
    CI -->|"fetches external"| EXT_DS
    ENGINE -->|"instantiates"| MODEL_VAN
    ENGINE -->|"instantiates"| MLP
    ENGINE -->|"instantiates"| PG
    ENGINE -->|"uses"| OPT
    ENGINE -->|"logs metrics"| UTIL
    ENGINE -->|"optional tuning"| TUNE
    NOTEBOOK -->|"interactive calls"| CI
    NOTEBOOK -->|"interactive calls"| ENGINE

    %% Click Events
    click DL_FILES "https://github.com/silencex12138/protogate/blob/master/data/Metabric_samples/metabric_pam50_train_200.csv"
    click CI "https://github.com/silencex12138/protogate/blob/master/src/dataset.py"
    click GC "https://github.com/silencex12138/protogate/blob/master/src/_config.py"
    click GC "https://github.com/silencex12138/protogate/blob/master/src/_shared_imports.py"
    click MODEL_VAN "https://github.com/silencex12138/protogate/blob/master/src/models.py"
    click MLP "https://github.com/silencex12138/protogate/blob/master/src/custom_models/mlp/MLP.py"
    click PG "https://github.com/silencex12138/protogate/blob/master/src/custom_models/protogate/ProtoGate.py"
    click OPT "https://github.com/silencex12138/protogate/blob/master/src/lookahead_optimizer.py"
    click ENGINE "https://github.com/silencex12138/protogate/blob/master/src/run_experiment.py"
    click TUNE "https://github.com/silencex12138/protogate/blob/master/src/param_tune.py"
    click UTIL "https://github.com/silencex12138/protogate/blob/master/src/utils.py"
    click KNN "https://github.com/silencex12138/protogate/blob/master/scripts/KNN/run_exp_knn_real.sh"
    click LASSO "https://github.com/silencex12138/protogate/blob/master/scripts/LASSO/run_exp_lasso_real.sh"
    click LASSO "https://github.com/silencex12138/protogate/blob/master/scripts/LASSO/run_exp_lasso_syn.sh"
    click MLP_S "https://github.com/silencex12138/protogate/blob/master/scripts/MLP/run_exp_mlp_real.sh"
    click PG_S "https://github.com/silencex12138/protogate/blob/master/scripts/PROTOGATE/run_exp_protogate_real.sh"
    click PG_S "https://github.com/silencex12138/protogate/blob/master/scripts/PROTOGATE/run_exp_protogate_syn.sh"
    click RF_S "https://github.com/silencex12138/protogate/blob/master/scripts/RF/run_exp_rf_real.sh"
    click RF_S "https://github.com/silencex12138/protogate/blob/master/scripts/RF/run_exp_rf_syn.sh"
    click TB_S "https://github.com/silencex12138/protogate/blob/master/scripts/TABNET/run_exp_tabnet_real.sh"
    click TB_S "https://github.com/silencex12138/protogate/blob/master/scripts/TABNET/run_exp_tabnet_syn.sh"
    click NOTEBOOK "https://github.com/silencex12138/protogate/blob/master/protogate_colab.ipynb"
    click RES "https://github.com/silencex12138/protogate/blob/master/requirements.txt"
    click RES "https://github.com/silencex12138/protogate/blob/master/README.md"
    click RES "https://github.com/silencex12138/protogate/tree/master/LICENSE"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#333,stroke-width:1px;
    classDef module fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef script fill:#CFD8DC,stroke:#333,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px;
    classDef notebook fill:#E1BEE7,stroke:#333,stroke-width:1px;
    classDef resource fill:#F5F5F5,stroke:#333,stroke-width:1px;
```
