Metadata-Version: 2.1
Name: synthyverse
Version: 0.1.1
Summary: Synthetic data generation and evaluation library
Home-page: https://github.com/synthyverse/synthyverse
Author: Jim Achterberg, Saif Ul Islam, Zia Ur Rehman
Author-email: 
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: arf
Requires-Dist: pandas; extra == "arf"
Requires-Dist: arfpy; extra == "arf"
Provides-Extra: bn
Requires-Dist: pandas; extra == "bn"
Requires-Dist: synthcity; extra == "bn"
Requires-Dist: opacus==1.5.3; extra == "bn"
Provides-Extra: cdtd
Requires-Dist: pandas; extra == "cdtd"
Requires-Dist: torch; extra == "cdtd"
Requires-Dist: torch-ema; extra == "cdtd"
Requires-Dist: scikit-learn; extra == "cdtd"
Requires-Dist: numpy; extra == "cdtd"
Requires-Dist: einops; extra == "cdtd"
Requires-Dist: tqdm; extra == "cdtd"
Provides-Extra: ctabgan
Requires-Dist: pandas; extra == "ctabgan"
Requires-Dist: numpy; extra == "ctabgan"
Requires-Dist: torch; extra == "ctabgan"
Requires-Dist: scikit-learn; extra == "ctabgan"
Requires-Dist: dython; extra == "ctabgan"
Requires-Dist: scipy; extra == "ctabgan"
Provides-Extra: ctgan
Requires-Dist: pandas; extra == "ctgan"
Requires-Dist: ctgan==0.10.0; extra == "ctgan"
Provides-Extra: eval
Requires-Dist: torch; extra == "eval"
Requires-Dist: pandas; extra == "eval"
Requires-Dist: numpy; extra == "eval"
Requires-Dist: scikit-learn; extra == "eval"
Requires-Dist: xgboost; extra == "eval"
Requires-Dist: sdmetrics; extra == "eval"
Provides-Extra: full
Requires-Dist: torch-ema; extra == "full"
Requires-Dist: zero; extra == "full"
Requires-Dist: opacus==1.5.3; extra == "full"
Requires-Dist: synthcity; extra == "full"
Requires-Dist: scikit-learn; extra == "full"
Requires-Dist: dython; extra == "full"
Requires-Dist: pandas; extra == "full"
Requires-Dist: sdmetrics; extra == "full"
Requires-Dist: tqdm; extra == "full"
Requires-Dist: tomli-w; extra == "full"
Requires-Dist: category-encoders; extra == "full"
Requires-Dist: mostlyai-engine; extra == "full"
Requires-Dist: xgboost; extra == "full"
Requires-Dist: ctgan==0.10.0; extra == "full"
Requires-Dist: arfpy; extra == "full"
Requires-Dist: numpy; extra == "full"
Requires-Dist: icecream; extra == "full"
Requires-Dist: einops; extra == "full"
Requires-Dist: tomli; extra == "full"
Requires-Dist: realtabformer; extra == "full"
Requires-Dist: torch; extra == "full"
Requires-Dist: scipy; extra == "full"
Provides-Extra: realtabformer
Requires-Dist: pandas; extra == "realtabformer"
Requires-Dist: realtabformer; extra == "realtabformer"
Provides-Extra: tabargn
Requires-Dist: pandas; extra == "tabargn"
Requires-Dist: mostlyai-engine; extra == "tabargn"
Provides-Extra: tabddpm
Requires-Dist: pandas; extra == "tabddpm"
Requires-Dist: synthcity; extra == "tabddpm"
Requires-Dist: opacus==1.5.3; extra == "tabddpm"
Provides-Extra: tabsyn
Requires-Dist: pandas; extra == "tabsyn"
Requires-Dist: torch; extra == "tabsyn"
Requires-Dist: tqdm; extra == "tabsyn"
Requires-Dist: numpy; extra == "tabsyn"
Requires-Dist: scipy; extra == "tabsyn"
Requires-Dist: scikit-learn; extra == "tabsyn"
Requires-Dist: category-encoders; extra == "tabsyn"
Requires-Dist: zero; extra == "tabsyn"
Requires-Dist: icecream; extra == "tabsyn"
Requires-Dist: tomli-w; extra == "tabsyn"
Requires-Dist: tomli; extra == "tabsyn"
Provides-Extra: tvae
Requires-Dist: pandas; extra == "tvae"
Requires-Dist: ctgan==0.10.0; extra == "tvae"

<table align="center" border="0">
<tr>
<td align="center">

<img src="logo/logo.png" alt="Synthyverse logo" width="250" height="auto">

<br/>
<br/>

Welcome to the synthyverse!

An extensive ecosystem for synthetic data generation and evaluation in Python.

_The synthyverse is a work in progress. Please provide any suggestions through a GitHub Issue._

</td>
</tr>
</table>

<div style="clear: both;"></div>

# Features
- 🔧 **Highly modular installation.** Install only those modules which you require to keep your installation lightweight.
- 📚 **Extensive library for synthetic data.** Any generator or metric can be quickly added without dependency conflicts due to synthyverse's modular installation. This allows the synthyverse to host a great amount of generators and evaluation metrics. It also allows the synthyverse to wrap around any existing synthetic data library.
- ⚙️ **Benchmarking module for simplified synthetic data pipelines.** The benchmarking module executes a modular pipeline of synthetic data generation and evaluation. Choose a generator, set of evaluation metrics, and pipeline parameters, and obtain results on synthetic data quality.
- 👷 **Minimal preprocessing required.** All preprocessing is handled under the hood in the synthyverse, so no need for scaling, one-hot encoding, or handling missing values.

# Installation
The synthyverse is unique in its modular installation set-up. To avoid conflicting dependencies, we provide various installation templates. Each template installs only those dependencies which are required to access certain modules. 

Templates provide installation for specific generators, the evaluation module, and more. Install multiple templates to get access to multiple modules of the synthyverse, e.g., multiple generators and evaluation. 

**We strongly advise to only install templates which you require during a specific run. Installing multiple templates gives rise to potential dependency conflicts. Use separate virtual environments across installations.**

**Note that the core installation without any template doesn't install any modules.**

See the [overview of templates](synthyverse/TEMPLATES.md).

### General Installation Template

```bash
pip install synthyverse[template]
```

### Installation Examples
```bash
pip install synthyverse[ctgan]
```

```bash
pip install synthyverse[arf,bn,ctgan,tvae]
```

```bash
pip install synthyverse[ctgan,eval]
```


# Usage

### Synthetic Data Generation
Import desired generator. Note that you can only import generators according to your installed synthyverse template.

See [all available generators](synthyverse/generators/GENERATORS.md).
```python
from synthyverse.generators import ARFGenerator
generator = ARFGenerator(num_trees=20, random_state=0)
```

Fit the generator. For tabular data, also pass which columns are discrete, as these often need to be handled differently than numerical features. If the target column is discrete, it should also be included in the discrete features list. 
```python
from sklearn.datasets import load_breast_cancer
X = load_breast_cancer(as_frame=True).frame
generator.fit(X, discrete_features=["target"])
```

Sample a synthetic dataset.
```python
syn = generator.generate(len(X))
```

### Synthetic Data Evaluation
Choose a set of metrics. Either choose default metrics as a list, or provide them as a dictionary with carefully selected hyperparameters. Add a dash to the metric name to compute various configurations of the same evaluation metric.

See [all available metrics](synthyverse/evaluation/METRICS.md).
```python
metrics = ["mle", "dcr", "similarity"]
metrics={
        "mle-trts": {"train_set": "real"},
        "mle-tstr": {"train_set": "synthetic"},
        "dcr": {"estimates": ["mean", 0.01, 0.05]},
        "similarity":{}
    }
```

Set-up a MetricEvaluator object.

```python
from synthyverse.evaluation import MetricEvaluator

evaluator = MetricEvaluator(
    metrics=metrics,
    discrete_features=["target"],
    target_column="target",
    random_state=seed
)
```

Evaluate the metrics with respect to the synthetic data, the training data used to fit the generator, and an independent holdout/test set of real data.

```python
results = evaluator.evaluate(X_train, X_test, syn)
```

### Benchmarking
The benchmarking module performs synthetic data generation and evaluation in a single pipeline. 

Set-up a benchmarking object. Supply the [generator name and its parameters](synthyverse/generators/GENERATORS.md), [evaluation metrics](synthyverse/evaluation/METRICS.md), the number of random train-test splits to fit the generator to, number of random initializations to fit the generator to, the number of synthetic sets to sample for each fitted generator, and the size of the test set.

```python
from synthyverse.benchmark import TabularBenchmark

benchmark = TabularBenchmark(
    generator_name="arf",
    generator_params={"num_trees": 20},
    n_random_splits=3,
    n_inits=3,
    n_generated_datasets=20,
    metrics=["classifier_test", "mle", "dcr"],
    test_size=0.3,
)
```

Run the benchmarking pipeline on a dataset. 
```python
results = benchmark.run(X, target_column="target", discrete_columns=["target"])
```

# Tutorials
- [Tabular Synthetic Data with the synthyverse: Introduction](tutorial.ipynb)
