privacy-tuner 1.0.0

A privacy-preserving data publishing tool with parameter optimization

Privacy Tuner

Privacy Tuner 是一个通用的隐私保护数据发布工具。它通过智能参数搜索，在用户指定的隐私预算和效用目标约束下，自动寻找最优的数据扰动参数（如噪声尺度、泛化粒度、采样比例等），从而在保护隐私的同时最大化数据的实用性。最终输出净化后的数据集、最优参数组合以及可视化报告。

特性

• 模块化设计：支持可插拔的隐私机制、风险度量、效用评估和优化器，方便扩展与定制。
• 多种隐私模型：内置差分隐私（拉普拉斯、高斯）、经验风险（KNN 成员推断攻击）等，并预留接口支持 k-匿名等传统方法。
• 多种数据类型：表格数据原生支持，并预留文本、图像数据加载接口。
• 自动参数搜索：提供网格搜索、贝叶斯优化、遗传算法等多种优化器，自动探索参数空间。
• 可解释性：生成风险-效用曲线和自然语言报告，帮助理解参数选择的理由。
• 结果可复现：支持保存最优参数、扰动数据和报告，便于审计和二次使用。

安装

通过 PyPI 安装（推荐）

pip install privacy-tuner

从源码安装

如果你已经获取了项目源码（例如从本地目录或压缩包），可以在项目根目录下执行以下命令进行安装：

cd privacy_tuner   # 进入项目根目录
pip install -e .

注：-e 选项表示以可编辑模式安装，方便修改代码后立即生效。如果不需要修改源码，也可以去掉 -e 进行普通安装。

快速开始

以下示例使用 Adult 数据集，演示完整的隐私保护流程。

import numpy as np
from sklearn.datasets import fetch_openml
from privacy_tuner.input import CSVLoader
from privacy_tuner.core.mechanisms import CopulaMechanism
from privacy_tuner.core.risk import EmpiricalRiskMeter
from privacy_tuner.core.utility import TSTRClassifier
from privacy_tuner.core.optimizers import GridSearchOptimizer
from privacy_tuner.output import CSVExporter, SimpleReporter

# 加载数据
adult = fetch_openml(data_id=1590, as_frame=True)
df = adult.data.select_dtypes(include=[np.number]).dropna()
y = (adult.target == '>50K').astype(int).values
data = np.column_stack([df.values, y])

# 定义组件
mechanism = CopulaMechanism()               # 生成合成数据
risk_meter = EmpiricalRiskMeter()           # 使用 KNN 成员推断风险
utility = TSTRClassifier(target_column=-1)  # 使用分类准确率作为效用
optimizer = GridSearchOptimizer()           # 网格搜索参数

# 设置参数空间和风险约束
param_space = {
    'sampling_ratio': [0.5, 1.0, 2.0],
    'noise_scale': [0.0, 0.1, 0.5]
}
risk_constraint = (0.0, 1.0)  # 允许风险 ≤ 1.0（风险值越小越安全）

# 执行搜索
best_params, best_utility, best_risk = optimizer.search(
    original_data=data,
    mechanism=mechanism,
    risk_meter=risk_meter,
    utility_evaluator=utility,
    param_space=param_space,
    risk_constraint=risk_constraint
)

# 输出结果
print(f"最优参数: {best_params}")
print(f"最优效用 (准确率): {best_utility:.4f}")
print(f"对应风险: {best_risk:.4f}")

# 生成最终扰动数据并导出
final_perturbed = mechanism.apply(data, best_params)
CSVExporter().export(final_perturbed, "output/perturbed.csv")
SimpleReporter().generate(
    original_info={"shape": data.shape},
    mechanism=mechanism,
    search_results={
        "best_params": best_params,
        "best_utility": best_utility,
        "best_risk": best_risk
    },
    output_path="output/report.txt"
)

运行上述代码后，你将在 output/ 目录下得到扰动后的数据文件 perturbed.csv 和一份简要报告 report.txt。

更多示例请参考项目中的 examples 目录。

核心模块

模块	描述	内置实现
输入层	数据加载与特征分析	CSVLoader, FeatureAnalyzer
隐私机制	数据扰动算法	CopulaMechanism, LaplaceMechanism, GaussianMechanism
风险度量	隐私风险评估	EmpiricalRiskMeter, DPRisk
效用评估	数据实用性评估	TSTRClassifier, QueryError, ClusteringSilhouette
优化器	参数自动搜索	GridSearchOptimizer, BayesianOptimizer, GeneticOptimizer
输出层	结果导出与报告	CSVExporter, HTMLReporter
可视化	图表绘制	Visualizer

目录结构

privacy_tuner/
├── privacy_tuner/               # 主代码包
│   ├── input/                   # 数据加载与特征分析
│   ├── core/                    # 核心模块（机制、风险、效用、优化器）
│   ├── output/                  # 数据导出与报告生成
│   ├── visualization/           # 可视化工具
│   ├── validation/              # 验证与案例库
│   └── examples/                # 使用示例
├── tests/                       # 单元测试
├── docs/                        # 文档
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── MANIFEST.in
├── setup.py
└── requirements.txt

开发与贡献

欢迎参与开发！请阅读 CONTRIBUTING.md 了解环境搭建、代码风格和测试流程。

本地开发环境

# 进入项目根目录
cd privacy_tuner

# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate   # Linux/Mac
venv\Scripts\activate      # Windows

# 安装开发依赖
pip install -e .
pip install pytest flake8 black

运行测试

pytest tests/

许可证

本项目采用 MIT 许可证。