How amirarsalan90/tabfairgan works
Project type and purpose
• TabFairGAN is a Python library/package for fair synthetic tabular data generation using a Wasserstein GAN.
• It’s neither a web app nor a full‐stack system: it’s an ML/data‐generation tool that users integrate into Python workflows.
File structure
• Top level:
• setup.py, requirements.txt, MANIFEST.in → packaging & dependencies
• adult/adult.csv → sample dataset
• notebook/usage.ipynb → demo & usage examples
• src/tabfairgan/ → core library code
• In src/tabfairgan:
• main.py → public API entry (TFG class, training & generation orchestration)
• modules.py → defines model components (Generator, Discriminator, fairness loss modules)
• utils.py → data preprocessing, CSV I/O, metric calculations
README for additional insights
• The library exposes a single class (TFG) that takes a DataFrame + optional fairness_config
• Two modes:
a. Unconstrained GAN training (only WGAN losses)
b. Fairness‐constrained training (additional fairness loss weighted by λ)
• Output: synthetic DataFrame of specified size
Main components
a. Data Input Layer
• Raw CSV (e.g., adult.csv) → pandas.DataFrame
b. Preprocessing Module (utils.py)
• Categorical/continuous encoding, normalization
c. GAN Architecture (modules.py)
• Generator
• Discriminator (Critic)
• Fairness Constraint Module (conditional/appended to loss when provided)
d. Training Orchestrator (main.py → TFG.train())
• Loop over epochs & batches
• Compute WGAN loss + optional fairness loss
• Optimizer steps for G and D
e. Synthetic Data Generator (main.py → TFG.generate_fake_df())
• Sample latent vectors, run through Generator, post‐process to DataFrame
f. User Interface
• Python API (import tabfairgan.TFG)
• Jupyter Notebook demo
g. Packaging & Deployment
• setup.py & PyPI distribution
Relationships & interactions
• Data flows: CSV → Preprocessing → Batches → GAN training → Synthetic samples → Post‐processing → Output DataFrame
• Fairness config toggles an extra loss branch in the Discriminator training loop
• The Notebook & CLI use the same API layer (TFG)
Architectural patterns & design principles
• Modular code split by responsibility: I/O (utils), model definition (modules), orchestration (main)
• Separation of concerns: training vs. data generation vs. fairness logic
• Dependency injection of fairness parameters into the training loop
Key technologies & libraries
• Python 3.x, PyTorch (implied by GAN usage & device='cuda')
• pandas for DataFrame operations
• numpy/scipy for numerical processing
• setuptools for packaging
Elements
• Clear component labels: “Data Loader”, “Preprocessor”, “Generator”, “Discriminator”, “Fairness Module”, “Trainer”, “Synthetic Data Output”
• Data → Preprocessor → Trainer
• Trainer → Model components (G & D)
• Fairness config → Trainer
• Trainer → Synthetic Data Generator → Output
• Blue for data components
• Green for model components
• Orange for configuration/fairness
Detailed capturing of essential architectural elements
• Don’t just show “GAN”: break it into Generator and Discriminator subcomponents
• Post‐processing in utils (e.g., decoding one‐hot back to raw feature values)