# PyPDA

**Repository Path**: coding_playground/pypda

## Basic Information

- **Project Name**: PyPDA
- **Description**: PyPDA是一个集成了蛋白质序列分析、PDB文件处理和UniProt数据检索功能的综合工具，旨在为生物信息学研究提供便捷的蛋白质数据分析解决方案。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: 0.8.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-01
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyPDA: 蛋白质分析综合工具

PyPDA是一个集成了蛋白质序列分析、PDB文件处理和UniProt数据检索功能的综合工具，旨在为生物信息学研究提供便捷的蛋白质数据分析解决方案。

## 🚀 功能特点

- **🎯 序列分析**：从UniProt批量获取蛋白质序列、提取特定区域、执行突变分析和序列比对，支持在指定位置插入/删除片段
- **🏗️ PDB处理**：从RCSB静态文件服务并行下载mmCIF结构文件（支持断点续传与失败重试）、提取配体信息并分类管理
- **📋 结构信息提取**：自动从PDB文件中提取PDB ID、结构标题、实验方法和分辨率范围，生成结构化报告
- **🧪 分子结构相似性**：基于SMILES计算小分子与PDB结构中配体的相似性（Tanimoto系数，配体视角Top N排名），支持在已下载结构文件的文件夹上直接离线计算，辅助分子对接
- **📊 UniProt数据检索**：获取蛋白质详细注释信息并生成结构化报告
- **🎯 OpenTargets数据查询**：查询疾病药物关联、靶点药物关联、基因疾病关联和疾病靶点关联信息
- **🧬 KEGG信号通路分析**：查询基因参与的信号通路、下载通路图、搜索通路，支持JSON和CSV双格式输出
- **🤝 PPI网络分析**：基于STRING数据库查询蛋白质互作网络，支持单基因扩展和基因列表交集两种模式，输出节点/边CSV及网络摘要
- **💊 ChEMBL化合物检索**：根据靶点名称查询活性化合物、基于SMILES进行全库相似性搜索，或两者组合在靶点化合物中按相似度精准过滤（RDKit本地计算）
- **🗂️ target 聚合下载**：输入蛋白名 / 基因名 / UniProt ID，一次下载 7 类数据库数据（UniProt、序列与结构域、PDB、OpenTargets、KEGG、STRING PPI、ChEMBL）到固定子目录
- **🔍 增强的基因搜索功能**：实现从精确到宽松的递进式查询策略，支持灵活的基因名和蛋白质名匹配，提高检索成功率
- **⚡ 并行计算支持**：采用多线程和多进程并行处理，显著提升大规模数据处理速度
- **📁 统一管理**：所有结果文件和下载zip文件统一存储在`result/`目录下

## 📦 安装方法

### 前提条件

- Python 3.8+
- 所需依赖库：参见requirements.txt

### 安装步骤

1. 克隆或下载本项目到本地
2. 安装依赖包：

```bash
pip install -r requirements.txt
```

1. 配置文件设置：
   - `exclude_residues.ini`：定义需要排除的残基
   - `config.ini`：配置文件路径

## 🎯 使用方法

### 命令行使用

#### 基本命令格式

```bash
python pypda.py <工具> <命令> [参数]
```

#### 2.1 序列分析工具 (`seq`)

用于蛋白质序列的获取、提取、突变和比对分析。

##### 2.1.1 获取蛋白质序列和结构域信息 (`fetch`)

从UniProt批量获取蛋白质序列和结构域信息，支持增强的搜索策略，提高检索成功率

```bash
python pypda.py seq fetch <genes> [output_dir]
```

- **参数**：
  - `genes`: 要下载的基因名称，用空格分隔（例如：BRCA1 TP53 EGFR）
  - `output_dir`: 输出目录，默认值为`result/protein_sequences/基因名_YYYYMMDD_HHMMSS`

**增强的搜索功能**：

- 实现从精确到宽松的递进式查询策略（gene\_exact → gene → 一般搜索）
- 支持灵活的基因名和蛋白质名匹配（精确匹配和包含匹配）
- 多结果筛选，提高匹配准确度
- 完善的错误处理和日志记录

**示例**：

```bash
python pypda.py seq fetch BRCA1 TP53 EGFR
```

即使是非标准或难以匹配的基因名（如MOGT2、MOGT3）也能成功检索

##### 2.1.2 提取序列区域 (`extract`)

从FASTA文件中提取指定位置的氨基酸序列

```bash
python pypda.py seq extract <fasta_file> <start> <end> [--output_dir <目录>]
```

- **参数**：
  - `fasta_file`: 输入FASTA文件路径
  - `start`: 起始位置（1-based）
  - `end`: 结束位置（1-based）
  - `--output_dir`: 输出目录，默认值为输入文件所在目录

**示例**：

```bash
python pypda.py seq extract protein.fasta 10 50 --output_dir ./extract_result
```

##### 2.1.3 执行序列突变 (`mutate`)

对蛋白质序列执行定点突变

```bash
python pypda.py seq mutate <fasta_file> --pos <位置列表> --aa <氨基酸列表> [--output_dir <目录>]
```

- **参数**：
  - `fasta_file`: 输入FASTA文件路径
  - `--pos`: 突变位置列表（空格分隔）
  - `--aa`: 对应位置的新氨基酸（空格分隔）
  - `--output_dir`: 输出目录，默认值为输入文件所在目录

**示例**：

```bash
python pypda.py seq mutate protein.fasta --pos 15 23 --aa A K --output_dir ./mutate_result
```

##### 2.1.4 插入序列片段 (`insert`)

在蛋白质序列的指定位置之前插入一段或多段氨基酸序列

```bash
python pypda.py seq insert <fasta_file> --at <位置列表> --seq <片段列表> [--output_dir <目录>]
```

- **参数**：
  - `fasta_file`: 输入FASTA文件路径
  - `--at`: 插入位置列表（1-based，空格分隔），位置N表示插到第N位之前，取值为序列长度+1时追加到末尾
  - `--seq`: 对应位置待插入的氨基酸片段（单字母，空格分隔）
  - `--output_dir`: 输出目录，默认值为输入文件所在目录

**说明**：

- 多个插入操作的坐标均相对**原始序列**，无需手动计算前面插入带来的偏移
- 待插入片段自动转为大写，不做氨基酸字母合法性校验（可插入接头序列或非标准残基）
- 输出文件名以 `ins{位置}{片段}` 标记，例如 `protein_ins15GGSG_ins40K.fasta`

**示例**：

```bash
# 在第15位前插入柔性连接子 GGSG，并在第40位前插入 K
python pypda.py seq insert protein.fasta --at 15 40 --seq GGSG K --output_dir ./insert_result
```

##### 2.1.5 删除序列片段 (`delete`)

删除蛋白质序列中指定区间（两端均包含）的氨基酸

```bash
python pypda.py seq delete <fasta_file> --start <起始列表> --end <结束列表> [--output_dir <目录>]
```

- **参数**：
  - `fasta_file`: 输入FASTA文件路径
  - `--start`: 删除区间起始位置列表（1-based，包含，空格分隔）
  - `--end`: 对应区间的结束位置列表（1-based，包含，空格分隔）
  - `--output_dir`: 输出目录，默认值为输入文件所在目录

**说明**：

- 多个删除操作的坐标均相对**原始序列**，无需手动计算前面删除带来的偏移
- 区间重叠时保留起始位置最靠前（同起点则更长）的一个，其余跳过并给出警告
- 输出文件名以 `del{起始}-{结束}` 标记，例如 `protein_del20-35_del50-60.fasta`

**示例**：

```bash
# 删除第20-35位和第50-60位
python pypda.py seq delete protein.fasta --start 20 50 --end 35 60 --output_dir ./delete_result
```

##### 2.1.6 序列比对分析 (`align`)

比较多个蛋白质序列的同源性

```bash
python pypda.py seq align <fasta_files>
```

- **参数**：
  - `fasta_files`: 多个FASTA文件路径（空格分隔）

**示例**：

```bash
python pypda.py seq align protein1.fasta protein2.fasta protein3.fasta
```

#### 2.2 PDB文件处理工具 (`pdb`)

用于PDB文件的下载、配体提取和分类管理，以及基于小分子SMILES的结构相似性计算。PDB ID 通过 RCSB Search API 按基因名检索，结构文件直接从 RCSB 静态文件服务（`files.rcsb.org`）下载。

##### 2.2.1 下载PDB文件并分析配体 (`fetch`)

根据蛋白质名称搜索并下载相关PDB结构文件，提取配体信息并进行分类管理。

```bash
python pypda.py pdb fetch <protein_name> [output_dir] [--smiles <smiles>]
```

- **参数**：
  - `protein_name`: 蛋白质名称或基因名称（例如：BRCA1, TP53, EGFR）
  - `output_dir`: 输出目录，默认值为`result/pdb_output/蛋白质名_YYYYMMDD_HHMMSS`
  - `--smiles`: 可选，小分子SMILES字符串，用于计算与PDB结构中配体的结构相似性

**示例**：

```bash
# 基本用法：使用蛋白质名称搜索并下载PDB文件
python pypda.py pdb fetch BRCA1

# 高级用法：下载PDB文件并计算结构相似性
python pypda.py pdb fetch HDAC1 --smiles "CC(=O)N(C)C(=O)N1CCC(CC1)C(C)C"  # 示例SMILES字符串
```

**下载说明**：

- 结构文件取自 `https://files.rcsb.org/download/{PDB ID}.cif`，即 RCSB 的完整 deposited mmCIF 条目
- 默认 8 线程并发下载；单条失败会自动退避重试（最多 3 次），最终失败的 ID 写入输出目录的 `download_failed.txt`
- 已存在的 `{PDB ID}.cif` 会直接跳过，因此下载中断后**重跑同一命令即可断点续传**，只补齐缺失条目
- 该地址仅覆盖真实 PDB 条目；计算模型 ID（如 `AF_xxx`）会返回 404 并记入 `download_failed.txt`

##### 2.2.2 口袋分析 (`analyze`)

对指定文件夹下的PDB或CIF文件进行口袋分析，基于ProLIF检测蛋白质-配体间的相互作用类型（氢键、疏水接触、π-π堆积、盐桥等）。

```bash
python pypda.py pdb analyze <folder_path> [--output_dir <目录>]
```

- **参数**：
  - `folder_path`: 包含PDB或CIF文件的文件夹路径
  - `--output_dir`: 输出目录，默认值为输入文件夹相同目录

**输出文件**：
- `pocket_analysis.md`：口袋分析结果，按文件→配体→交互类型三级结构展示
- `pocket_analysis_errors.log`：分析失败记录（若有）

> **兼容性说明**：含负残基编号（如表达标签 ASP-1）或超长配体名（超过3字符，如糖链配体 `A1IS8`）的CIF文件会自动规范化后分析，报告中仍显示原始配体名。

**示例**：

```bash
# 基本用法
python pypda.py pdb analyze result/pdb_output/BRCA1_20240101_120000

# 指定输出目录
python pypda.py pdb analyze result/pdb_output/BRCA1_20240101_120000 --output_dir ./analysis_result
```

##### 2.2.3 结构相似性计算 (`similarity`)

对已下载好的文件夹中的结构文件（CIF、PDB或两种混合）计算与输入SMILES的结构相似性并排序配体，**不下载任何结构文件**（仅补下缺失的配体化学信息JSON）。

```bash
python pypda.py pdb similarity <folder_path> --smiles <smiles> [--output_dir <目录>] [--top_n <数量>]
```

- **参数**：
  - `folder_path`: 包含结构文件 (.cif/.pdb) 的文件夹路径，会递归扫描子目录（如 `with_ligand/`、`no_ligand/`）
  - `--smiles`: 输入小分子的SMILES字符串，用于计算与结构文件中配体的结构相似性
  - `--output_dir`: 输出目录，默认值为与输入文件夹相同
  - `--top_n`: 返回前N个最相似的配体，默认10

**说明**：

- 相似性基于RDKit Morgan指纹（radius=2, 2048 bit）的Tanimoto系数，从结构文件提取的配体通过RCSB CCD获取Canonical SMILES
- 输出为**配体视角**排名：每个配体的全部对应结构文件ID一并列出；每个结构文件的最终分数取其所有配体中的最大Tanimoto分数

**示例**：

```bash
# 基本用法：对已有KRas结果目录计算相似性
python pypda.py pdb similarity result/pdb_output/KRas_20260910_132149 --smiles "CC(=O)OC1=CC=CC=C1C(=O)O"

# 指定输出目录与返回数量
python pypda.py pdb similarity ./structures --smiles "CC(=O)N(C)C(=O)N1CCC(CC1)C(C)C" --output_dir ./sim_result --top_n 5
```

#### 2.3 OpenTargets数据查询工具 (`opentargets`)

用于查询OpenTargets数据库，获取疾病药物关联、基因疾病关联和疾病靶点关联信息。

##### 2.3.1 查询疾病相关药物 (`disease-drugs`)

查询特定疾病的相关药物信息

```bash
python pypda.py opentargets disease-drugs [--disease-name <疾病名称>] [--disease-id <EFO ID>] [--limit <数量>] [--format <格式>]
```

- **参数**：
  - `--disease-name`: 疾病名称（例如：breast cancer）
  - `--disease-id`: 疾病的EFO ID（例如：MONDO_0007254）
  - `--limit`: 返回结果数量限制，默认100
  - `--format`: 输出格式（json/csv/all），默认json

**示例**：

```bash
python pypda.py opentargets disease-drugs --disease-name "lung cancer" --limit 50 --format csv
```

##### 2.3.2 查询靶点相关药物 (`target-drugs`)

查询特定靶点的相关药物信息

```bash
python pypda.py opentargets target-drugs <gene_name> [--format <格式>]
```

- **参数**：
  - `gene_name`: 基因名称（例如：EGFR）
  - `--format`: 输出格式（json/csv/all），默认json

**示例**：

```bash
python pypda.py opentargets target-drugs EGFR --format csv
```

##### 2.3.3 查询基因关联疾病 (`target-associations`)

查询特定基因关联的疾病信息

```bash
python pypda.py opentargets target-associations <gene_name> [--limit <数量>] [--format <格式>]
```

- **参数**：
  - `gene_name`: 基因名称（例如：TP53）
  - `--limit`: 返回结果数量限制，默认100
  - `--format`: 输出格式（json/csv/all），默认json

**示例**：

```bash
python pypda.py opentargets target-associations EGFR --limit 50 --format csv
```

##### 2.3.4 查询疾病关联靶点 (`disease-associations`)

查询特定疾病关联的靶点信息

```bash
python pypda.py opentargets disease-associations [--disease-name <疾病名称>] [--disease-id <EFO ID>] [--limit <数量>] [--format <格式>]
```

- **参数**：
  - `--disease-name`: 疾病名称（例如：diabetes）
  - `--disease-id`: 疾病的EFO ID（例如：EFO_0010164）
  - `--limit`: 返回结果数量限制，默认100
  - `--format`: 输出格式（json/csv/all），默认json

**示例**：

```bash
python pypda.py opentargets disease-associations --disease-name "breast cancer" --limit 50 --format csv
```

#### 2.4 KEGG信号通路分析工具 (`kegg`)

用于查询KEGG数据库，获取基因参与的信号通路信息并下载通路图。

##### 2.4.1 查询基因参与的信号通路 (`gene-pathways`)

查询特定基因参与的所有信号通路，并下载对应的通路图

```bash
python pypda.py kegg gene-pathways <gene_name> [output_dir]
```

- **参数**：
  - `gene_name`: 基因名称（例如：TP53）
  - `output_dir`: 输出目录，默认值为`result/kegg_output/基因名_YYYYMMDD_HHMMSS`

**输出文件**：
- `基因名_pathways.json`：信号通路列表（JSON格式）
- `基因名_pathways.csv`：信号通路列表（CSV格式，Excel兼容）
- `pathway_images/`：信号通路图目录（PNG格式）

**示例**：

```bash
python pypda.py kegg gene-pathways TP53
```

##### 2.4.2 下载信号通路图 (`download-pathway`)

根据信号通路ID下载通路图

```bash
python pypda.py kegg download-pathway <pathway_id> [output_dir]
```

- **参数**：
  - `pathway_id`: 信号通路ID（例如：hsa04110）
  - `output_dir`: 输出目录，默认值为`result/kegg_output/通路ID_YYYYMMDD_HHMMSS`

**示例**：

```bash
python pypda.py kegg download-pathway hsa04110
```

##### 2.4.3 搜索信号通路 (`search-pathway`)

根据名称搜索信号通路

```bash
python pypda.py kegg search-pathway <pathway_name> [output_dir]
```

- **参数**：
  - `pathway_name`: 信号通路名称关键词（例如：cancer）
  - `output_dir`: 输出目录（可选）

**示例**：

```bash
python pypda.py kegg search-pathway cancer
```

#### 2.5 UniProt数据处理工具 (`uniprot`)

用于从UniProt数据库获取蛋白质注释信息并生成分析报告。

##### 2.5.1 获取UniProt数据并生成报告 (`fetch`)

从UniProt API获取蛋白质数据并生成JSON和Markdown报告

```bash
python pypda.py uniprot fetch <accession> [output_dir]
```

- **参数**：
  - `accession`: 蛋白质名称或基因名称（例如：TP53）
  - `output_dir`: 输出目录，默认值为`result/uniprot_reports/基因名_YYYYMMDD_HHMMSS`

**示例**：

```bash
python pypda.py uniprot fetch TP53
```

##### 2.5.2 分析现有UniProt数据文件 (`analyze`)

分析本地已有的UniProt蛋白质信息JSON文件，提取关键数据并生成Markdown格式的分析报告。

```bash
python pypda.py uniprot analyze <file>
```

- **参数**：
  - `file`: 要分析的UniProt蛋白质信息JSON文件路径

**示例**：

```bash
python pypda.py uniprot analyze result/uniprot_reports/TP53_20240101_120000/TP53_20240101_120000.json
```

#### 2.6 PPI网络分析工具 (`ppi`)

基于STRING数据库查询蛋白质互作网络，支持单基因扩展和基因列表交集两种模式。

##### 2.6.1 查询蛋白质互作网络 (`--target`)

自动检测输入类型：若输入为基因名则获取该基因的一阶互作网络；若输入为文件路径则查询列表中基因两两之间的互作。

```bash
python pypda.py ppi --target <target> [--species <TaxID>] [--confidence <阈值>] [--max-neighbors <数量>] [--output-dir <目录>]
```

- **参数**：
  - `--target`: 基因名（如TP53）或基因列表文件路径（每行一个基因，`#` 开头为注释）（必填）
  - `--species`: 物种TaxID，默认9606（智人）
  - `--confidence`: 置信度阈值（0-1），默认0.7
  - `--max-neighbors`: 最多邻居数（仅单基因模式有效），默认50
  - `--output-dir`: 输出目录，默认值为`result/ppi_output/<名称>_YYYYMMDD_HHMMSS`

**输出文件**：
- `network.json`：STRING API原始响应
- `nodes.csv`：节点列表（node_id, display_name, preferred_name）
- `edges.csv`：边列表（source, target, score）
- `summary.md`：网络统计摘要（节点数、边数、平均度、Top-5高连接节点）

**示例**：

```bash
# 单基因扩展模式：查询TP53的一阶互作网络
python pypda.py ppi --target TP53

# 基因列表交集模式：查询文件中基因两两之间的互作
python pypda.py ppi --target gene_list.txt --confidence 0.9

# 指定物种和最大邻居数
python pypda.py ppi --target EGFR --species 9606 --max-neighbors 100
```

#### 2.7 ChEMBL化合物检索工具 (`chembl`)

查询ChEMBL数据库，支持根据靶点名称检索活性化合物、基于SMILES进行结构相似性搜索，以及两者组合的精准筛选。

`--target` 与 `--smiles` 两个参数不互斥，可单独使用或同时使用，工具会自动选择对应模式：

| 参数组合 | 模式 | 说明 |
| --- | --- | --- |
| `--target` | 靶点化合物查询 | 查询该靶点的活性数据及对应化合物详情 |
| `--smiles` | 全库相似性搜索 | 在ChEMBL全库中按Tanimoto相似度搜索 |
| `--target` + `--smiles` | 靶点化合物相似性过滤 | 先查靶点化合物，再用RDKit本地计算与查询SMILES的相似度，按 `--threshold` 过滤并降序排序 |

```bash
python pypda.py chembl [--target <靶点名>] [--smiles <SMILES>] [--threshold <阈值>] [--limit <数量>] [--output-dir <目录>]
```

- **参数**：
  - `--target`: 靶点名称（基因名或UniProt ID），如 EGFR、TP53、P00533。与 `--smiles` 至少提供一个
  - `--smiles`: 查询分子的SMILES字符串，用于结构相似性搜索
  - `--threshold`: Tanimoto相似度阈值（0-100），默认70。涉及相似性计算时生效（全库搜索或组合模式）
  - `--limit`: 最多返回的化合物数量，默认100
  - `--output-dir`: 输出目录，默认值为`result/chembl_output/<名称>_YYYYMMDD_HHMMSS`

> **注意**：组合模式（同时提供 `--target` 和 `--smiles`）需要安装 RDKit（`pip install rdkit`），用于本地计算分子指纹与Tanimoto相似度。

**输出文件**：
- `<名称>_results.json`：化合物数据（JSON格式）
- `<名称>_results.csv`：化合物数据（CSV格式，Excel兼容）

其中 `<名称>` 按模式自动确定：靶点查询为靶点名（如 `EGFR`），全库相似性搜索为 `similar`，组合模式为 `<靶点名>_similar`（如 `EGFR_similar`）。组合模式的结果额外包含 `similarity` 字段。

**示例**：

```bash
# 1. 靶点化合物查询：查询EGFR靶点的活性化合物
python pypda.py chembl --target EGFR

# 限制返回50条结果
python pypda.py chembl --target EGFR --limit 50

# 使用UniProt ID查询
python pypda.py chembl --target P00533

# 2. 全库相似性搜索：搜索阿司匹林的相似分子（默认阈值70%）
python pypda.py chembl --smiles "CC(=O)OC1=CC=CC=C1C(=O)O"

# 指定相似度阈值80%，限制返回20条
python pypda.py chembl --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" --threshold 80 --limit 20

# 3. 组合模式：在EGFR靶点化合物中筛选与阿司匹林相似度≥70%的化合物（按相似度降序）
python pypda.py chembl --target EGFR --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" --threshold 70
```

#### 2.8 聚合下载工具 (`target`)

一次性聚合下载多个数据库数据。输入蛋白名、基因名或 UniProt ID，自动解析基因符号，并将 7 类数据库的数据按数据库命名拆分到固定的子目录中。

```bash
python pypda.py target <name> [--confidence <阈值>] [--max-neighbors <数量>] [--out-root <目录>] [--chembl-limit <数量>]
```

- **参数**：
  - `name`: 蛋白名 / 基因名 / UniProt ID（例如：EGFR、TP53、P00533）
  - `--confidence`: PPI 置信度阈值（0-1），默认 0.7
  - `--max-neighbors`: PPI 最多邻居数，默认 50
  - `--out-root`: 输出根目录，默认 `result`
  - `--chembl-limit`: ChEMBL 靶点化合物最多返回条数，默认 100

**下载的 7 类数据**：

| 子目录 | 数据库 | 下载内容 |
| --- | --- | --- |
| `uniprot` | UniProt | 蛋白质数据（JSON）及注释分析报告（Markdown） |
| `sequence` | UniProt | 蛋白质序列（FASTA）与结构域信息（Markdown） |
| `pdb` | RCSB PDB | PDB 结构文件（mmCIF）及配体信息分类管理 |
| `opentargets` | OpenTargets | 基因-疾病关联、基因-药物关联 |
| `kegg` | KEGG | 基因参与的信号通路信息及通路图 |
| `ppi` | STRING | 一阶蛋白质互作网络（节点/边 CSV 及摘要） |
| `chembl` | ChEMBL | 靶点化合物的 ID、结构（canonical_smiles）、靶点、活性数据、assay 与文献出处 |

**输出目录结构**：

命令会自动解析真实基因符号，并以 `<基因名>_<时间戳>` 命名结果根目录（未取到基因符号时退化为输入名）：

```bash
result/<基因名>_20260828_103000/
├── run.log                      # 各步骤执行状态 / 错误记录
├── uniprot/                     # UniProt 蛋白质数据及注释报告
├── sequence/                    # 蛋白质序列（fasta）与结构域信息
├── pdb/                         # PDB 结构文件及配体信息
├── opentargets/                 # 基因-疾病 / 基因-药物关联
├── kegg/                        # 信号通路信息及通路图
├── ppi/                         # 蛋白质互作网络
└── chembl/                      # 化合物、结构、靶点、活性、assay、文献
```

> **说明**：各数据库步骤相互独立，单个步骤失败不会中断整体流程，错误会记录到结果目录下的 `run.log`。未产生任何文件的空子目录会被自动清理。

**示例**：

```bash
# 基本用法：聚合下载 TP53 的全部 7 类数据
python pypda.py target TP53

# 使用 UniProt ID
python pypda.py target P00533

# 自定义输出根目录与 PPI 参数
python pypda.py target EGFR --out-root ./out --confidence 0.9 --max-neighbors 100 --chembl-limit 50
```

## 📁 目录结构说明

项目采用统一的目录结构管理所有输出文件：

```
result/
├── zip/                    # 所有下载zip文件统一存放
├── extract_output/         # 序列提取结果
├── mutate_output/          # 序列突变结果
├── align_output/           # 序列比对结果
├── pdb_output/             # PDB处理结果
├── protein_sequences/      # 蛋白质序列结果
├── uniprot_reports/        # UniProt数据结果
├── opentargets/            # OpenTargets查询结果
├── kegg_output/            # KEGG信号通路分析结果
├── ppi_output/             # PPI网络分析结果
├── chembl_output/          # ChEMBL化合物检索结果
└── temp/                   # 临时文件目录
```

## 📊 输出文件说明

### 序列分析输出

- **FASTA文件**：包含蛋白质序列
- **domain_info.md**：结构域信息报告
- **JSON文件**：原始UniProt数据（命名格式：`基因名_YYYYMMDD_HHMMSS.json`）
- **Markdown报告**：蛋白质详细信息（命名格式：`基因名_YYYYMMDD_HHMMSS.md`）

### PDB处理输出

- **CIF文件**：蛋白质结构文件（CIF格式）
- **配体文件**：提取的配体信息
- **分类报告**：配体分类结果（with_ligand / no_ligand）
- **结构信息报告**：`structure_info.csv`，包含PDB ID、结构标题、实验方法、分辨率和种属信息
- **下载失败记录**：`download_failed.txt`，下载失败的 PDB ID 列表（仅当有失败时生成，重跑即可补齐）
- **配体化学信息**：`chemical_components_info.csv`，包含配体ID、名称、分子式、分子量和SMILES
- **结构相似性报告**：`structure_similarity_ranking.md`，当使用`--smiles`参数（或`pdb similarity`命令）时生成，按Tanimoto系数降序列出前N个与输入分子最相似的配体及其对应的全部结构文件ID

## 📁 项目结构

PyPDA采用模块化设计，代码结构清晰，便于维护和扩展：

```
pypda/
├── config/                 # 配置管理模块
│   ├── __init__.py
│   └── config_manager.py   # 配置文件管理
├── logger/                 # 日志管理模块
│   ├── __init__.py
│   └── logger.py           # 日志记录功能
├── opentargets/            # OpenTargets数据查询模块
│   ├── __init__.py
│   ├── opentargets_api.py  # OpenTargets API交互
│   └── opentargets_processor.py # OpenTargets命令处理
├── kegg/                   # KEGG信号通路分析模块
│   ├── __init__.py
│   ├── kegg_api.py         # KEGG API交互
│   └── kegg_processor.py   # KEGG命令处理
├── ppi/                    # PPI网络分析模块
│   ├── __init__.py
│   ├── ppi_api.py          # STRING API交互
│   └── ppi_processor.py    # PPI命令处理
├── chembl/                 # ChEMBL靶点化合物检索模块
│   ├── __init__.py
│   ├── chembl_api.py       # ChEMBL API交互
│   └── chembl_processor.py # ChEMBL命令处理
├── target/                 # target 聚合下载模块
│   ├── __init__.py
│   ├── gene_resolver.py    # 基因符号解析
│   └── target_processor.py # 聚合下载编排器
├── pdb_tools/              # PDB处理模块
│   ├── __init__.py
│   ├── pdb_processor.py    # PDB文件处理功能
│   └── prolif_analyzer.py  # 基于ProLIF的蛋白质-配体相互作用分析
├── report/                 # 报告生成模块
│   ├── __init__.py
│   └── report_generator.py # 报告生成功能
├── sequence/               # 序列处理模块
│   ├── __init__.py
│   └── sequence_processor.py # 序列分析功能
├── uniprot/                # UniProt数据模块
│   ├── __init__.py
│   ├── protein_analyzer.py # 蛋白质数据分析
│   └── uniprot_api.py      # UniProt API交互
├── utils/                  # 工具函数模块
│   ├── __init__.py
│   └── common_utils.py     # 通用工具函数
├── pypda.py                # 主应用入口和命令行工具入口
├── requirements.txt        # 依赖列表
└── setup.py                # 安装配置
```

## ⚙️ 配置文件说明

1. **exclude_residues.ini**：定义需要排除的残基类型
   - 在配体提取时用于过滤不需要考虑的残基

## 🔧 开发信息

- **主要更新**：
  - **版本 0.8.0**：
    - `pdb fetch --smiles` 的相似性排序改为配体视角：`structure_similarity_ranking.md` 列出前10个与输入分子最相似的配体及其全部对应结构文件ID；每个结构文件的最终分数取其所有配体中的最大Tanimoto分数
    - 新增 `pdb similarity` 命令：输入SMILES对已下载好的文件夹中的结构文件（CIF/PDB或两种混合，递归扫描子目录）直接计算结构相似性，无需重新下载结构文件
    - `pdb fetch` 结构文件下载源从 RCSB ModelServer API 切换为静态文件服务 `files.rcsb.org`，批量下载提速约一个数量级（KRAS 523 个结构：约 26 分钟 → 63 秒），并彻底解决大量下载时的 `RemoteProtocolError`（incomplete chunked read）
    - 新增断点续传：已存在的 CIF 自动跳过，失败的 PDB ID 记录到 `download_failed.txt`，重跑只补齐缺失条目
    - 修复并行任务进度条严重滞后于实际进度的问题：进度改为按任务完成顺序推进，不再被队头的慢任务阻塞
    - 下载统一使用带退避重试的 `requests` 会话，配体 JSON 下载超时由 10 秒放宽到 30 秒
    - 新增 `seq insert` 命令：在序列指定位置之前插入一段或多段氨基酸片段，支持平行列表批量插入、越界跳过与末尾追加
    - 新增 `seq delete` 命令：删除指定1-based闭区间的氨基酸片段，多个区间坐标相对原始序列，自动剔除重叠区间
    - 新增 `target` 聚合下载命令：输入蛋白名 / 基因名 / UniProt ID，一次下载 7 类数据库数据（UniProt、序列与结构域、PDB、OpenTargets、KEGG、STRING PPI、ChEMBL）到固定子目录
    - ChEMBL 命令下载数据补充文献出处字段（PMID、DOI、期刊、标题、年份）
    - 将 `pdb` 子包重命名为 `pdb_tools`，修复其对 Python 标准库 `pdb` 模块的遮蔽，保证 `breakpoint()` / `pdb.set_trace()` 及 pytest 调试插件正常工作
  - **版本 0.7.0**：
    - 修复 `pdb analyze` 在 Windows 下的连锁失败：临时文件句柄锁（WinError 32）、晶体结构缺氢原子导致的 AttributeError，以及蛋白残基丢键导致的交互漏检
    - 修复部分特殊 CIF 文件（负残基编号、超长配体名）导致的 uint32 溢出和坐标解析错误
    - 修复 OpenTargets GraphQL 查询 400 错误（上游 `tradeNames` 字段 schema 变更适配）
    - 修复 `pdb fetch` 下载的 CIF 文件名带 `_full` 后缀的问题
    - 修复 `pdb analyze` 多进程模式下控制台输出乱序问题
    - 新增PPI网络分析功能，基于STRING数据库查询蛋白质互作网络，支持单基因扩展和基因列表交集两种模式
    - 新增ChEMBL化合物检索功能，`--target` 与 `--smiles` 参数可单独或组合使用，支持靶点化合物查询、全库相似性搜索，以及组合模式下基于RDKit的本地相似度过滤+排序
    - 在PPI和ChEMBL模块的核心分支添加详细日志，便于排查API调用、数据解析、文件保存等问题
    - 优化文件夹创建逻辑，避免创建空文件夹

## 📋 依赖库

核心依赖：

- biopython：生物信息学工具包
- requests：HTTP请求库
- pandas：数据处理
- configparser：配置文件解析
- rcsb-api：RCSB PDB 数据库检索（PDB ID 搜索与结构信息查询）
- rdkit：用于分子结构处理和相似性计算（需额外安装）
- prolif：基于RDKit的蛋白质-配体相互作用指纹分析（用于口袋分析）
- MDAnalysis：分子动力学轨迹和结构分析（用于口袋分析）

完整依赖列表参见`requirements.txt`

> **注意**：RDKit库需要额外安装，可通过`pip install rdkit>=2023.03.01`命令安装。该库用于支持`--smiles`参数的结构相似性计算功能。
>
> **注意**：ProLIF和MDAnalysis可通过`pip install prolif MDAnalysis`安装，用于支持`pdb analyze`命令的蛋白质-配体相互作用分析功能。