How redgriff/t-vae-gan works
Project type and purpose
• Project type: A Python library for tabular data synthesis using a hybrid “t-Variational Autoencoder + GAN” model.
• Purpose: Load real tabular data, train a TVAeGAN model (encoder, decoder, critic), then generate synthetic data with similar distributions.
File structure
• Top-level:
• examples/ → sample data and example usage (adult.csv, example.ipynb, example.py)
• src/ → core Python modules
• requirements.txt → external dependencies (likely PyTorch, NumPy, pandas, etc.)
• README.md → project title; assumes more details are in code/docs.
• src/ modules:
• data_loader.py → ingest raw CSV or DataFrame
• data_handler.py → preprocess (normalization, categorical encoding, train/test split)
• encoder_critic.py → critic network (GAN discriminator)
• decoder_generator.py → generator network (GAN generator / VAE decoder)
• mlp_network.py → helper MLP blocks used by encoder/decoder/critic
• tvaegan_network.py → stitches encoder, decoder, critic into a single model class
• tvaegan_synthesizer.py → high-level API: trains the network, manages epochs, loss functions, and sampling
README for additional insights
• The README is minimal; the source code names reveal the architecture: a two-stage model (VAE pretraining + adversarial training) whose components are modularized in separate files.
a. Main components
• Data Ingestion Layer
– examples/adult.csv or user-provided CSV
– data_loader.py
• Data Preprocessing Layer
– data_handler.py (scalers, encoders)
• Model Definition
– mlp_network.py (shared building blocks)
– encoder_critic.py
– decoder_generator.py
– tvaegan_network.py
• Training Orchestrator
– tvaegan_synthesizer.py (trains VAE phase, then GAN phase)
• External Dependencies
– PyTorch/TensorFlow, NumPy, pandas
• Output
– Synthetic dataset (pandas DataFrame or CSV)
b. Relationships and interactions
• Raw Data → Data Loader → Data Handler → preprocessed tensors
• Preprocessed tensors → TVAeGAN Synthesizer
• Synthesizer pulls in TVAeGAN Network
• TVAeGAN Network uses MLP blocks to build Encoder, Decoder, Critic
• Training loop in Synthesizer:
– VAE pretraining: Encoder ↔ Decoder (reconstruction loss + KL)
– GAN training: Generator(Decoder) ↔ Critic (adversarial loss)
• After training: Synthesizer calls sampling API on TVAeGAN Network → outputs synthetic data → passes back through inverse transforms in Data Handler → final CSV/DataFrame
c. Architectural patterns and design principles
• Modularization: each network component in its own module
• Layered design: clear separation between data handling, model definition, and orchestration
• Reuse: MLP blocks factored into mlp_network.py
• Two-phase training pipeline encapsulated in synthesizer
d. Key technologies & libraries
• PyTorch (torch.nn, torch.optim)
• pandas / NumPy for data I/O and processing
• Scikit-learn utilities (scalers, encoders)
Elements
• Raw CSV → DataLoader → DataHandler → Synthesizer → TVAeGAN Network → Loss & Optimizers → back to Synthesizer
• Synthesizer → Sampling → DataHandler (inverse preprocess) → Synthetic CSV
• Blue for data layers (Loader/Handler)
• Green for model definition (Encoder, Decoder, Critic, MLP)
• Orange for orchestrator (Synthesizer)
• Gray for external dependencies
• Rectangles for code modules/classes
• Parallelograms for inputs/outputs