synthcity

生成和评估合成表格数据的库。

功能

• :key: 易于扩展的可插拔架构。
• :cyclone: 正确性和隐私的几个评估指标。
• :fire: 按类型划分的几个参考模型
  • 通用：基于GAN（AdsGAN、CTGAN、PATEGAN、DP-GAN）、基于VAE（TVAE、RTVAE）、正态化流、贝叶斯网络（PrivBayes、BN）、随机森林（arfpy）、基于LLM（GReaT）。
  • 时间序列和时间序列生存生成器：TimeGAN、FourierFlows、TimeVAE。
  • 静态生存分析：SurvivalGAN、SurVAE。
  • 关注隐私：DECAF、DP-GAN、AdsGAN、PATEGAN、PrivBayes。
  • 域适应：RadialGAN。
  • 图像：Image ConditionalGAN、Image AdsGAN。
• :book: 查看文档！
• :airplane: 查看教程！

请注意：synthcity不处理缺失数据，因此这些值必须首先填充。可以使用HyperImpute来完成此操作。

:rocket: 安装

可以使用以下命令从PyPI安装此库

$ pip install synthcity

或从源代码，使用

$ pip install .

其他库扩展

• 安装带有单元测试支持的库

 pip install synthcity[testing]

• 安装带有GOGGLE支持的库

 pip install synthcity[goggle]

• 安装带有所有扩展的库

 pip install synthcity[all]

:boom: 示例用法

通用数据

• 列出可用的通用生成器

from synthcity.plugins import Plugins

Plugins(categories=["generic", "privacy"]).list()

• 加载并训练一个表格生成器

from sklearn.datasets import load_diabetes
from synthcity.plugins import Plugins

X, y = load_diabetes(return_X_y=True, as_frame=True)
X["target"] = y

syn_model = Plugins().get("adsgan")

syn_model.fit(X)

• 生成新的合成表格数据

syn_model.generate(count = 10)

• 基准测试插件质量

# third party
from sklearn.datasets import load_diabetes

# synthcity absolute
from synthcity.benchmark import Benchmarks
from synthcity.plugins.core.constraints import Constraints
from synthcity.plugins.core.dataloader import GenericDataLoader

X, y = load_diabetes(return_X_y=True, as_frame=True)
X["target"] = y

loader = GenericDataLoader(X, target_column="target", sensitive_columns=["sex"])

score = Benchmarks.evaluate(
    [
        (f"example_{model}", model, {})  # testname, plugin name, plugin args
        for model in ["adsgan", "ctgan", "tvae"]
    ],
    loader,
    synthetic_size=1000,
    metrics={"performance": ["linear_model"]},
    repeats=3,
)
Benchmarks.print(score)

静态生存分析

• 列出针对生存分析的可用的生成器

from synthcity.plugins import Plugins

Plugins(categories=["generic", "privacy", "survival_analysis"]).list()

• 生成新数据

from lifelines.datasets import load_rossi
from synthcity.plugins.core.dataloader import SurvivalAnalysisDataLoader
from synthcity.plugins import Plugins

X = load_rossi()
data = SurvivalAnalysisDataLoader(
    X,
    target_column="arrest",
    time_to_event_column="week",
)

syn_model = Plugins().get("survival_gan")

syn_model.fit(data)

syn_model.generate(count=10)

时间序列

• 列出可用的生成器

from synthcity.plugins import Plugins

Plugins(categories=["generic", "privacy", "time_series"]).list()

• 生成新数据

# synthcity absolute
from synthcity.plugins import Plugins
from synthcity.plugins.core.dataloader import TimeSeriesDataLoader
from synthcity.utils.datasets.time_series.google_stocks import GoogleStocksDataloader

static_data, temporal_data, horizons, outcome = GoogleStocksDataloader().load()
data = TimeSeriesDataLoader(
    temporal_data=temporal_data,
    observation_times=horizons,
    static_data=static_data,
    outcome=outcome,
)

syn_model = Plugins().get("timegan")

syn_model.fit(data)

syn_model.generate(count=10)

图像

注意：用于生成器的架构不是最先进的。对于其他架构，请考虑扩展convnet.py模块中的suggest_image_generator_discriminator_arch方法。

• 列出可用的生成器

from synthcity.plugins import Plugins

Plugins(categories=["images"]).list()

• 生成新数据

from synthcity.plugins import Plugins
from synthcity.plugins.core.dataloader import ImageDataLoader
from torchvision import datasets


dataset = datasets.MNIST(".", download=True)
loader = ImageDataLoader(dataset).sample(100)

syn_model = Plugins().get("image_cgan")

syn_model.fit(loader)

syn_img, syn_labels = syn_model.generate(count=10).unpack().numpy()

print(syn_img.shape)

序列化

• 使用保存/加载方法

from synthcity.utils.serialization import save, load
from synthcity.plugins import Plugins

syn_model = Plugins().get("adsgan")

buff = save(syn_model)
reloaded = load(buff)

assert syn_model.name() == reloaded.name()

• 从磁盘保存和加载模型

from sklearn.datasets import load_diabetes
from synthcity.utils.serialization import save_to_file, load_from_file
from synthcity.plugins import Plugins

X, y = load_diabetes(return_X_y=True, as_frame=True)
X["target"] = y

syn_model = Plugins().get("adsgan", n_iter=10)

syn_model.fit(X)

save_to_file('./adsgan_10_epochs.pkl', syn_model)
reloaded = load_from_file('./adsgan_10_epochs.pkl')

assert syn_model.name() == reloaded.name()

• 使用可序列化接口

from synthcity.plugins import Plugins

syn_model = Plugins().get("adsgan")

buff = syn_model.save()
reloaded = Plugins().load(buff)

assert syn_model.name() == reloaded.name()

📓 教程

• 教程 0：表格数据入门
• 教程 1：编写新的插件
• 教程 2：基准测试模型
• 教程 3：生成生存分析数据
• 教程 4：生成时间序列
• 教程 5：生成具有差分隐私保证的数据
• 教程 6：使用自定义时间序列数据的练习
• 教程 7：图像生成
• 教程 8：超参数优化
• 教程 9：处理缺失数据

🔑 方法

贝叶斯方法

生成对抗网络(GANs)

Variational autoencoders(VAE)

正态化流

图神经网络

扩散模型

随机森林模型

基于LLM的模型

静态生存分析方法

时间序列和时间序列生存分析方法

隐私 & 公平

领域自适应

图像

调试方法

:zap: 评估指标

以下表格包含可用的评估指标

• 合理性检查

• 统计测试

• 合成数据质量

• 隐私度量

准标识符：不是本身唯一标识符的信息片段，但与实体高度相关，可以与其他准标识符结合以创建唯一标识符。

:mag: 合成数据在保真度和隐私之外的用例

以下表格包含已完成的研究项目和论文，它们使用了Synthcity。请自由探索并从中获得灵感，以便在您自己的研究项目中使用Synthcity！

:hammer: 测试

使用以下命令安装测试依赖项

pip install .[testing]

可以使用以下命令执行测试

pytest -vsx

为 Synthcity 做贡献

我们希望使为 Synthcity 做贡献尽可能简单和透明。我们希望与尽可能多的人合作。

开发安装

首先创建一个新环境。建议您使用 conda。这可以通过以下步骤完成

conda create -n your-synthcity-env python=3.9
conda activate your-synthcity-env

Python 版本 3.7、3.8、3.9 和 3.10 都是兼容的，但最好使用您能获得的最新版本，因为某些模型可能不支持较旧的 Python 版本。

要获取带有所有必要依赖项的开发安装，包括代码检查、测试、自动格式化和 pre-commit 等，请运行以下命令

git clone https://github.com/vanderschaarlab/synthcity.git
cd synthcity
pip install -e .[testing]

请检查是否已正确安装了存储库的 pre-commit，通过运行以下命令

pre-commit run --all

这确保您已正确设置以进行贡献，这样您将匹配项目中其余部分的代码风格。这将在下文进行更详细的说明。

我们的开发流程

代码风格

我们相信保持一致的代码风格至关重要。因此，Synthcity 对贡献的代码施加某些规则，如果不符合这些规则，自动化测试将不会通过。贡献被合并的要求之一就是通过这些测试。然而，我们将遵守这种代码风格的方式尽可能简化。首先，在设置开发环境时，在上述步骤中安装了所有必需的库，以生成与 Synthcity 代码风格兼容的代码。其次，这些库都由 pre-commit 触发，所以一旦设置完成，您就无需做任何事情。当您运行 git commit 时，任何强制执行风格的简单更改将自动运行，其他必需的更改将在 stdout 中为您说明，以便您进行检查和修复。

Synthcity 使用 black 和 flake8 代码格式化器来强制在代码库中实施统一的代码风格。无需额外配置（有关高级用法，请参阅 black 文档）。

此外，Synthcity 使用 isort 对导入进行字母排序并分开成部分。

类型提示

Synthcity 完全使用 python 3.7+ 类型提示。这通过静态类型检查器 mypy 来强制执行，它适用于贡献。

测试

要运行测试，您可以使用 pytest（再次，与测试额外一起安装）。以下测试命令非常适合检查您的代码，因为它跳过了运行时间较长的测试。

pytest -vvvsx -m "not slow" --durations=50

但是，可以使用以下命令运行完整的测试套件。

pytest -vvvs  --durations=50

某些插件可能包含在库中作为额外内容，这些插件的相关测试需要单独运行，例如，可以使用以下命令测试 goggle 插件

pytest -vvvs -k goggle --durations=50

拉取请求

我们积极欢迎您的拉取请求。

1. 从 main 分支分叉存储库并创建您的分支。
2. 如果您添加了应进行测试的代码，请以与存储库中已有的相同风格添加测试。
3. 如果您更改了 API，请在 PR 中记录 API 变更。
4. 确保测试套件通过。
5. 确保您的代码通过 pre-commit，这是提交和推送所必需的，如果您已正确安装 pre-commit，它包含在测试额外内容中。

问题

我们使用 GitHub 问题跟踪公共错误。请确保您的描述清晰，并且有足够的说明，以便能够重现问题。

许可证

通过向Synthcity贡献，您同意您的贡献将按照此源代码树的根目录中的LICENSE文件进行许可。因此，您应确保，如果您引入了任何依赖项，它们也应受一个许可证的保护，该许可证允许代码被项目使用，并且与本项目根目录中的许可证兼容。

引用

如果您使用此代码，请引用相关的论文

@misc{https://doi.org/10.48550/arxiv.2301.07573,
  doi = {10.48550/ARXIV.2301.07573},
  url = {https://arxiv.org/abs/2301.07573},
  author = {Qian, Zhaozhi and Cebere, Bogdan-Constantin and van der Schaar, Mihaela},
  keywords = {Machine Learning (cs.LG), Artificial Intelligence (cs.AI), FOS: Computer and information sciences, FOS: Computer and information sciences},
  title = {Synthcity: facilitating innovative use cases of synthetic data in different data modalities},
  year = {2023},
  copyright = {Creative Commons Attribution 4.0 International}
}