diffix/syndiffix

## 概述 **SynDiffix** 是一个开源工具，用于从结构化数据生成统计准确且高度匿名的合成数据。与现有的开源和专有商业方案相比，SynDiffix 具有以下优势： - 准确度高出数倍 - 机器学习效能相当或更好 - 运行速度相当或更快 - 匿名性更强 SynDiffix 采用**多表**方式生成合成数据。SynDiffix 不尝试生成包含原始数据所有列的单一表格，而是设计为允许生成任意数量的、列数较少的表格，同时仍能保持强匿名性。这种方法的优势在于，列数较少的表格在相应列上更加准确。 为了获得最佳性能，只应合成特定分析任务所需的列。例如，如果只需要一个单列度量，则应合成仅包含该列的表格。如果需要测量两列之间的相关性，则应创建一个仅包含这两列的合成表格。 ## 用途 合成数据有两个主要用例： 1. 描述性分析（直方图、热力图、列相关性、基本统计如计数、平均值、标准差等） 2. 机器学习（构建模型） 虽然 SynDiffix 服务于这两个用例，但它在描述性分析方面特别出色。描述性分析的质量是其他合成数据产品的数倍。 ## 安装 使用 `pip` 安装： `pip install syndiffix` 需要 Python 3.10 或更高版本。 ## 使用方法 SynDiffix 有两种使用方式： - 生成单独的合成表格。 - 生成"SynDiffix blob"。SynDiffix blob 的用户可以从 blob 中生成任何表格。 当数据所有者知道用户需要哪些表格时，适合使用单独表格方式。当数据所有者不知道用户需要哪些表格时，适合使用 blob 方式，但用户必须安装 SynDiffix 才能从 blob 生成表格。blob 方式也适用于数据所有者必须删除原始数据的情况，例如为了符合 GDPR。数据所有者随后可以从 blob 中生成任何合成表格。 **Blob 限制：** 当前 blob 在超过约 10 列时扩展性不佳。此限制将在未来版本中修复。 ### 生成单独的表格 要生成单独的表格，请使用 `Synthesizer` 类。使用方法可以很简单： ``` from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original).sample() ``` 这将创建一个新的 Pandas dataframe，其中包含合成数据，具有与输入 dataframe 相同的列数和几乎相同的行数。 脚本 [example_simple.py](example_simple.py) 提供了一个简单的 CSV 输入输出示例，用于生成合成数据。 ### 生成和使用 SynDiffix blob 要生成 SynDiffix blob，请使用 `SyndiffixBlobBuilder` 类： ``` from syndiffix import SyndiffixBlobBuilder sbb = SyndiffixBlobBuilder(blob_name='blob_name', path_to_dir='blob_path') sbb.write(df_raw=df_orig) ``` 这将在目录 `blob_path` 中创建一个名为 `blob_name.sdxblob.zip` 的 SynDiffix blob。该 blob 可以安全地分发给公众。 要使用 SynDiffix blob，请使用 `SyndiffixBlobReader` 类： ``` from syndiffix import SyndiffixBlobReader sbr = SyndiffixBlobReader(blob_name='blob_name', path_to_dir='blob_path') # Make a dataframe with columns col1 and col2 df_syn = sbr.read(columns=['col1', 'col2']) ``` blob 的使用示例可在 `blob_tester.py` 中找到。 ### 最大化数据准确性 通过仅合成分析任务所需的列来最大化数据准确性。例如，如果目标是了解两列 `col1` 和 `col2` 之间的相关性，则只应合成这些列： ``` # Individual table usage from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original[['col1','col2']]).sample() ``` ``` # Blob usage from syndiffix import SyndiffixBlobReader sbr = SyndiffixBlobReader(blob_name='blob_name', path_to_dir='blob_path') df_synthetic = sbr.read(columns=['col1', 'col2']) ``` 有关示例，请参阅[教程笔记本](docs/tutorial.ipynb)。请注意，无论从任何给定列生成多少个不同的合成 dataframe，匿名性都会得到保持。 ### 最大化相对于给定目标列的机器学习效能 当用例是为给定目标列 'your_target_col' 生成机器学习模型时，目标列的指定方式如下： ``` # Individual table usage from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original, target_column='your_target_col') ``` ``` # Blob usage from syndiffix import SyndiffixBlobReader sbr = SyndiffixBlobReader(blob_name='blob_name', path_to_dir='blob_path') df_synthetic = sbr.read(target_column='your_target_col') ``` 请注意，不指定目标列时，指定目标列后目标列的预测模型质量会更好。如果需要为不同的目标列创建模型，则应创建一个单独的合成 dataframe。有关示例，请参阅[教程笔记本](docs/tutorial.ipynb)。 ### 管理受保护实体 *受保护实体*是 dataframe 中被保护其匿名性的东西。通常这一个人，但也可以是一个人使用的设备或任何其他东西。 如果每个受保护实体有多行（例如事件或时间序列数据），则必须有一个列来标识受保护实体，并且此列必须在其自己的 dataframe 中传递。否则会损害匿名性。 如果标识受保护实体的列是 'pid_col'，则按以下方式指定： ``` df_pid = df_original[["pid_col"]] df_original = df_original.drop(columns=["pid_col"]) # Individual table usage from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original, pids=df_pid).sample() # Blob usage from syndiffix import SyndiffixBlobBuilder sbb = SyndiffixBlobBuilder(blob_name='blob_name', path_to_dir='blob_path') sbb.write(df_raw=df_original, pids=df_pid) ``` 请注意，从 `df_original` 中删除 'pid_col' 并不是严格必要的，但这样做可以获得稍高质量的数据和更快的执行时间。 一个 dataframe 可以有多个受保护实体。例如，银行交易中的发送者和接收者，或医疗数据库中的患者和医生。如果标识两个受保护实体的列是 'pid_col1' 和 'pid_col2'，则按以下方式指定： ``` pid_columns = ["pid_col1", "pid_col2"] df_pids = df_original[pid_columns] df_original = df_original.drop(columns=pid_columns) # Individual table usage from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original, pids=df_pid).sample() # Blob usage from syndiffix import SyndiffixBlobBuilder sbb = SyndiffixBlobBuilder(blob_name='blob_name', path_to_dir='blob_path') sbb.write(df_raw=df_original, pids=df_pid) ``` ### 声明具有"安全"（公开已知）值的列 数据集中的列通常包含公开已知的值。这些值不需要被隐藏。可以使用 `value_safe_columns` 参数声明此类列。此参数适用于所有数据类型。原始列中的值只会出现在相应的合成数据列中。（对于具有极高精度的浮点数，例如 15 位或更多小数位，合成数据值将与原始数据非常接近。） ``` # Individual table usage from syndiffix import Synthesizer df_synthetic = Synthesizer(df_original, value_safe_columns=['safe_col1', 'safe_col2']).sample() # Blob usage from syndiffix import SyndiffixBlobBuilder sbb = SyndiffixBlobBuilder(blob_name='blob_name', path_to_dir='blob_path') sbb.write(df_raw=df_original, value_safe_columns=['safe_col1', 'safe_col2']) ``` ### 其他参数 有多种参数可以控制 SynDiffix 的运行方式。具体说明见[此处](docs/parameters.md)。 ### 附加信息 [时间序列笔记本](docs/time-series.ipynb) 提供了如何从时间序列数据获取准确统计数据的示例。[聚类笔记本](docs/clustering.ipynb) 提供了如何控制底层聚类算法的示例。 算法的逐步说明可在[此处](docs/algorithm.md)找到。 缝合函数有一个 API。它主要用于测试和开发目的。说明见[此处](docs/stitching-api.md)。 描述 SynDiffix 设计、性能和匿名属性的论文可在 [ArXiv](https://arxiv.org/abs/2311.09628) 上找到。 每个维度的范围在内部称为 interval（由 `Interval` 类处理），以避免与原生 Python `range` API 发生潜在命名冲突。 开发说明可在[此处](docs/development.md) 找到。

标签：Apex, ETL, JavaCC, ProjectDiscovery, Python, 合成数据生成, 多表数据处理, 差分隐私, 数据保护, 数据匿名化, 数据科学, 无后门, 机器学习, 结构化数据, 统计准确性, 统计分析, 网络安全, 资源验证, 逆向工具, 隐私保护