synthcity

Synthcity provides a wide range of generators categorized by their primary use case and data type. You can choose a generator based on whether you need general-purpose modeling, privacy-preserving features, domain adaptation, or specialized handling for survival analysis, time-series, or images.

Generator Categories:

• General purpose: Standard synthetic data generators like CTGAN, TVAE, GOGGLE, ARF, GReaT, Bayesian Network, Normalizing Flows, and RTVAE.
• Privacy-focused: Generators designed with differential privacy or privacy-preserving mechanisms, including PATEGAN, DP-GAN, PrivBayes, AdsGAN, DECAF, and AIM.
• Domain adaptation: Tools for adapting models to different domains, such as RadialGAN.
• Static Survival Analysis: Specialized for survival data, including SurvivalGAN, SurvivalCTGAN, SurVAE, and Survival NFlows.
• Time-series & Time-Series Survival Analysis: For temporal data, including TimeGAN, FourierFlows, and TimeVAE.
• Images: Generative models specifically for image data, such as ImageCGAN and Image AdsGAN.

The synthcity library provides a wide range of tutorials covering different data modalities and specialized generation tasks. You can find specific guides for:

Core Workflows

• Basic Tabular Data: Getting started with general-purpose generators.
• Plugin Development: How to add a new plugin to the synthcity ecosystem.
• Benchmarking: Evaluating the performance of different generators.

Specialized Data Modalities

• Survival Analysis: Generating data for static survival analysis.
• Time Series: Using probabilistic autoregressive generators, TimeGAN, or FourierFlows, including custom dataset preparation.
• Images: Generating images using Image CGAN or Image AdsGAN.

Advanced Generation Paradigms

• Privacy-Preserving: Generating data with Differential Privacy guarantees using plugins like DECAF, DP-GAN, AdsGAN, PATEGAN, or PrivBayes.
• Domain Adaptation: Using RadialGAN for domain adaptation tasks.

The ValidationMixin is used to integrate validation logic into a model. It allows a model to split data into training and validation sets and evaluate performance using a WeightedMetrics object during training.

Key features:

• Data Splitting: Uses valid_size (a float between 0 and 1) to create a validation set via train_test_split.
• Automatic Validation: When on_epoch_end is triggered, the mixin calls validate(), which generates synthetic data and evaluates it against the validation set, storing the result in self.valid_score.
• Early Stopping Support: The should_stop attribute can be set to True by a callback to halt training.

To use it, your model class should inherit from ValidationMixin and implement the generate(count, cond) method.

from synthcity.utils.callbacks import ValidationMixin
from synthcity.metrics.weighted_metrics import WeightedMetrics
import pandas as pd

class MyModel(ValidationMixin):
    def __init__(self, valid_metric: WeightedMetrics, valid_size: float = 0.2, callbacks=()):
        super().__init__(valid_metric=valid_metric, valid_size=valid_size, callbacks=callbacks)

    def generate(self, count: int, cond=None) -> pd.DataFrame:
        # Implementation for generating synthetic data
        return pd.DataFrame()

    def fit(self, data: pd.DataFrame):
        # Use _set_val_data to prepare the validation set
        train_data = self._set_val_data(data)
        # ... training loop calling on_epoch_begin/end ...
        pass

A Distribution object characterizes the empirical marginal distribution of a feature. It is the base class for all specific data types in the library. Distributions can be initialized using raw data (a pd.Series) or by providing specific parameters (like choices for categorical or low/high for numeric types).

Key capabilities of a Distribution include:

• Sampling: Generating new values using .sample(count) based on a sampling_strategy (e.g., "marginal" or "uniform").
• Constraints: Converting the distribution into a set of Constraints via .as_constraint() to define valid ranges or sets.
• Validation: Checking if a value is within the distribution's support using .has(val) or checking if one distribution is a subset of another using .includes(other).
• Metadata: Retrieving range information via .min() and .max(), or data type via .dtype().

from synthcity.plugins.core.distribution import CategoricalDistribution
import pandas as pd

# Initialize from data
dist = CategoricalDistribution(name="category_col", data=pd.Series(['a', 'a', 'b']))

# Sample values
samples = dist.sample(count=5)

# Check support
print("a" in dist)  # True

Imbalanced Sampling

ImbalancedDatasetSampler uses a weight-based approach. It calculates weights = 1.0 / label_to_count[label]. During iteration, it uses torch.multinomial with these weights to draw samples with replacement. This effectively compensates for class imbalance by making rare classes more likely to be picked.

Conditional Sampling

ConditionalDatasetSampler works by mapping discrete features to a one-hot encoded conditional space.

1. It identifies all discrete features via FeatureInfo.
2. It builds a _categorical_value_to_row_ mapping to quickly find which rows in the original data contain specific category values.
3. It calculates conditional_probs based on the frequency of categories in the dataset.
4. When sample_conditional is called, it selects a discrete column and then selects a category within that column based on the observed category probabilities.

Synthcity provides several generative models designed with Differential Privacy (DP) guarantees. DP aims to add noise to data to preserve statistical properties while preventing the identification of individual data points.

Key concepts:

• epsilon (ε): A measure of privacy loss. A lower ε provides stronger privacy guarantees but typically requires more noise, which may impact data utility.
• delta (δ): Represents the probability that the privacy loss exceeds the ε threshold.

Supported DP models in Synthcity:

• AdsGAN: Uses an identifiability penalty (controlled by lambda_identifiability_penalty).
• PATEGAN: Uses the Private Aggregation of Teacher Ensembles framework.
• PrivBayes: Uses a Bayesian network to learn conditional probabilities from noisy marginals.
• DPGAN: Uses the DP-SGD optimizer for training the discriminator.

Note: PATEGAN, PrivBayes, and DPGAN allow customization of the epsilon parameter.