Metadata-Version: 2.4
Name: scm-policy-analysis
Version: 1.0.0
Summary: 合成控制法政策效应分析系统 — 评估宏观经济政策对A股市场影响的自动化因果推断工具
Author: SCM Policy Analysis Contributors
License: MIT
Project-URL: Homepage, https://github.com/Z7X2C7/scm-policy-analysis
Project-URL: Repository, https://github.com/Z7X2C7/scm-policy-analysis
Project-URL: Documentation, https://github.com/Z7X2C7/scm-policy-analysis#readme
Keywords: scm,synthetic-control,causal-inference,a-share,policy-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3
Requires-Dist: numpy>=1.21
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.11
Requires-Dist: scikit-learn>=1.0
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.64
Requires-Dist: python-dateutil>=2.8
Requires-Dist: plotly>=5.9
Requires-Dist: loguru>=0.6
Requires-Dist: click>=8.1
Requires-Dist: scipy>=1.7
Requires-Dist: pillow>=9.0
Requires-Dist: openpyxl>=3.0
Requires-Dist: baostock>=0.5
Provides-Extra: gui
Requires-Dist: PyQt6>=6.5; extra == "gui"
Provides-Extra: extra
Requires-Dist: tushare>=1.3; extra == "extra"
Requires-Dist: akshare>=1.8; extra == "extra"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: black>=23; extra == "dev"
Requires-Dist: isort>=5; extra == "dev"
Requires-Dist: pre-commit>=3; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# 合成控制法政策效应分析系统

[![CI](https://github.com/Z7X2C7/scm-policy-analysis/actions/workflows/ci.yml/badge.svg)](https://github.com/Z7X2C7/scm-policy-analysis/actions)
![Python](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-62_passing-brightgreen)

评估宏观经济政策对 A 股市场影响的自动化因果推断工具——基于**合成控制法（Synthetic Control Method）**。

```bash
pip install . && scm-analysis --user-file data/user_input.csv
```

---

## 快速上手

### 安装

```bash
git clone https://github.com/Z7X2C7/scm-policy-analysis && cd scm-policy-analysis

# 基础安装（CLI）
pip install .

# 带 GUI 桌面端
pip install .[gui]

# 开发模式（含测试/格式化工具）
pip install -e ".[dev]"
pre-commit install
```

### 准备数据

在 `data/user_input.csv` 中写入政策和股票信息，格式如下：

| policy_name | policy_date | treatment_stock_code | treatment_stock_name | donor_stock_code | donor_stock_name |
|---|---|---|---|---|---|
| 政策名称 | 2024-01-15 | 002594.SZ | 比亚迪 | 601238.SH | 广汽集团 |

- **`policy_name`** — 政策名称（必填）
- **`policy_date`** — 政策发布日期（必填）
- **`treatment_stock_code` / `treatment_stock_name`** — 处理股票，至少填一项
- **`donor_stock_code` / `donor_stock_name`** — 供体池股票，**可选**
  - 提供 → 全量使用，不做截断，SCM 算法自动分配权重
  - 留空 → 系统调用 **DeepSeek API** 按同行业规则自动补充

已有示例文件可直接使用：

```bash
cp examples/sample_input.csv data/user_input.csv
```

### 运行

**命令行 (CLI)：**

```bash
# 使用默认数据文件
scm-analysis

# 指定文件和分析参数
scm-analysis --user-file data/my_policy.csv --pre-months 18 --post-months 12

# 强制刷新缓存
scm-analysis --force-refresh --no-cache
```

**桌面应用 (GUI)：**

```bash
python -m src.gui
# 或
python run_gui.py
```

### 查看结果

结果保存在 `output/` 目录：

- `output/report.html` — 完整分析报告
- `output/result/` — 政策效应汇总 CSV
- `output/charts/` — Matplotlib / Plotly 图表
- `output/placebo/` — 安慰剂检验结果

---

## 核心流程

```
用户 CSV  →  数据校验  →  提取/补充供体池
                              ↓
                       baostock 行情
                              ↓
                       月度综合指标
                              ↓
                        SCM 权重求解
                              ↓
                   空间安慰剂检验 + 时间安慰剂检验
                              ↓
                         HTML 报告
```

### 合成控制法

`src/sc_optimizer.py` 基于 `scipy.optimize.minimize` 求解权重：

- **约束**：权重非负、求和为 1、每只股票权重 ≤ 0.5
- **政策效应**：处理单元实际值 − 合成控制值
- **MSPE**：政策前均方预测误差，衡量拟合质量

### 双重安慰剂检验

| 类型 | 方法 | 目的 |
|------|------|------|
| **空间安慰剂** | 将每只供体股票假想为处理单元，重新跑 SCM | 真实效应是否显著大于随机效应 |
| **时间安慰剂** | 将政策日期向前平移 3/6 个月，重新跑 SCM | 效应是否确实由该政策事件导致 |

详见 [架构文档](docs/architecture.md)。

---

## 目录结构

```
├── src/                  # 源代码
│   ├── config.py         # 全局配置（环境变量驱动）
│   ├── sc_optimizer.py   # SCM 核心优化（SLSQP + NNLS 备选）
│   ├── synthetic_control.py  # 高层调度 + 留一法检验
│   ├── data_fetcher.py   # baostock 行情获取（带缓存）
│   ├── data_processor.py # 日度→月度指标计算
│   ├── weight_calculator.py  # 4 指标等权 → composite_indicator
│   ├── data_validator.py # 数据校验 + AI 补全
│   ├── policy_generator.py  # 政策-股票映射表生成
│   ├── donor_pool_cleaner.py  # 供体池清洗
│   ├── post_treatment_placebo.py  # 时间安慰剂检验
│   ├── visualization.py  # 报告与图表
│   ├── placebo_visualization.py  # Nature 期刊风格图表
│   └── gui/              # PyQt6 桌面应用
├── tests/                # 62 个 pytest 测试
├── docs/                 # 文档
├── main.py               # CLI 入口
├── run_gui.py            # GUI 入口
├── pyproject.toml        # 包配置
└── data/                 # 数据与缓存
```

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（供体补充/数据补全） | 空（跳过 AI 功能） |
| `DEEPSEEK_MODEL` | 模型名 | `deepseek-chat` |
| `LOG_LEVEL` | 日志级别 | `INFO` |

可复制 `.env.example` 为 `.env` 填写。核心分析功能**完全不需要** API Key，仅可选的数据补全和供体推荐依赖 AI。

## 开发

```bash
pip install -e ".[dev]"    # 安装开发依赖
pre-commit install         # 安装 pre-commit 钩子
pytest tests/ -v           # 运行 62 个测试
ruff check src/            # 代码检查
black src/                 # 自动格式化
```

## 技术栈

- **SCM 求解**: `scipy.optimize.minimize` (SLSQP) + NNLS 备选
- **行情数据**: baostock (免费 A 股数据)
- **可视化**: Matplotlib / Plotly / Seaborn
- **AI 辅助**: DeepSeek API（可选）
- **桌面端**: PyQt6
- **质量工具**: pytest / ruff / black / isort / mypy / pre-commit

## 许可证

MIT License
