# 系统发育提取 v4 使用说明

## 功能特性

v4版本是完整版，支持：
1. ✅ 从PDF提取基础信息
2. ✅ 自动从Europe PMC API获取补充材料
3. ✅ 解析Excel提取完整分组
4. ✅ 智能合并PDF和补充材料数据
5. ✅ 自动计算并提升confidence score

---

## 安装依赖

```bash
# 安装pandas和openpyxl
pip3 install pandas openpyxl --break-system-packages
```

---

## 使用方法

### 基本用法

```bash
python extract_phylogeny_v4.py <pdf路径> --pmcid <PMCID>
```

### 示例

#### 1. 番茄P450（需要补充材料）

```bash
python extract_phylogeny_v4.py \
    "/home/xia-lab/gene-family-mas-v2/paper/ceshi/番茄p450基因家族BMCgenomics2020.pdf" \
    --pmcid PMC6367802
```

**预期结果**:
- 初始confidence: 40/100
- 下载补充材料后: 100/100
- 提取到52个分组

#### 2. 短柄AP2（不需要补充材料）

```bash
python extract_phylogeny_v4.py \
    "/home/xia-lab/gene-family-mas-v2/paper/ceshi/短柄AP2s12864-016-2968-8.pdf" \
    --pmcid PMC4986339
```

**预期结果**:
- 初始confidence: 100/100
- 跳过补充材料下载
- 直接提取成功

#### 3. 指定输出目录

```bash
python extract_phylogeny_v4.py \
    "论文.pdf" \
    --pmcid PMC1234567 \
    --output-dir ./my_results
```

---

## 输出文件

运行后会生成以下文件：

```
evaluation/auto_results/
├── {论文名}_v4.json           # 完整结果（包含所有分组详情）
├── {论文名}_v4_report.json    # 简化报告
├── {论文名}_supplementary.zip # 下载的补充材料（如果有）
└── {PMCID}_MOESM1_ESM.xlsx   # 解压的Excel文件（如果有）
```

---

## 结果字段说明

### 完整结果 (_v4.json)

```json
{
  "pdf_name": "番茄p450基因家族BMCgenomics2020",
  "pmcid": "PMC6367802",
  "gene_family": "P450",
  "species": "Solanum lycopersicum",
  "total_genes": 233,
  "total_groups": 52,
  "groups": {
    "Group_71": ["CYP71D184", "CYP71D185", ...],
    "Group_72": ["CYP72A51", "CYP72A172", ...],
    ...
  },
  "confidence_score": 100,
  "confidence_level": "high",
  "source": "pdf+supplementary",
  "supplementary_file": "12864_2019_5483_MOESM1_ESM.xlsx",
  "validation": {
    "gene_coverage": 1.0,
    "group_coverage": 1.0
  }
}
```

### 简化报告 (_v4_report.json)

```json
{
  "pdf_name": "番茄p450基因家族BMCgenomics2020",
  "pmcid": "PMC6367802",
  "confidence_score": 100,
  "confidence_level": "high",
  "gene_family": "P450",
  "species": "Solanum lycopersicum",
  "total_genes": 233,
  "total_groups": 52,
  "source": "pdf+supplementary",
  "has_supplementary": true
}
```

---

## 工作流程

```
输入: PDF + PMCID
    ↓
步骤1: 从PDF提取基础信息
    - 基因家族名
    - 物种名
    - 总基因数
    ↓
步骤2: 计算初始置信度
    - 如果 >= 85: 直接输出
    - 如果 < 85: 继续步骤3
    ↓
步骤3: 获取补充材料
    - 从Europe PMC API下载ZIP
    - 解压提取Excel
    - 解析Excel获取分组
    ↓
步骤4: 合并数据
    - PDF基础信息
    + Excel分组详情
    ↓
步骤5: 重新计算置信度
    - 通常从40提升到100
    ↓
输出: 完整结果
```

---

## 支持的期刊

| 期刊 | PMCID格式 | 补充材料可用性 |
|:---|:---|:---|
| BMC Genomics | PMC6367802 | ✅ 可用 |
| BMC Plant Biology | PMCxxxxxxx | ✅ 可用 |
| Frontiers in Plant Science | PMCxxxxxxx | ✅ 可用 |
| PLOS ONE | PMCxxxxxxx | ✅ 可用 |
| Nature Communications | PMCxxxxxxx | ✅ 可用 |

---

## 常见问题

### Q1: 如何找到PMCID？

**方法1**: 从PubMed页面查找
- 访问 https://pubmed.ncbi.nlm.nih.gov/
- 搜索论文标题
- 在页面右侧找到 "PMCID"

**方法2**: 从论文PDF
- 通常在第一页或致谢部分
- 格式: PMC6367802

**方法3**: 从DOI
- 访问 https://www.ncbi.nlm.nih.gov/pmc/
- 搜索DOI

### Q2: 下载很慢怎么办？

补充材料ZIP文件通常较大（10-100MB），下载时间：
- 快: 10-30秒
- 慢: 1-2分钟

如果超过2分钟，可能是网络问题，建议：
1. 重试
2. 手动下载（见下方）

### Q3: 没有PMCID怎么办？

可以不提供PMCID：
```bash
python extract_phylogeny_v4.py "论文.pdf"
```

但这样无法获取补充材料，confidence可能较低。

### Q4: 如何手动下载补充材料？

如果自动下载失败，可以手动：

1. 访问: https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/
2. 找到 "Supplementary data" 部分
3. 下载 "Additional file 1"
4. 放到输出目录，命名为 `{PMCID}_MOESM1_ESM.xlsx`

---

## 技术细节

### Europe PMC API

```
端点: https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/supplementaryFiles
方法: GET
返回: ZIP文件（包含所有补充材料）
```

### 自动触发条件

```python
if confidence_score < 85 and pmcid:
    fetch_supplementary_files()
```

### 置信度计算

```python
score = 0
if total_genes > 0:      score += 20
if gene_family:          score += 10
if species:              score += 10
if groups:               score += 30
if coverage >= 0.95:     score += 30
```

---

## 版本对比

| 功能 | v2 | v3 | v4 |
|:---|:---|:---|:---|
| PDF提取 | ✅ | ✅ | ✅ |
| Confidence分数 | ❌ | ✅ | ✅ |
| Basis字段 | ❌ | ✅ | ✅ |
| 自动获取补充材料 | ❌ | ❌ | ✅ |
| Excel解析 | ❌ | ❌ | ✅ |
| 完整分组提取 | ⚠️ | ⚠️ | ✅ |
| 番茄P450成功率 | 40% | 40% | 100% |

---

## 下一步计划

1. **批量处理**: 支持一次处理多篇论文
2. **缓存机制**: 避免重复下载
3. **更多期刊**: 支持非PMC论文
4. **可视化**: 生成系统发育树

---

*版本: v4.0*
*更新日期: 2026-03-30*
*作者: xialab的幸运星 🧬🤖*