# kyungeun-lee/tabularbinning architecture

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

- Interactive diagram: https://gitdiagram.com/kyungeun-lee/tabularbinning
- Repository: https://github.com/kyungeun-lee/tabularbinning

## Overview

##### Project type and purpose
- This is a self-supervised learning (SSL) research codebase for tabular data (“Binning as a Pretext Task”), not a web or microservices app.
- It implements a pretext task (reconstructing discretized bin indices) to learn feature representations, then evaluates them via a downstream linear or fine-tuning classifier.

##### File structure
- Top‐level scripts:
- main_ssl.py – runs the SSL training (encoder + decoder).
- main_eval.py – runs downstream evaluation (linear probe or fine-tuning).
- config.yaml – experiment parameters (e.g., number of bins, architectures, learning rates).
- dataset/ – raw CSV data; data ingestion source.
- libs/ – core logic:
- transform.py – binning and other input transforms.
- model.py – encoder and decoder network definitions.
- utils.py – training loops, logging, checkpoint I/O.
- results/ – logs, model checkpoints, evaluation metrics.

##### Key insights from README
- Workflow: (1) discretize features → (2) SSL training to predict bin indices → (3) save encoder → (4) downstream evaluation (linear/fine-tuning).
- Dependencies: PyTorch, scikit-learn, numpy/pandas, an external library rtdl for tabular architectures, etc.
- Outputs: model weights (.pt), logs (.log).

##### Components and interactions
a. Main components
- Data Ingestion & Binning Preprocessor
- Self-Supervised Model (Encoder + Decoder)
- Checkpoint & Logging System
- Evaluation Module (Linear Probe / Fine-tuning)
- Configuration Manager (config.yaml)
- External Libraries (PyTorch, scikit-learn, rtdl)
b. Relationships and data flow
1. Configuration Manager loads hyperparameters → drives both SSL and Eval scripts.
2. Dataset CSV → Binning Preprocessor (transform.py) → yields binned targets + raw features.
3. Features → Encoder network → latent representations → Decoder network → predicts bin indices.
4. Loss computation → backprop → weight updates → checkpoint saved via utils.py → results/.
5. For evaluation: Trained encoder → freeze or unfreeze (fine-tuning flag) + attach linear head → evaluate on ground-truth labels → write logs.
c. Architectural patterns
- Pipeline pattern – sequential data transformations (ETL style).
- Modular design – separation of concerns: data transforms, model definition, utils/training, evaluation.
d. Key technologies
- PyTorch for model training
- rtdl as a tabular-model library
- scikit-learn for quantile binning
- YAML/argparse for configuration and CLI

##### Be thorough but modular
- Every major subdirectory or file that impacts flow (dataset, libs/transform.py, libs/model.py, main_ssl.py, main_eval.py, results).
- Don’t overload with implementation details (no need to call out each util function), but do show the division between pretext and downstream.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    CONFIG["Configuration Manager\n(config.yaml)"]:::orchestration
    REQ["Dependency Manifest\n(requirements.txt)"]:::orchestration
    SSL_SCRIPT["SSL Training Script\n(main_ssl.py)"]:::orchestration
    EVAL_SCRIPT["Evaluation Script\n(main_eval.py)"]:::orchestration

    %% Data Layer
    DATASET["Raw CSV Dataset\n(Churn_Modelling.csv)"]:::data
    TRANSFORM["Binning Preprocessor\n(transform.py)"]:::data

    %% Model Layer
    MODEL["Self-Supervised Model\n(Encoder + Decoder)"]:::model
    EVAL_HEAD["Linear Head\n(fine-tuning/linear probe)"]:::model
    LOSS["Loss Computation & Backprop"]:::model

    %% Storage Layer
    UTILS["Checkpoint & Logging Utils\n(utils.py)"]:::storage
    RESULTS["Results Storage\n(results/)"]:::storage
    STATIC["Static Assets\n(figures/)"]:::storage

    %% Flow
    CONFIG -->|loads config| SSL_SCRIPT
    CONFIG -->|loads config| EVAL_SCRIPT
    REQ --> SSL_SCRIPT

    SSL_SCRIPT --> DATASET
    DATASET --> TRANSFORM
    TRANSFORM --> MODEL
    MODEL --> LOSS
    LOSS --> UTILS
    UTILS --> RESULTS

    RESULTS --> EVAL_SCRIPT
    EVAL_SCRIPT --> MODEL
    MODEL --> EVAL_HEAD
    EVAL_HEAD --> LOSS
    LOSS --> UTILS
    UTILS --> RESULTS

    SSL_SCRIPT -->|uses rtdl, PyTorch, scikit-learn| MODEL
    EVAL_SCRIPT -->|uses rtdl, PyTorch| EVAL_HEAD

    STATIC -->|diagrams| SSL_SCRIPT

    %% Click Events
    click CONFIG "https://github.com/kyungeun-lee/tabularbinning/blob/main/config.yaml"
    click REQ "https://github.com/kyungeun-lee/tabularbinning/blob/main/requirements.txt"
    click SSL_SCRIPT "https://github.com/kyungeun-lee/tabularbinning/blob/main/main_ssl.py"
    click EVAL_SCRIPT "https://github.com/kyungeun-lee/tabularbinning/blob/main/main_eval.py"
    click DATASET "https://github.com/kyungeun-lee/tabularbinning/blob/main/dataset/Churn_Modelling.csv"
    click TRANSFORM "https://github.com/kyungeun-lee/tabularbinning/blob/main/libs/transform.py"
    click MODEL "https://github.com/kyungeun-lee/tabularbinning/blob/main/libs/model.py"
    click UTILS "https://github.com/kyungeun-lee/tabularbinning/blob/main/libs/utils.py"
    click RESULTS "https://github.com/kyungeun-lee/tabularbinning/tree/main/results/"
    click STATIC "https://github.com/kyungeun-lee/tabularbinning/tree/main/figures/"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,color:#004085
    classDef model fill:#d4edda,stroke:#155724,color:#155724
    classDef orchestration fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
