• Stars
    star
    563
  • Rank 78,589 (Top 2 %)
  • Language
    Python
  • License
    Other
  • Created over 4 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Synthetic data generators for structured and unstructured text, featuring differentially private learning.

Gretel Synthetics

Gobs the Gretel.ai cat
A permissive synthetic data library from Gretel.ai

Documentation Status CLA assistant PyPI Python Downloads GitHub stars Discord

Documentation

Try it out now!

If you want to quickly discover gretel-synthetics, simply click the button below and follow the tutorials!

Open in Colab

Check out additional examples here.

Getting Started

This section will guide you through installation of gretel-synthetics and dependencies that are not directly installed by the Python package manager.

Dependency Requirements

By default, we do not install certain core requirements, the following dependencies should be installed external to the installation of gretel-synthetics, depending on which model(s) you plan to use.

  • Tensorflow: Used by the LSTM model, we recommend version 2.11.x
  • Torch: Used by Timeseries DGAN and ACTGAN (for ACTGAN, Torch is installed by SDV), we recommend version 2.0
  • SDV (Synthetic Data Vault): Used by ACTGAN, we recommend version 0.17.x

These dependencies can be installed by doing the following:

pip install tensorflow==2.11 # for LSTM
pip install sdv<0.18 # for ACTGAN
pip install torch==2.0 # for Timeseries DGAN

To install the actual gretel-synthetics package, first clone the repo and then...

pip install -U .

or

pip install gretel-synthetics

then...

$ pip install jupyter
$ jupyter notebook

When the UI launches in your browser, navigate to examples/synthetic_records.ipynb and get generating!

If you want to install gretel-synthetics locally and use a GPU (recommended):

  1. Create a virtual environment (e.g. using conda)
$ conda create --name tf python=3.9
  1. Activate the virtual environment
$ conda activate tf
  1. Run the setup script ./setup-utils/setup-gretel-synthetics-tensorflow24-with-gpu.sh

The last step will install all the necessary software packages for GPU usage, tensorflow=2.8 and gretel-synthetics. Note that this script works only for Ubuntu 18.04. You might need to modify it for other OS versions.

Timeseries DGAN Overview

The timeseries DGAN module contains a PyTorch implementation of a DoppelGANger model that is optimized for timeseries data. Similar to tensorflow, you will need to manually install pytorch:

pip install torch==1.13.1

This notebook shows basic usage on a small data set of smart home sensor readings.

ACTGAN Overview

ACTGAN (Anyway CTGAN) is an extension of the popular CTGAN implementation that provides some additional functionality to improve memory usage, autodetection and transformation of columns, and more.

To use this model, you will need to manually install SDV:

pip install sdv<0.18

Keep in mind that this will also install several dependencies like PyTorch that SDV relies on, which may conflict with PyTorch versions installed for use with other models like Timeseries DGAN.

The ACTGAN interface is a superset of the CTGAN interface. To see the additional features, please take a look at the ACTGAN demo notebook in the examples directory of this repo.

LSTM Overview

This package allows developers to quickly get immersed with synthetic data generation through the use of neural networks. The more complex pieces of working with libraries like Tensorflow and differential privacy are bundled into friendly Python classes and functions. There are two high level modes that can be utilized.

Simple Mode

The simple mode will train line-per-line on an input file of text. When generating data, the generator will yield a custom object that can be used a variety of different ways based on your use case. This notebook demonstrates this mode.

DataFrame Mode

This library supports CSV / DataFrames natively using the DataFrame "batch" mode. This module provided a wrapper around our simple mode that is geared for working with tabular data. Additionally, it is capabable of handling a high number of columns by breaking the input DataFrame up into "batches" of columns and training a model on each batch. This notebook shows an overview of using this library with DataFrames natively.

Components

There are four primary components to be aware of when using this library.

  1. Configurations. Configurations are classes that are specific to an underlying ML engine used to train and generate data. An example would be using TensorFlowConfig to create all the necessary parameters to train a model based on TF. LocalConfig is aliased to TensorFlowConfig for backwards compatability with older versions of the library. A model is saved to a designated directory, which can optionally be archived and utilized later.

  2. Tokenizers. Tokenizers convert input text into integer based IDs that are used by the underlying ML engine. These tokenizers can be created and sent to the training input. This is optional, and if no specific tokenizer is specified then a default one will be used. You can find an example here that uses a simple char-by-char tokenizer to build a model from an input CSV. When training in a non-differentially private mode, we suggest using the default SentencePiece tokenizer, an unsupervised tokenizer that learns subword units (e.g., byte-pair-encoding (BPE) [Sennrich et al.]) and unigram language model [Kudo.]) for faster training and increased accuracy of the synthetic model.

  3. Training. Training a model combines the configuration and tokenizer and builds a model, which is stored in the designated directory, that can be used to generate new records.

  4. Generation. Once a model is trained, any number of new lines or records can be generated. Optionally, a record validator can be provided to ensure that the generated data meets any constraints that are necessary. See our notebooks for examples on validators.

Utilities

In addition to the four primary components, the gretel-synthetics package also ships with a set of utilities that are helpful for training advanced synthetics models and evaluating synthetic datasets.

Some of this functionality carries large dependencies, so they are shipped as an extra called utils. To install these dependencies, you may run

pip install gretel-synthetics[utils]

For additional details, please refer to the Utility module API docs.

Differential Privacy

Differential privacy support for our TensorFlow mode is built on the great work being done by the Google TF team and their TensorFlow Privacy library.

When utilizing DP, we currently recommend using the character tokenizer as it will only create a vocabulary of single tokens and removes the risk of sensitive data being memorized as actual tokens that can be replayed during generation.

There are also a few configuration options that are notable such as:

  • predict_batch_size should be set to 1
  • dp should be enabled
  • learning_rate, dp_noise_multiplier, dp_l2_norm_clip, and dp_microbatches can be adjusted to achieve various epsilon values.
  • reset_states should be disabled

Please see our example Notebook for training a DP model based on the Netflix Prize dataset.

More Repositories

1

awesome-synthetic-data

πŸ“– A curated list of resources dedicated to synthetic data
106
star
2

gretel-blueprints

Public blueprints for data use cases
Jupyter Notebook
68
star
3

gretel-python-client

The Gretel Python Client allows you to interact with the Gretel REST API.
Python
52
star
4

synthetic-data-genomics

Proof of concept code from Gretel.ai and Illumina using generative neural networks to create synthetic versions of mouse genotype and phenotype data.
Jupyter Notebook
34
star
5

trainer

Simple interface to synthesize complex and highly dimensional datasets using Gretel APIs.
Python
29
star
6

gdpr-helpers

Generative models to automatically anonymize data to meet GDPR & CCPA standards.
Python
29
star
7

public_research

Where Gretel published notebooks and code for blog posts
Jupyter Notebook
18
star
8

gretel-tools

General tools for machine learning, data engineering, and more!
Jupyter Notebook
14
star
9

FluentBitLogging

Logging AWS EKS infrastructure with Fluent Bit.
HCL
10
star
10

contact-tracing-experiment

Pythonic implementation of Apple + Google's contact tracing proposal
Python
8
star
11

multi-table

Notebook and code to synthesize relational databases such as Postgres and Mysql.
Jupyter Notebook
8
star
12

gretel-mlops

Python
7
star
13

doppelganger-torch

PyTorch implementation of DoppelGANger. This library has been moved to the gretel-synthetics package. Find the latest version here: https://github.com/gretelai/gretel-synthetics/tree/master/src/gretel_synthetics/timeseries_dgan
Jupyter Notebook
6
star
14

gretel-airflow-pipelines

Runbooks for running Gretel on Apache Airflow
Python
6
star
15

fun-with-synthetic-data

A collection of notebooks full of whimsy and fun to show all of the cool things you can do with Gretel Synthetics
Jupyter Notebook
6
star
16

safe-location-density

Python
5
star
17

rediscover-2020-joinability

Sample code for Redis Conf talk on Joinability at scale using HyperLogLog
Python
3
star
18

gretel-tuner

πŸŽ›οΈ Hyperparameter tuning with Optuna and the Gretel SDK
Python
2
star
19

navigator-helpers

Navigator Helpers
Python
1
star
20

support

Repo for reporting bugs, feature requests, general feedback, etc to the Gretel.ai team
1
star
21

gretel-hybrid

Resources to help with setting up and running Gretel Hybrid
HCL
1
star