Metadata-Version: 2.4
Name: privacy-tuner
Version: 1.1.0
Summary: A privacy-preserving data publishing tool with parameter optimization
Home-page: 
Author: Sanqian
Author-email: 2770316004@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: scikit-optimize>=0.9.0
Requires-Dist: copulas>=0.9.0
Requires-Dist: tqdm>=4.64.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: diffprivlib>=0.6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Privacy Tuner

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

## 特性

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

## 安装

### 通过 PyPI 安装（推荐）

```bash
pip install privacy-tuner
```

### 从源码安装

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

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

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


## 快速开始

### Python API

```python
from privacy_tuner import protect
import numpy as np

# 假设你有一个数据数组，最后一列是标签
data = np.random.randn(100, 5)  # 100个样本，5个特征
labels = (data[:, 0] > 0).astype(int)
data = np.column_stack([data, labels])

# 一键保护数据
result = protect(data, epsilon=1.0, output_dir='output')

print(f"最优参数: {result['best_params']}")
print(f"效用 (准确率): {result['best_utility']:.4f}")
print(f"风险: {result['best_risk']:.4f}")
```

### 命令行工具（安装后使用）

```bash
privacy-tuner your_data.csv --epsilon 1.0 --output results
```
更多示例请参考项目中的 [examples](./privacy_tuner/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](CONTRIBUTING.md) 了解环境搭建、代码风格和测试流程。

### 本地开发环境

```bash
# 进入项目根目录
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
```

### 运行测试

```bash
pytest tests/
```

## 许可证

本项目采用 [MIT 许可证](LICENSE)。
