# sdv-dev/ctgan architecture

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

- Interactive diagram: https://gitdiagram.com/sdv-dev/ctgan
- Repository: https://github.com/sdv-dev/ctgan

## Overview

##### Project type and purpose
- This is a Python library (ctgan/) implementing two deep-learning synthetic data generators (CTGAN & TVAE) plus associated preprocessing.
- It exposes both a programmatic API and a CLI entrypoint (`ctgan/__main__.py`).
- It bundles sample data loaders, data transformers, and synthesizer implementations as core components.

##### File structure
- **ctgan/** (core package)
- `__main__.py` – CLI entrypoint
- `data.py` – data‐loading logic (`load_demo`)
- `data_transformer.py` – transforms between raw & model‐ready formats
- `data_sampler.py` – sampling utilities and conditional vector logic
- `synthesizers/` – base classes and concrete synthesizer implementations (`ctgan.py`, `tvae.py`)
- `demo.py` – wrapper combining load → fit → sample flow
- `errors.py` – custom exception types
- **examples/** – sample CSV/TSV datasets & metadata to demonstrate library usage
- **tests/** – unit & integration tests organized by component (data transformer, synthesizers)
- **scripts/** & **tasks.py** – automation (release notes, Makefile targets)
- CI/CD configuration under **.github/workflows** and **tox.ini**

##### Extract additional insights from the README
- CTGAN implements the models described in the “Conditional GAN” NeurIPS paper.
- Primary user flows:
a. `load_demo()` → returns real DataFrame
b. `CTGAN.fit(real, discrete_cols)` → trains model
c. `CTGAN.sample(n)` → returns synthetic DataFrame
- The library can be invoked standalone or via the broader SDV ecosystem.

##### Main components & interactions
a. **User / Consumer**
- Python script or interactive REPL
- CLI (`ctgan` console script)
b. **Data Loader** (`ctgan.data`)
- Fetches raw demo data or user‐provided data
c. **Data Transformer** (`ctgan.data_transformer`)
- Converts pandas DataFrame → numerical tensors, one-hot, normalization
- Stores transformer state for inverse mapping
d. **Conditional Vector & Sampler** (`ctgan.data_sampler`)
- Computes conditional vectors for discrete columns
- Samples conditioning vectors at generate time
e. **Synthesizer Core** (`ctgan.synthesizers.base`)
- Defines `fit()`, `sample()` interface
f. **Model Implementations**
- **CTGAN** (`ctgan.synthesizers.ctgan`) – conditional GAN architecture
- **TVAE** (`ctgan.synthesizers.tvae`) – variational autoencoder variant
g. **Output Transformer** (inverse in `data_transformer`)
- Maps model output back → pandas DataFrame with original dtypes
h. **CLI / Demo** (`ctgan/__main__.py`, `ctgan/demo.py`)
- Glue code orchestrating above steps end-to-end
i. **Tests & CI**
- Unit tests for each module
- Integration tests for full fit→sample pipeline
- GitHub Actions workflows for lint, unit, integration, release

##### Architectural patterns & design principles
- **Modular Package Layout**: clear separation of concerns (data, transform, sampler, models).
- **Strategy Pattern**: base synthesizer class + pluggable model implementations.
- **ETL Pipeline**: data ingestion → transform → model training → sample → inverse transform.
- **CLI + API Dual‐Interface**: same core logic exposed programmatically and via console.
- **Test‐Driven**: comprehensive unit/integration test suite safeguarding each component.

- Technologies: Python, PyTorch (implied by CTGAN paper), pandas.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User / Consumer\n(Python script / CLI)"]:::runtime

    subgraph "Core Pipeline"
        CLI["ctgan/__main__.py\n(CLI Entrypoint)"]:::runtime
        Demo["ctgan/demo.py\n(Programmatic API)"]:::runtime
        DataLoader["ctgan/data.py\n(load_demo)"]:::runtime
        DataTransformer["ctgan/data_transformer.py\n(transform/inverse)"]:::runtime
        Sampler["ctgan/data_sampler.py\n(conditional vector & sampling)"]:::runtime
        SynthBase["ctgan/synthesizers/base.py\n(fit(), sample())"]:::runtime
        subgraph "Synthesizer Implementations"
            CTGANImpl["ctgan/synthesizers/ctgan.py\n(CTGAN Model)"]:::runtime
            TVAEImpl["ctgan/synthesizers/tvae.py\n(TVAE Model)"]:::runtime
        end
        InverseTrans["ctgan/data_transformer.py\n(inverse transform)"]:::runtime
    end

    User --> CLI
    User --> Demo
    CLI --> DataLoader
    Demo --> DataLoader
    DataLoader --> DataTransformer
    DataTransformer --> Sampler
    Sampler --> SynthBase
    SynthBase --> CTGANImpl
    SynthBase --> TVAEImpl
    CTGANImpl --> InverseTrans
    TVAEImpl --> InverseTrans
    InverseTrans --> User

    subgraph "Supporting Artifacts"
        Examples["examples/"]:::dev
        subgraph "Tests & CI"
            UnitTests["tests/unit/"]:::dev
            IntegrationTests["tests/integration/"]:::dev
            CI[".github/workflows/"]:::cfg
        end
        subgraph "Scripts & Configuration"
            Tasks["tasks.py"]:::dev
            ReleaseNotes["scripts/release_notes_generator.py"]:::dev
            Config_py["pyproject.toml"]:::cfg
            Config_mk["Makefile"]:::cfg
            Config_tox["tox.ini"]:::cfg
        end
    end

    Examples --> DataLoader
    UnitTests --> DataTransformer
    UnitTests --> SynthBase
    IntegrationTests --> CLI
    IntegrationTests --> Demo

    click CLI "https://github.com/sdv-dev/ctgan/blob/main/ctgan/__main__.py"
    click Demo "https://github.com/sdv-dev/ctgan/blob/main/ctgan/demo.py"
    click DataLoader "https://github.com/sdv-dev/ctgan/blob/main/ctgan/data.py"
    click DataTransformer "https://github.com/sdv-dev/ctgan/blob/main/ctgan/data_transformer.py"
    click Sampler "https://github.com/sdv-dev/ctgan/blob/main/ctgan/data_sampler.py"
    click SynthBase "https://github.com/sdv-dev/ctgan/blob/main/ctgan/synthesizers/base.py"
    click CTGANImpl "https://github.com/sdv-dev/ctgan/blob/main/ctgan/synthesizers/ctgan.py"
    click TVAEImpl "https://github.com/sdv-dev/ctgan/blob/main/ctgan/synthesizers/tvae.py"
    click Examples "https://github.com/sdv-dev/ctgan/tree/main/examples/"
    click UnitTests "https://github.com/sdv-dev/ctgan/tree/main/tests/unit/"
    click IntegrationTests "https://github.com/sdv-dev/ctgan/tree/main/tests/integration/"
    click CI "https://github.com/sdv-dev/ctgan/tree/main/.github/workflows/"
    click Tasks "https://github.com/sdv-dev/ctgan/blob/main/tasks.py"
    click ReleaseNotes "https://github.com/sdv-dev/ctgan/blob/main/scripts/release_notes_generator.py"
    click Config_py "https://github.com/sdv-dev/ctgan/blob/main/pyproject.toml"
    click Config_mk "https://github.com/sdv-dev/ctgan/tree/main/Makefile"
    click Config_tox "https://github.com/sdv-dev/ctgan/blob/main/tox.ini"

    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef dev fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef cfg fill:#FFFF99,stroke:#000,stroke-width:1px;
```
