# inwonakng/tdbench architecture

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

- Interactive diagram: https://gitdiagram.com/inwonakng/tdbench
- Repository: https://github.com/inwonakng/tdbench

## Overview

##### Project type and purpose
- This is a research‑oriented machine‑learning benchmarking framework (“TDBench”) for tabular data distillation and downstream classification.
- It is not a web or full‑stack application but rather a modular pipeline: data ingestion → preprocessing → distillation → representation learning → classifier training/HPO → result aggregation/visualization.

##### File structure
- Top‑level:
- scripts & Q*.py files: experiment entry points for different research questions
- config/: Hydra config hierarchy for data, encoder, distill, classifier, tuning
- tabdd/: application code (subpackages: config, data, distill, models, results, dashboard, scripts, tune, utils)
- figures/: generated plots
- requirements_*.txt: environment definitions
- Key patterns:
- Hydra for configuration management (config/ + @hydra.main scripts)
- Modular ML components under tabdd/models and tabdd/distill
- Data loader & preprocessing under tabdd/data
- Results loaders & plotters under tabdd/results and tabdd/dashboard
- CLI orchestration via python -m tabdd.[scripts|tune].*

##### README insights
- Entry points must be run with `-m tabdd.xxx` in a conda‑managed environment
- Hydra config overrides drive experiments (e.g. data.datasets, distill.methods)
- Extensibility points: add new YAML under config, new DatasetConfig, new DistillConfig, new Encoder subclasses

a. Main components
1. CLI / Experiment Launcher
– Entry scripts (Q*.py, tabdd/scripts/, tabdd/tune/)
2. Config Manager
– Hydra + YAML files under config/
3. Pipeline Orchestrator
– PipelineConfig + main() functions that wire subcomponents
– Ray integration for distributed execution/HPO
4. Data Module
– tabdd/data/load (OpenML/Kaggle), tabdd/data/preprocessing, TabularDataModule
– Outputs preprocessed batches or cached HDF5
5. Distillation Engine
– tabdd/distill methods (kmeans, random_sample, graph_cut, etc.)
– Produces distilled datasets or embeddings
6. Encoder & Classifier Trainers
– tabdd/models/encoder (autoencoders, multihead, GNN)
– tabdd/models/classifier (MLP, XGB, ResNet, Transformer)
– Wrapped in Hydra‑driven tuning (Ray Tune)
7. Results Store
– Filesystem directories (RAY_RESULT_DIR, results/), CSV/HDF5 records
8. Analysis & Visualization
– tabdd/results/load & tabdd/results/plot modules
– tabdd/dashboard for interactive dashboards
– figures/ output

b. Relationships & data flow
- CLI → Config Manager loads YAML → Pipeline Orchestrator
- Orchestrator invokes Data Module → raw data → preprocessing → cached features
- Orchestrator forks two paths:
1. Distillation Engine on raw or encoded features → distilled set
2. Encoder training on raw data → latent representations
- Classifier Trainer consumes either raw, distilled or encoded data → model training/HPO via Ray → metrics/results
- Results Store collects experiment outputs → passed to Analysis & Visualization → plots/figures

c. Architectural patterns & design principles
- Modular plugin pattern: new distill methods, encoders, classifiers drop into their folders and register via Hydra config
- Separation of concerns: data ingestion, transformation, model logic, result analysis
- Config‑driven execution: Hydra for reproducibility and easy parameter sweeps
- Distributed/HPO orchestration: Ray for parallelism

d. Relevant technologies
- Python 3.10, PyTorch, torch_geometric
- Hydra for configuration
- Ray Tune for HPO and distributed experiments
- OpenML/Kaggle APIs for data ingestion
- Matplotlib/Plotly for plotting, Jinja2 (?) for dashboard

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External services
    CondaEnv["Conda Env"]:::external
    OpenML["OpenML API"]:::external
    Kaggle["Kaggle API"]:::external
    RayCluster["Ray Cluster"]:::external

    %% CLI / Experiment Launcher
    subgraph "CLI / Experiment Launcher"
        Q0["Q0_experiment_scale.py"]:::code
        Q1["Q1_encoding.py"]:::code
        Q2["Q2_distill_methods.py"]:::code
        Q3["Q3_autoencoders.py"]:::code
        Q4a["Q4_1_runtime.py"]:::code
        Q4b["Q4_2_hpo.py"]:::code
        Q5["Q5_class_imbal.py"]:::code
        Q6["Q6_feature_corel.py"]:::code
        Scripts["tabdd/scripts/"]:::code
        TuneScripts["tabdd/tune/"]:::code
    end

    %% Config Manager
    subgraph "Config Manager"
        HydraYAML["config/ (Hydra YAML)"]:::config
        DC["dataset_config.py"]:::config
        DMC["data_mode_config.py"]:::config
        DistC["distill_config.py"]:::config
        EncC["encoder_config.py"]:::config
        ClassC["classifier_config.py"]:::config
        PipeC["pipeline_config.py"]:::config
        Paths["paths.py"]:::config
    end

    %% Pipeline Orchestrator
    subgraph "Pipeline Orchestrator"
        TotalPipe["total_pipelines.py"]:::code
        BuildScripts["build_scripts.py"]:::code
        PipeConfig["pipeline_config.py"]:::config
    end

    %% Data Module
    subgraph "Data Module"
        subgraph "Load"
            OpenMLLoad["openml.py"]:::code
            KaggleLoad["kaggle.py"]:::code
            MIMICLoad["mimic3.py"]:::code
            DataUtils["utils.py"]:::code
        end
        subgraph "Preprocessing"
            OneHot["one_hot_encoder.py"]:::code
            Scaler["scaler.py"]:::code
        end
        TDM["tabular_data_module.py"]:::code
        TDSet["tabular_dataset.py"]:::code
        Reduce2D["reduce_2d.py"]:::code
    end

    %% Distillation Engine
    subgraph "Distillation Engine"
        DistDir["tabdd/distill/"]:::code
    end

    %% Encoder & Classifier Trainers
    subgraph "Models"
        subgraph "Encoders"
            BE["base_encoder.py"]:::code
            MLP_AE["mlp_autoencoder.py"]:::code
            TF_AE["tf_autoencoder.py"]:::code
            GNN_AE["gnn_autoencoder.py"]:::code
            MH_AE["multihead_autoencoder.py"]:::code
            TabAE["tabular_autoencoder.py"]:::code
        end
        subgraph "Classifiers"
            FTTrans["ft_transformer.py"]:::code
            ResNet["resnet.py"]:::code
            GetClf["get_classifier.py"]:::code
        end
        HyperTuneEnc["tabdd/tune/encoder.py"]:::code
        HyperTuneClf["tabdd/tune/classifier.py"]:::code
    end

    %% Results Store
    subgraph "Results Store"
        RAY_DIR["RAY_RESULT_DIR (FS)"]:::datastore
        ResultsLoad["tabdd/results/load/"]:::code
        Figures["figures/"]:::datastore
    end

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        PlotMods["tabdd/results/plot/"]:::code
        DashPlots["tabdd/results/plot/dashboard/"]:::code
        DashCLI["tabdd/dashboard/"]:::code
    end

    %% Relationships
    CondaEnv -->|runs| Q0
    CondaEnv -->|runs| Q1
    CondaEnv -->|runs| Q2
    CondaEnv -->|runs| Q3
    CondaEnv -->|runs| Q4a
    CondaEnv -->|runs| Q4b
    CondaEnv -->|runs| Q5
    CondaEnv -->|runs| Q6
    Q0 -->|loads| HydraYAML
    Q1 -->|loads| HydraYAML
    Q2 -->|loads| HydraYAML
    Q3 -->|loads| HydraYAML
    Q4a -->|loads| HydraYAML
    Q4b -->|loads| HydraYAML
    Q5 -->|loads| HydraYAML
    Q6 -->|loads| HydraYAML
    Scripts -->|loads| HydraYAML
    TuneScripts -->|loads| HydraYAML

    HydraYAML -->|provides| PipeConfig
    DC -->|registered| HydraYAML
    DMC -->|registered| HydraYAML
    DistC -->|registered| HydraYAML
    EncC -->|registered| HydraYAML
    ClassC -->|registered| HydraYAML
    Paths -->|registered| HydraYAML

    PipeConfig -->|orchestrates| TotalPipe
    PipeConfig -->|orchestrates| BuildScripts
    TotalPipe -->|executes| OpenMLLoad
    TotalPipe -->|executes| KaggleLoad
    TotalPipe -->|executes| MIMICLoad
    TotalPipe -->|executes| OneHot
    TotalPipe -->|executes| Scaler
    TotalPipe -->|executes| TDM
    TotalPipe -->|executes| TDSet

    OpenML -->|ingest| OpenMLLoad
    Kaggle -->|ingest| KaggleLoad

    TotalPipe -->|distill| DistDir
    TotalPipe -->|train_encoder| BE
    TotalPipe -->|train_encoder| MLP_AE
    TotalPipe -->|train_encoder| TF_AE
    TotalPipe -->|train_encoder| GNN_AE
    TotalPipe -->|train_encoder| MH_AE
    TotalPipe -->|train_encoder| TabAE
    TotalPipe -->|train_classifier| FTTrans
    TotalPipe -->|train_classifier| ResNet
    TotalPipe -->|train_classifier| GetClf
    RayCluster -->|schedule| TotalPipe
    RayCluster -->|tune| HyperTuneEnc
    RayCluster -->|tune| HyperTuneClf

    DistDir -->|output| RAY_DIR
    BE -->|output| RAY_DIR
    MLP_AE -->|output| RAY_DIR
    TF_AE -->|output| RAY_DIR
    GNN_AE -->|output| RAY_DIR
    MH_AE -->|output| RAY_DIR
    TabAE -->|output| RAY_DIR
    FTTrans -->|output| RAY_DIR
    ResNet -->|output| RAY_DIR
    GetClf -->|output| RAY_DIR

    RAY_DIR -->|load| ResultsLoad
    ResultsLoad -->|plot| PlotMods
    PlotMods -->|dashboard| DashPlots
    DashPlots -->|cli| DashCLI
    Figures -->|generated by| PlotMods

    %% Click Events
    click Q0 "https://github.com/inwonakng/tdbench/blob/main/Q0_experiment_scale.py"
    click Q1 "https://github.com/inwonakng/tdbench/blob/main/Q1_encoding.py"
    click Q2 "https://github.com/inwonakng/tdbench/blob/main/Q2_distill_methods.py"
    click Q3 "https://github.com/inwonakng/tdbench/blob/main/Q3_autoencoders.py"
    click Q4a "https://github.com/inwonakng/tdbench/blob/main/Q4_1_runtime.py"
    click Q4b "https://github.com/inwonakng/tdbench/blob/main/Q4_2_hpo.py"
    click Q5 "https://github.com/inwonakng/tdbench/blob/main/Q5_class_imbal.py"
    click Q6 "https://github.com/inwonakng/tdbench/blob/main/Q6_feature_corel.py"
    click Scripts "https://github.com/inwonakng/tdbench/tree/main/tabdd/scripts/"
    click TuneScripts "https://github.com/inwonakng/tdbench/tree/main/tabdd/tune/"
    click HydraYAML "https://github.com/inwonakng/tdbench/tree/main/config/"
    click DC "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/dataset_config.py"
    click DMC "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/data_mode_config.py"
    click DistC "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/distill_config.py"
    click EncC "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/encoder_config.py"
    click ClassC "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/classifier_config.py"
    click Paths "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/paths.py"
    click PipeConfig "https://github.com/inwonakng/tdbench/blob/main/tabdd/config/pipeline_config.py"
    click TotalPipe "https://github.com/inwonakng/tdbench/blob/main/tabdd/scripts/total_pipelines.py"
    click BuildScripts "https://github.com/inwonakng/tdbench/blob/main/tabdd/scripts/build_scripts.py"
    click OpenMLLoad "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/load/openml.py"
    click KaggleLoad "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/load/kaggle.py"
    click MIMICLoad "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/load/mimic3.py"
    click DataUtils "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/load/utils.py"
    click OneHot "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/preprocessing/one_hot_encoder.py"
    click Scaler "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/preprocessing/scaler.py"
    click TDM "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/tabular_data_module.py"
    click TDSet "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/tabular_dataset.py"
    click Reduce2D "https://github.com/inwonakng/tdbench/blob/main/tabdd/data/reduce_2d.py"
    click BE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/base_encoder.py"
    click MLP_AE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/mlp_autoencoder.py"
    click TF_AE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/tf_autoencoder.py"
    click GNN_AE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/gnn_autoencoder.py"
    click MH_AE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/multihead_autoencoder.py"
    click TabAE "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/encoder/tabular_autoencoder.py"
    click FTTrans "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/classifier/ft_transformer.py"
    click ResNet "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/classifier/resnet.py"
    click GetClf "https://github.com/inwonakng/tdbench/blob/main/tabdd/models/classifier/get_classifier.py"
    click HyperTuneEnc "https://github.com/inwonakng/tdbench/blob/main/tabdd/tune/encoder.py"
    click HyperTuneClf "https://github.com/inwonakng/tdbench/blob/main/tabdd/tune/classifier.py"
    click ResultsLoad "https://github.com/inwonakng/tdbench/tree/main/tabdd/results/load/"
    click PlotMods "https://github.com/inwonakng/tdbench/tree/main/tabdd/results/plot/"
    click DashPlots "https://github.com/inwonakng/tdbench/tree/main/tabdd/results/plot/dashboard/"
    click DashCLI "https://github.com/inwonakng/tdbench/tree/main/tabdd/dashboard/"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#4A90E2;
    classDef config fill:#FFE4B2,stroke:#FFA500;
    classDef datastore fill:#DFFFE0,stroke:#33A02C;
    classDef external fill:#F0D0FF,stroke:#800080;
```
