How kyungeun-lee/tabularbinning works
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.