Skip to main content

Synthetic Data Generation with optional Differential Privacy

Project description

Gretel Synthetics

Gobs the cat
An open source synthetic data library from

gretel-synthetics workflows Documentation Status GitHub PyPI Python Downloads GitHub stars Slack


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

By default, we do not install Tensorflow via pip as many developers and cloud services such as Google Colab are running customized versions for their hardware. If you wish to pip install Tensorflow along with gretel-synthetics, use the [tf] commands below instead.

pip install -U .                     # Do not install Tensorflow by default (assuming you have built a distro for your hardware)
pip install -U -e ".[tf]"            # Install a pinned version of Tensorflow"


pip install gretel-synthetics        # Do not install Tensorflow by default (assuming you have built a distro for your hardware)
pip install gretel-synthetics[tf]    # Install a pinned version of Tensorflow


$ pip install jupyter
$ jupyter notebook

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


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.


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 paramters 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.

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gretel-synthetics-0.15.2.tar.gz (970.1 kB view hashes)

Uploaded Source

Built Distribution

gretel_synthetics-0.15.2-py3-none-any.whl (47.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page