synthyverse 0.1.0__tar.gz

synthyverse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jim Achterberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synthyverse-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include requirements/**/*
+include README.md
+include LICENSE
+include logo/*
+include tutorial.ipynb

synthyverse-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.1
+Name: synthyverse
+Version: 0.1.0
+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: 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: ctgan
+Requires-Dist: pandas; extra == "ctgan"
+Requires-Dist: ctgan==0.10.0; extra == "ctgan"
+Requires-Dist: pandas; extra == "ctgan"
+Provides-Extra: arf
+Requires-Dist: pandas; extra == "arf"
+Requires-Dist: arfpy; extra == "arf"
+Requires-Dist: pandas; extra == "arf"
+Provides-Extra: bn
+Requires-Dist: pandas; extra == "bn"
+Requires-Dist: synthcity; extra == "bn"
+Requires-Dist: opacus==1.5.3; extra == "bn"
+Requires-Dist: pandas; extra == "bn"
+Provides-Extra: tvae
+Requires-Dist: pandas; extra == "tvae"
+Requires-Dist: ctgan==0.10.0; extra == "tvae"
+Requires-Dist: pandas; extra == "tvae"
+Provides-Extra: full
+Requires-Dist: sdmetrics; extra == "full"
+Requires-Dist: arfpy; extra == "full"
+Requires-Dist: opacus==1.5.3; extra == "full"
+Requires-Dist: torch; extra == "full"
+Requires-Dist: xgboost; extra == "full"
+Requires-Dist: pandas; extra == "full"
+Requires-Dist: scikit-learn; extra == "full"
+Requires-Dist: numpy; extra == "full"
+Requires-Dist: synthcity; extra == "full"
+Requires-Dist: ctgan==0.10.0; extra == "full"
+
+<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!
+
+The most 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.
+- 📚 **Most 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 the most generators and evaluation metrics out of any 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.
+```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
+
+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)

synthyverse-0.1.0/README.md

@@ -0,0 +1,137 @@
+<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!
+
+The most 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.
+- 📚 **Most 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 the most generators and evaluation metrics out of any 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.
+```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
+
+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)

synthyverse-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

synthyverse-0.1.0/requirements/evaluation/eval.txt

@@ -0,0 +1,6 @@
+torch
+pandas
+numpy
+scikit-learn
+xgboost
+sdmetrics

synthyverse-0.1.0/requirements/generators/arf.txt

@@ -0,0 +1,2 @@
+arfpy
+pandas

synthyverse-0.1.0/requirements/generators/base.txt

@@ -0,0 +1 @@
+pandas

synthyverse-0.1.0/requirements/generators/bn.txt

@@ -0,0 +1,3 @@
+synthcity
+opacus==1.5.3
+pandas

synthyverse-0.1.0/requirements/generators/ctgan.txt

@@ -0,0 +1,2 @@
+ctgan==0.10.0
+pandas

synthyverse-0.1.0/requirements/generators/tvae.txt

@@ -0,0 +1,2 @@
+ctgan==0.10.0
+pandas

synthyverse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synthyverse-0.1.0/setup.py

@@ -0,0 +1,60 @@
+from setuptools import setup, find_packages
+import os
+
+version = "0.1.0"
+
+
+def read_requirements(filename):
+    # Get the directory where setup.py is located
+    setup_dir = os.path.dirname(os.path.abspath(__file__))
+    filepath = os.path.join(setup_dir, "requirements", filename)
+    with open(filepath, "r", encoding="utf-8") as f:
+        return [line.strip() for line in f if line.strip() and not line.startswith("#")]
+
+
+# Define extras dynamically from requirements folder
+base_requirements = read_requirements("generators/base.txt")
+extras = {
+    "eval": read_requirements("evaluation/eval.txt"),
+    "ctgan": base_requirements + read_requirements("generators/ctgan.txt"),
+    "arf": base_requirements + read_requirements("generators/arf.txt"),
+    "bn": base_requirements + read_requirements("generators/bn.txt"),
+    "tvae": base_requirements + read_requirements("generators/tvae.txt"),
+}
+
+# Create a "full" extra that includes all extras
+extras["full"] = []
+for key in extras:
+    extras["full"].extend(extras[key])
+extras["full"] = list(set(extras["full"]))
+
+core_dependencies = []  # Always-installed dependencies
+
+setup(
+    name="synthyverse",
+    version=version,
+    description="Synthetic data generation and evaluation library",
+    author="Jim Achterberg, Saif Ul Islam, Zia Ur Rehman",
+    author_email=" ",
+    packages=find_packages(),
+    install_requires=core_dependencies,
+    extras_require=extras,
+    python_requires=">=3.8",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/synthyverse/synthyverse",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)

synthyverse-0.1.0/synthyverse/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

synthyverse-0.1.0/synthyverse/benchmark/__init__.py

@@ -0,0 +1 @@
+from .benchmark import TabularBenchmark

synthyverse-0.1.0/synthyverse/benchmark/benchmark.py

@@ -0,0 +1,88 @@
+from sklearn.model_selection import train_test_split
+from ..evaluation.eval import MetricEvaluator
+from ..utils.utils import get_generator, free_up_memory
+from ..utils.reproducibility import set_seed
+import pandas as pd
+from time import time
+
+
+class TabularBenchmark:
+    def __init__(
+        self,
+        generator_name: str = "arf",
+        generator_params: dict = {},
+        n_random_splits: int = 1,
+        n_inits: int = 1,
+        n_generated_datasets: int = 1,
+        metrics: list = ["classifier_test", "mle", "dcr"],
+        test_size: float = 0.3,
+    ):
+
+        self.generator_name = generator_name
+        self.generator_params = generator_params
+        self.n_random_splits = n_random_splits
+        self.n_inits = n_inits
+        self.n_generated_datasets = n_generated_datasets
+        self.metrics = metrics
+        self.test_size = test_size
+
+    def run(self, X: pd.DataFrame, target_column: str, discrete_columns: list):
+
+        results = {}
+        generator_ = get_generator(self.generator_name)
+        for split_i in range(self.n_random_splits):
+            results[f"split_{split_i}"] = {}
+
+            # split data according to current seed
+            stratify = None
+            if target_column in discrete_columns:
+                stratify = X[target_column]
+            X_train, X_test = train_test_split(
+                X, stratify=stratify, test_size=self.test_size, random_state=split_i
+            )
+            X_train, X_test = X_train.reset_index(drop=True), X_test.reset_index(
+                drop=True
+            )
+
+            for init_i in range(self.n_inits):
+                results[f"split_{split_i}"][f"init_{init_i}"] = {}
+                set_seed(init_i)
+                generator = generator_(random_state=init_i, **self.generator_params)
+                start_time = time()
+                generator.fit(X_train, discrete_columns)
+                results[f"split_{split_i}"][f"init_{init_i}"]["training_time"] = (
+                    time() - start_time
+                )
+
+                # potentially generate multiple datasets
+                for generated_dataset_i in range(self.n_generated_datasets):
+                    results[f"split_{split_i}"][f"init_{init_i}"][
+                        f"generated_dataset_{generated_dataset_i}"
+                    ] = {}
+                    start_time = time()
+                    X_syn = generator.generate(len(X))
+                    results[f"split_{split_i}"][f"init_{init_i}"][
+                        f"generated_dataset_{generated_dataset_i}"
+                    ] = {}
+                    results[f"split_{split_i}"][f"init_{init_i}"][
+                        f"generated_dataset_{generated_dataset_i}"
+                    ]["inference_time"] = (time() - start_time)
+                    start_time = time()
+                    evaluator = MetricEvaluator(
+                        metrics=self.metrics,
+                        discrete_features=discrete_columns,
+                        target_column=target_column,
+                        random_state=init_i,
+                    )
+                    metric_results = evaluator.evaluate(X_train, X_test, X_syn)
+                    results[f"split_{split_i}"][f"init_{init_i}"][
+                        f"generated_dataset_{generated_dataset_i}"
+                    ]["evaluation_time"] = (time() - start_time)
+                    results[f"split_{split_i}"][f"init_{init_i}"][
+                        f"generated_dataset_{generated_dataset_i}"
+                    ].update(metric_results)
+
+                    # free up memory for next iteration
+                    free_up_memory()
+
+        return results

synthyverse-0.1.0/synthyverse/evaluation/__init__.py

@@ -0,0 +1 @@
+from .eval import MetricEvaluator