# PyBIP **Repository Path**: coding_playground/pybip ## Basic Information - **Project Name**: PyBIP - **Description**: PyBIP是一个Python脚本,旨在简化为主流结构预测模型生成输入文件的过程。 - **Primary Language**: Python - **License**: GPL-3.0 - **Default Branch**: 1.0.0 - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-09 - **Last Updated**: 2026-11-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Python Boltz/Protenix/AlphaFold3/OpenFold3/OpenDDE/Mol-1 Input Generator ## 简介 `Python Boltz/Protenix/AlphaFold3/OpenFold3/OpenDDE/Mol-1 Input Generator` (简称 PyBIP) 是一个Python脚本,旨在简化为生物信息学工具 **Boltz-2** (输出YAML格式)、**Protenix** (输出JSON格式)、**AlphaFold3** (输出JSON格式)、**OpenFold3** (输出JSON格式)、**OpenDDE** (输出JSON格式) 和 **Mol-1** (输出JSON格式) 生成输入文件的过程。它能够解析FASTA格式的蛋白质、DNA、RNA序列文件,CCD配体信息,以及包含化合物ID和SMILES的CSV文件,然后根据所选工具的要求生成相应的结构化输入文件。`batch` 子命令读取批量配置JSON,一次为多个体系 × 多个模型生成输入文件。此外,`nim` 子命令可以调用 **NVIDIA NIM** 托管端点,在线执行 Boltz-2 结构预测并保存返回的结构(OpenFold3 因端点强制要求 MSA 而暂未开放)。 ## 功能特性 - **多类型序列支持**: 从FASTA文件读取蛋白质、DNA、RNA序列,并支持指定每个序列的复制数量。 - **CCD配体支持**: 支持通过命令行指定CCD配体及其数量;命令行中**直接填裸CCD码**(如 `P4G`、`ATP`),无需 `CCD_` 前缀,程序会按各模型的规范自动添加或省略前缀。 - **化合物数据集成**: 从CSV文件中读取化合物ID和SMILES,并将其整合到生成的输入文件中。 - **可选配体场景**: 所有子命令的 `--csv` 参数均为可选,不提供时生成无配体的纯结构输入文件。 - **预计算MSA路径**: `--msa`/`--msa-paired` 参数可将预计算MSA文件路径写入蛋白实体(`boltz`/`protenix`/`alphafold3`/`openfold3`/`opendde`/`mol1` 六个模型支持),按顺序与 `--protein` 一一对应。 - **Boltz-2 YAML生成**: - 为每种序列和CCD配体生成带有唯一ID的条目。 - 为CSV中的每个化合物生成一个独立的YAML文件,化合物在YAML中固定ID为`B`。 - 无CSV时生成单个 `{base_name}.yaml`,不含binder和亲和力部分。 - **Protenix JSON生成**: - 为每种序列和CCD配体生成条目,**不包含ID字段**。 - 将CSV中的每个化合物作为一个独立条目整合到一个JSON文件中,化合物不包含ID字段。 - 在输出JSON文件同目录下生成一个随机种子文件 `seed.txt`。 - 无CSV时生成单条目JSON,`name` 为 `base_name`。 - **AlphaFold3 JSON生成**: - 输出符合 AlphaFold3 官方 JSON 格式 (`dialect: alphafold3`, `version: 4`)。 - 随机生成 `modelSeeds` 字段(101–999999 范围)。 - 链ID按输入顺序分配大写字母 (A, B, C...),多拷贝时使用列表 (如 `["A", "B"]`)。 - 离子/配体通过 `ccdCodes` 字段处理,SMILES化合物通过 `smiles` 字段处理。 - 为CSV中的每个化合物生成一个独立的JSON文件,无CSV时生成单个 `{base_name}.json`。 - **OpenFold3 JSON生成**: - 输出符合 OpenFold3 推理 JSON 格式(顶层 `seeds` 字段 + `queries` 字典)。 - 顶层随机生成 `seeds` 字段(101–999999 范围),无需命令行参数。 - 链使用 `molecule_type` + `chain_ids` 结构。 - 配体支持 `ccd_codes` (CCD) 和 `smiles` (SMILES) 两种定义方式。 - 链ID按输入顺序分配大写字母,多拷贝时使用列表;每个 query 的链ID独立从 `A` 开始。 - 多个预测任务(CSV中的每个化合物/组合)合并写入**单个JSON文件**的 `queries` 字典,每个任务一个 query。 - `--output` 为输出**文件路径**(默认 `input.json`),与 `protenix` 子命令一致;仅在该路径的父目录不存在时创建,不额外生成文件夹。 - **OpenDDE JSON生成**: - 输出符合 OpenDDE 推理 JSON 格式(顶层为 job 数组)。 - 实体键为 `proteinChain`、`dnaSequence`、`rnaSequence`、`ligand`(CCD 或 SMILES)和 `ion`。 - `--ccd` 的值会自动补上 `CCD_` 前缀;`--ion` 的值保持裸CCD码(自动去掉 `CCD_` 前缀)。 - 每个 job 随机生成 `modelSeeds` 字段(101–999999 范围)。 - 不输出实体 `id` 字段,链ID由 OpenDDE 自动分配。 - 多个预测任务(CSV中的每个化合物/组合)作为多个 job 合并写入**单个JSON文件**;`--output` 为输出**文件路径**(默认 `input.json`),与 `protenix` 子命令一致。 - 可选 `--covalent-bonds` 传入共价键JSON文件(顶层为数组),其内容原样注入每个 job 的 `covalent_bonds` 字段。 - **Mol-1 JSON生成**: - 输出符合 Mol-1 推理 JSON 格式(顶层为 job 数组,实体键与 OpenDDE 一致)。 - 实体键为 `proteinChain`、`dnaSequence`、`rnaSequence`、`ligand`(CCD 或 SMILES)和 `ion`。 - `--ccd` 的值会自动补上 `CCD_` 前缀;`--ion` 的值保持裸CCD码(自动去掉 `CCD_` 前缀)。 - `--model-seeds true|false` 控制是否在每个 job 中写入随机 `modelSeeds`(默认 `true`);设为 `false` 时不输出该字段,Mol-1 使用默认种子 101(该字段仅在使用 `--use_seeds_in_json true` 推理时被读取)。 - 不输出实体 `id` 字段,链ID由 Mol-1 自动分配。 - 多个预测任务(CSV中的每个化合物/组合)作为多个 job 合并写入**单个JSON文件**;`--output` 为输出**文件路径**(默认 `input.json`),与 `protenix`/`opendde` 子命令一致。 - 可选 `--covalent-bonds` 传入共价键JSON文件(格式与 OpenDDE 完全相同),其内容原样注入每个 job 的 `covalent_bonds` 字段。 - **NVIDIA NIM 在线预测 (nim)**: - 调用 NVIDIA NIM 托管端点,在线执行 Boltz-2 结构预测,一次运行只提交一个复合物任务(OpenFold3 因端点强制要求 MSA 而暂未开放)。 - 复用 `--protein`/`--dna`/`--rna`/`--ccd` 参数,并新增 `--peptide`(裸序列多肽)、`--cyclic`(环肽开关)、`--smiles`(小分子)和 `--timeout`。 - 保存返回的 cif 结构、评分 JSON 与实际发出的请求 JSON(不含 API key)。 - **统一错误处理**: 使用自定义异常 `InputGeneratorError` 和错误码,提供清晰的错误信息。 - **详细日志**: 提供生成过程中的信息、警告和错误日志。 - **PEP8兼容**: 代码风格符合Python PEP8规范。 - **类型注解**: 广泛使用类型注解,增强代码可读性和可维护性。 ## 版本 当前版本: 1.0.0 ## 安装 ### 1. 从源代码安装 1. **克隆仓库**: ```bash git clone https://gitee.com/coding_playground/pybip.git cd pybip ``` 2. **安装依赖**: ```bash pip install -r requirements.txt ``` 3. **安装包**: ```bash pip install -e . ``` ### 2. 直接使用脚本 如果您不想安装包,也可以直接使用 `pybip.py` 脚本: 1. **下载脚本**: 将 `pybip.py` 文件下载到您的本地目录。 2. **安装依赖**: ```bash pip install pyyaml ``` ## 使用方法 脚本通过子命令的方式工作,支持 `boltz`、`protenix`、`alphafold3`、`openfold3`、`opendde`、`mol1`、`batch` 和 `nim` 八个主命令。其中前六个分别生成单个模型的输入文件,`batch` 读取批量配置JSON一次为多个体系×模型生成,`nim` 用于调用 NVIDIA NIM 在线执行结构预测。 ### 通用参数 以下参数可用于所有子命令,用于指定输入数据: - `--protein "PATH:COUNT[,PATH:COUNT]..."`: 蛋白质FASTA文件路径和数量。例如: `"protein1.fasta:1,protein2.fasta:2"` - `--dna "PATH:COUNT[,PATH:COUNT]..."`: DNA FASTA文件路径和数量。格式同上。 - `--rna "PATH:COUNT[,PATH:COUNT]..."`: RNA FASTA文件路径和数量。格式同上。 - `--ccd "NAME:COUNT[,NAME:COUNT]..."`: CCD配体名称和数量,**直接填裸CCD码,无需 `CCD_` 前缀**。例如: `"P4G:1,6OI:2"`。程序会按模型自动处理前缀:`protenix`/`opendde` 的配体会补上 `CCD_`(`P4G` → `CCD_P4G`),`boltz`/`alphafold3`/`openfold3` 保持裸码。写成 `CCD_P4G` 也能识别(会自动去前缀后再按模型重加)。`protenix`/`opendde` 还支持 `FILE_` 前缀的结构文件路径(保持原样,不加前缀)。 - `--ion "NAME:COUNT[,NAME:COUNT]..."`: 离子名称和数量(仅 `protenix`、`opendde` 和 `mol1` 子命令支持),同样**直接填裸CCD码**。例如: `"NA:1,CL:2"`。这些模型的 `ion` 字段都**不带** `CCD_` 前缀,写成 `CCD_NA` 也会自动去前缀。 - `--csv "PATH[,PATH]..."`: **(可选)** 包含化合物ID和SMILES的CSV文件路径,可传多个,格式同 `--protein`。CSV文件必须包含 `id` 和 `smiles` 两列。提供多个CSV时,生成文件中的配体为各CSV文件SMILES的笛卡尔积组合(每个CSV取一个),同一CSV内的SMILES不重复出现在同一文件中。不提供时生成无配体的纯结构输入文件。 - `--msa "PATH[,PATH]..."`: **(可选)** 非配对MSA文件路径(如 a3m),逗号分隔,**第 n 个路径对应 `--protein` 中第 n 个蛋白文件,数量须一致**。MSA 仅写入蛋白实体,多拷贝(count>1)共享同一 MSA。仅 `boltz`、`protenix`、`alphafold3`、`openfold3`、`opendde` 和 `mol1` 支持(`nim` 不接受该参数);**不检查本地是否存在该文件**——MSA 文件通常在推理服务器端,路径按原样写入输入文件。 - `--msa-paired "PATH[,PATH]..."`: **(可选)** 配对MSA文件路径,对应关系同 `--msa`。仅 `protenix`、`alphafold3`、`openfold3`、`opendde` 和 `mol1` 支持;`boltz` 的 YAML 格式只有单路径 `msa` 字段,不接受该参数。 各模型输出的 MSA 字段名: | 模型 | 非配对(`--msa`) | 配对(`--msa-paired`) | |------|------------------|----------------------| | boltz | `msa` | 不支持 | | protenix | `unpairedMsaPath` | `pairedMsaPath` | | alphafold3 | `unpairedMsaPath` | `pairedMsaPath` | | openfold3 | `main_msa_file_paths` | `paired_msa_file_paths` | | opendde | `unpairedMsaPath` | `pairedMsaPath` | | mol1 | `unpairedMsaPath` | `pairedMsaPath` | 以上通用参数中,`nim` 子命令只使用 `--protein`、`--dna`、`--rna` 和 `--ccd`;它**不接受** `--csv`、`--ion` 和 `--msa`,离子的表达方式见下文第 8 节。`batch` 子命令以**数组形式**消费同样的通用参数(见第 7 节)。 ### 1. 生成 Boltz-2 YAML 输入文件 使用 `boltz` 子命令生成 Boltz-2 YAML 文件。 **特定参数**: - `--output DIR_PATH`: YAML文件的输出目录(默认: `.` 当前目录)。 - `--pocket FILE_PATH`: 口袋约束YAML文件路径,其内容将被直接添加到生成的YAML文件末尾。 - `--affinity true|false`: 是否在输出YAML中包含亲和力计算部分(默认: `false`)。仅在提供 `--csv` 时生效。 **输出文件结构**: - 提供 `--csv` 时:每个化合物生成一个独立的YAML文件,命名格式为 `[所有序列文件基础名用下划线连接]_[化合物ID].yaml`。 - YAML文件中的序列(蛋白质、DNA、RNA)和CCD配体都会被分配一个唯一的 `id` (如 `P1`, `D2`, `P4G`)。 - 从CSV读取的化合物:第一个CSV的配体固定使用 `id: B`,后续CSV的配体依次使用 `id: L1`、`L2`... - 当 `--affinity` 为 `true` 时,YAML文件会包含 `properties` 部分,用于指定亲和力计算的binder。 - 当 `--affinity` 为 `false` 时,YAML文件不会包含 `properties` 部分。 - 多CSV组合时,文件/entry命名为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:生成单个 `{base_name}.yaml`,仅包含序列和CCD配体,不含binder和亲和力部分。 **示例**: 假设您有以下文件: - `protein.fasta` (包含一个蛋白质序列) - `compounds.csv` (内容如下: `id,smiles COMP1,CCCC COMP2,O=C(N)C`) - `pocket.yaml` (包含口袋约束信息) ```bash python pybip.py boltz \ --protein "protein.fasta:1" \ --ccd "P4G:1" \ --csv compounds.csv \ --output boltz_inputs \ --pocket pocket.yaml ``` **示例 (不包含亲和力计算部分)**: ```bash python pybip.py boltz \ --protein "protein.fasta:1" \ --ccd "P4G:1" \ --csv compounds.csv \ --output boltz_inputs \ --pocket pocket.yaml \ --affinity false ``` **示例 (无配体纯结构预测)**: ```bash python pybip.py boltz \ --protein "protein.fasta:1" \ --output boltz_inputs ``` 这将会在 `boltz_inputs` 目录下生成类似的文件: - `protein_COMP1.yaml` - `protein_COMP2.yaml` `protein_COMP1.yaml` 的大致内容: ```yaml version: 1 sequences: - protein: id: P1 sequence: YOUR_PROTEIN_SEQUENCE_HERE count: 1 - ligand: id: P4G ccd: P4G count: 1 - ligand: id: B smiles: CCCC count: 1 properties: - affinity: binder: B constraints: - pocket: binder: B # Ligand chain contacts: [[P1, AA No.], [P1, AA No.], [P1, AA No.]...] # Contact residues max_distance: x # Angstroms force: true # Use potential to enforce ``` ### 2. 生成 Protenix JSON 输出文件 使用 `protenix` 子命令生成 Protenix JSON 文件。 **特定参数**: - `--output FILE_PATH`: 输出JSON文件的名字(默认: `input.json`)。 **输出文件结构**: - 提供 `--csv` 时:所有化合物的条目都会被整合到一个JSON文件中。 - JSON文件中的序列(蛋白质、DNA、RNA)和CCD配体 **不会** 包含 `id` 字段。 - JSON文件中的化合物也不会包含 `id` 字段,只有 `ligand` 和 `count`。 - 多CSV组合时,文件/entry命名为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:生成单条目JSON,`name` 为 `base_name`,仅包含序列、CCD配体和离子。 - 在输出JSON文件所在的目录下,会生成一个名为 `seed.txt` 的文件,其中包含一个随机生成的整数种子。 **示例**: ```bash python pybip.py protenix \ --protein "protein.fasta:1" \ --dna "dna.fasta:1" \ --ccd "6OI:2" \ --ion "NA:1,CL:2" \ --csv compounds.csv \ --output protenix_data.json ``` 这将在当前目录下生成 `protenix_data.json` 和 `seed.txt`。 `protenix_data.json` 的大致内容: ```json [ { "sequences": [ { "proteinChain": { "sequence": "YOUR_PROTEIN_SEQUENCE_HERE", "count": 1 } }, { "dnaSequence": { "sequence": "YOUR_DNA_SEQUENCE_HERE", "count": 1 } }, { "ligand": { "ligand": "CCD_6OI", "count": 2 } }, { "ion": { "ion": "NA", "count": 1 } }, { "ion": { "ion": "CL", "count": 2 } }, { "ligand": { "ligand": "CCCC", "count": 1 } } ], "name": "protein_COMP1" }, { "sequences": [ { "proteinChain": { "sequence": "YOUR_PROTEIN_SEQUENCE_HERE", "count": 1 } }, { "dnaSequence": { "sequence": "YOUR_DNA_SEQUENCE_HERE", "count": 1 } }, { "ligand": { "ligand": "CCD_6OI", "count": 2 } }, { "ion": { "ion": "NA", "count": 1 } }, { "ion": { "ion": "CL", "count": 2 } }, { "ligand": { "ligand": "O=C(N)C", "count": 1 } } ], "name": "protein_dna_COMP2" } ] ``` ### 3. 生成 AlphaFold3 JSON 输入文件 使用 `alphafold3` 子命令生成 AlphaFold3 JSON 文件。 **特定参数**: - `--output DIR_PATH`: JSON文件的输出目录(默认: `.` 当前目录)。 **输出文件结构**: - 输出符合 AlphaFold3 官方 JSON 格式 (`dialect: "alphafold3"`, `version: 4`)。 - 随机生成 `modelSeeds` 字段(101–999999 范围的整数列表)。 - 链ID按输入顺序分配大写字母 (A, B, C...),多拷贝时使用列表 (如 `["A", "B"]`)。 - 提供 `--csv` 时:每个化合物生成一个独立的JSON文件,命名格式为 `[所有序列文件基础名用下划线连接]_[化合物ID].json`。 - 多CSV组合时,文件/entry命名为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:生成单个 `{base_name}.json`,仅包含序列和CCD配体。 - 蛋白质、DNA、RNA分别通过 `protein`、`dna`、`rna` 字段定义。 - CCD配体通过 `ligand.ccdCodes` 字段定义(列表形式)。 - SMILES化合物通过 `ligand.smiles` 字段定义。 **示例**: ```bash python pybip.py alphafold3 \ --protein "protein.fasta:1" \ --ccd "ATP:1" \ --csv compounds.csv \ --output af3_inputs ``` **示例 (无配体纯结构预测)**: ```bash python pybip.py alphafold3 \ --protein "protein.fasta:1" \ --output af3_inputs ``` 这将会在 `af3_inputs` 目录下生成类似的文件: - `protein_COMP1.json` - `protein_COMP2.json` `protein_COMP1.json` 的大致内容: ```json { "name": "protein_COMP1", "modelSeeds": [12345], "sequences": [ { "protein": { "id": "A", "sequence": "YOUR_PROTEIN_SEQUENCE_HERE" } }, { "ligand": { "id": "B", "ccdCodes": ["ATP"] } }, { "ligand": { "id": "C", "smiles": "CCCC" } } ], "dialect": "alphafold3", "version": 4 } ``` ### 4. 生成 OpenFold3 JSON 输入文件 使用 `openfold3` 子命令生成 OpenFold3 JSON 文件。 **特定参数**: - `--output FILE_PATH`: 输出JSON文件路径(默认: `input.json`),与 `protenix` 子命令一致。父目录不存在时自动创建,不生成额外文件夹。 **输出文件结构**: - 输出符合 OpenFold3 推理 JSON 格式(顶层 `seeds` 字段 + `queries` 字典)。 - 顶层 `seeds` 字段为随机生成的整数列表(101–999999 范围),无需命令行参数。 - 链使用 `molecule_type` + `chain_ids` 结构。 - 链ID按输入顺序分配大写字母 (A, B, C...),多拷贝时使用列表 (如 `["A", "B"]`);**每个 query 的链ID独立从 `A` 开始**。 - 提供 `--csv` 时:所有化合物/组合作为多个 query 合并写入 `--output` 指定的单个文件。 - 多CSV组合时,query 名称为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:`queries` 中只有一个 query,名称为 `base_name`,仅包含序列和CCD配体。 - 蛋白质、DNA、RNA分别通过 `molecule_type: "protein"/"dna"/"rna"` 定义。 - CCD配体通过 `molecule_type: "ligand"` + `ccd_codes` 字段定义。 - SMILES化合物通过 `molecule_type: "ligand"` + `smiles` 字段定义。 **示例**: ```bash python pybip.py openfold3 \ --protein "protein.fasta:1" \ --ccd "ATP:1" \ --csv compounds.csv \ --output of3_inputs.json ``` **示例 (无配体纯结构预测)**: ```bash python pybip.py openfold3 \ --protein "protein.fasta:1" \ --output of3_inputs/protein.json ``` 这将在 `of3_inputs/` 下生成单个文件 `protein.json`(CSV 中有 12 个化合物即 12 个 query)。 `of3_inputs.json` 的大致内容(多个预测任务合并为一个输入文件): ```json { "seeds": [12345], "queries": { "protein_COMP1": { "chains": [ { "molecule_type": "protein", "chain_ids": "A", "sequence": "YOUR_PROTEIN_SEQUENCE_HERE" }, { "molecule_type": "ligand", "chain_ids": "B", "ccd_codes": "ATP" }, { "molecule_type": "ligand", "chain_ids": "C", "smiles": "CCCC" } ] }, "protein_COMP2": { "chains": [ { "molecule_type": "protein", "chain_ids": "A", "sequence": "YOUR_PROTEIN_SEQUENCE_HERE" }, { "molecule_type": "ligand", "chain_ids": "B", "ccd_codes": "ATP" }, { "molecule_type": "ligand", "chain_ids": "C", "smiles": "O=C(N)C" } ] } } } ``` ### 5. 生成 OpenDDE JSON 输入文件 使用 `opendde` 子命令生成 OpenDDE JSON 文件。 **特定参数**: - `--output FILE_PATH`: 输出JSON文件路径(默认: `input.json`),与 `protenix` 子命令一致。父目录不存在时自动创建。 - `--covalent-bonds FILE_PATH`: 共价键JSON文件路径,顶层应为数组(元素字段见 OpenDDE 文档的 `covalent_bonds` 规范),其内容会被**原样注入**每个 job 的 `covalent_bonds` 字段。可选。 该子命令同样支持 `--ion` 参数。 **输出文件结构**: - 输出符合 OpenDDE 推理 JSON 格式(**顶层为 job 数组**)。 - 每个 job 包含 `name`、`modelSeeds`、`sequences`,以及可选的 `covalent_bonds`。 - `modelSeeds` 为随机生成的整数列表(101–999999 范围)。 - 实体键为 `proteinChain`、`dnaSequence`、`rnaSequence`、`ligand`(CCD 或 SMILES)和 `ion`,每个实体均含 `count`。 - **不输出**实体 `id` 字段,链ID由 OpenDDE 自动分配。 - `--ccd` 的值会自动补上 `CCD_` 前缀(如 `P4G` → `CCD_P4G`);`--ion` 的值保持裸CCD码(如 `NA`),即使写成 `CCD_NA` 也会自动去掉前缀。 - 提供 `--csv` 时:所有化合物/组合作为多个 job 合并写入 `--output` 指定的单个文件。 - 多CSV组合时,job 名称为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:数组中只有一个 job,名称为 `base_name`,仅包含序列、CCD配体和离子。 **示例**: ```bash python pybip.py opendde \ --protein "protein.fasta:1" \ --ccd "P4G:1" \ --ion "NA:1" \ --csv compounds.csv \ --output opendde_inputs.json ``` **示例 (无配体纯结构预测)**: ```bash python pybip.py opendde \ --protein "protein.fasta:1" \ --output opendde_inputs/protein.json ``` `opendde_inputs.json` 的大致内容(多个预测任务合并为一个输入文件): ```json [ { "name": "protein_COMP1", "modelSeeds": [428173], "sequences": [ { "proteinChain": { "sequence": "YOUR_PROTEIN_SEQUENCE_HERE", "count": 1 } }, { "ligand": { "ligand": "CCD_P4G", "count": 1 } }, { "ion": { "ion": "NA", "count": 1 } }, { "ligand": { "ligand": "CCCC", "count": 1 } } ], "covalent_bonds": [ { "entity1": "1", "copy1": 1, "position1": "2", "atom1": "SG", "entity2": "2", "copy2": 1, "position2": "1", "atom2": "C1" } ] } ] ``` ### 6. 生成 Mol-1 JSON 输入文件 使用 `mol1` 子命令生成 Mol-1 JSON 文件。 **特定参数**: - `--output FILE_PATH`: 输出JSON文件路径(默认: `input.json`),与 `protenix`/`opendde` 子命令一致。父目录不存在时自动创建。 - `--covalent-bonds FILE_PATH`: 共价键JSON文件路径,顶层应为数组(元素字段见 Mol-1 文档的 `covalent_bonds` 规范,与 OpenDDE 格式相同),其内容会被**原样注入**每个 job 的 `covalent_bonds` 字段。可选。 - `--model-seeds true|false`: 是否在每个 job 中写入随机 `modelSeeds`(默认: `true`)。Mol-1 仅在使用 `--use_seeds_in_json true` 推理时读取该字段;设为 `false` 时不输出该字段,Mol-1 使用默认种子 101。 该子命令同样支持 `--ion` 参数。 **输出文件结构**: - 输出符合 Mol-1 推理 JSON 格式(**顶层为 job 数组**)。 - 每个 job 包含 `name`、`sequences`、可选的 `modelSeeds`(`--model-seeds true` 时)以及可选的 `covalent_bonds`。 - 实体键为 `proteinChain`、`dnaSequence`、`rnaSequence`、`ligand`(CCD 或 SMILES)和 `ion`,每个实体均含 `count`。 - **不输出**实体 `id` 字段,链ID由 Mol-1 自动分配。 - `--ccd` 的值会自动补上 `CCD_` 前缀(如 `P4G` → `CCD_P4G`);`--ion` 的值保持裸CCD码(如 `NA`),即使写成 `CCD_NA` 也会自动去掉前缀。 - 提供 `--csv` 时:所有化合物/组合作为多个 job 合并写入 `--output` 指定的单个文件。 - 多CSV组合时,job 名称为 `[所有序列文件基础名用下划线连接]_[各CSV配体ID按下划线连接]`;若不同CSV存在相同ID导致命名冲突,自动回退为 `[基础名]_[CSV文件名]_[ID]_...` 形式,仍冲突则追加数字后缀。 - 不提供 `--csv` 时:数组中只有一个 job,名称为 `base_name`,仅包含序列、CCD配体和离子。 **示例**: ```bash python pybip.py mol1 \ --protein "protein.fasta:1" \ --ccd "P4G:1" \ --ion "NA:1" \ --csv compounds.csv \ --output mol1_inputs.json ``` **示例 (无配体纯结构预测,不写 modelSeeds)**: ```bash python pybip.py mol1 \ --protein "protein.fasta:1" \ --model-seeds false \ --output mol1_inputs/protein.json ``` `mol1_inputs.json` 的大致内容(多个预测任务合并为一个输入文件): ```json [ { "name": "protein_COMP1", "sequences": [ { "proteinChain": { "sequence": "YOUR_PROTEIN_SEQUENCE_HERE", "count": 1 } }, { "ligand": { "ligand": "CCD_P4G", "count": 1 } }, { "ion": { "ion": "NA", "count": 1 } }, { "ligand": { "ligand": "CCCC", "count": 1 } } ], "modelSeeds": [428173] } ] ``` ### 7. 批量生成输入文件(batch) 使用 `batch` 子命令读取批量配置JSON,一次为多个体系 × 多个模型生成输入文件。 **用法**: ```bash python pybip.py batch ``` **配置格式要点**(完整规范见 `docs/superpowers/specs/2026-11-04-json-config-design.md`): - 顶层:`version`(当前仅 `1`)、`output_root`(输出根目录,缺省 `.`)、`jobs`(非空数组,每个元素一个体系)。**未知字段一律报错**。 - 每个体系:`name`(全文件唯一的体系标识)、可选 `output`(体系输出目录名,缺省为 `name`)、`models`(模型列表,支持 `af3`/`of3` 简写)、通用参数的**数组形式**(`protein`/`dna`/`rna`/`ccd`/`ion`/`csv`/`msa`/`msa_paired`,每个元素与对应 CLI 参数中逗号分隔的一项完全同形,含 `:数量` 后缀)、可选 `model_options`(按模型分组的专属参数:boltz 的 `pocket`/`affinity`、openfold3 的 `pocket`、opendde 的 `covalent_bonds`、mol1 的 `covalent_bonds`/`model_seeds`,以及所有模型的 `output`)。 - **路径基准**:所有本地相对路径以 JSON 文件所在目录为基准;`msa`/`msa_paired` 是推理服务器端路径,**原样写入、不做本地存在性检查**。 - **输出布局**:`/<体系 output 或 name>/<模型名>/...`;目录型模型(boltz/alphafold3)产出子目录,单文件型模型(protenix/openfold3/opendde/mol1)产出 `<模型名>/input.json`,两层均可经 `output` 命名覆盖。 - **校验时机**:全部结构校验在写任何文件之前完成(失败错误码 `213`);运行期单个模型失败不中断其余任务,末尾打印汇总,存在失败时以第一个失败任务的错误码非零退出。 **示例**(`batch.json`): ```json { "version": 1, "output_root": "inputs", "jobs": [ { "name": "JAK1_P4G", "output": "JAK1_run1", "models": ["boltz", "mol1"], "protein": ["JAK1_839_1154.fasta:1"], "ccd": ["P4G:1"], "msa": ["/data/msa/jak1/non_pairing.a3m"], "model_options": { "mol1": {"output": "jak1_mol1.json"} } }, { "name": "NLRP3_apo", "models": ["protenix", "af3"], "protein": ["NLRP3_131_679.fasta:1"] } ] } ``` ```bash python pybip.py batch batch.json ``` **汇总输出示例**: ``` ===== batch 汇总 ===== [成功] JAK1_P4G.boltz: inputs/JAK1_run1/boltz [成功] JAK1_P4G.mol1: inputs/JAK1_run1/mol1/jak1_mol1.json [成功] NLRP3_apo.protenix: inputs/NLRP3_apo/protenix/input.json [成功] NLRP3_apo.alphafold3: inputs/NLRP3_apo/alphafold3 共 4 个模型任务,成功 4 个,失败 0 个 ``` ### 8. 调用 NVIDIA NIM 在线执行结构预测(nim) 使用 `nim` 子命令调用 **NVIDIA NIM** 托管端点,在线执行 **Boltz-2** 或 **OpenFold3** 结构预测。与前面七个子命令只生成输入文件不同,`nim` 会真正发起网络请求并保存预测结果。**一次运行只提交一个复合物预测任务。** **特定参数**: - `--model {boltz2,openfold3}`: **必填**,选择要调用的 NIM 模型。只接受这两个全名,不接受别名。**目前只有 `boltz2` 开放**,`openfold3` 会直接报错(错误码 `211`),原因见下。 - `--peptide "SEQ[,SEQ]..."`: 多肽序列,**直接填序列本身,不是文件路径**,多条用逗号分隔(如 `"ACDEFGH,HHH"`)。在请求中按蛋白质类型提交。 - `--cyclic true|false`: 是否把 `--peptide` 提供的多肽视为环肽(默认: `false`)。 - `--smiles "SMILES"`: 小分子 SMILES 字符串,**只接受一条**,不做逗号拆分、也不解析 `:数量`。 - `--output DIR_PATH`: 预测结果的输出目录(默认: `.` 当前目录)。 - `--timeout SECONDS`: 单次请求的超时秒数(默认: `3600`)。NIM 是同步调用且没有轮询端点,大体系可能耗时很久。 **关于 `openfold3`(暂未开放)**: 实测 NVIDIA 的 OpenFold3 端点**强制要求每个蛋白序列携带非空 MSA**,未携带时会返回 `HTTP 422`: ``` Each protein sequence in the input must be accompanied by a non-empty MSA or paired_msa. If the user intent is to provide 0 hits for this protein sequence, then an MSA consisting of only the query sequence should be provided. ``` 也就是说该端点不自带 MSA 搜索,必须由调用方提供。当前实现不构造 MSA,因此 `--model openfold3` 会在发请求之前直接报错(错误码 `211`)。仅查询序列的 MSA 可以让请求通过,但那属于单序列模式,实测 `complex_plddt_score` 只有 68–76,属明显低置信度,不宜作为默认行为。恢复开放需要补上 MSA 输入支持,详见 `docs/superpowers/specs/` 下的设计文档。 **通用参数的差异**: - `--protein`/`--dna`/`--rna`/`--ccd` 的格式与其它子命令完全一致。 - `nim` **不提供** `--csv` 和 `--ion`。离子请用 `--ccd` 表达,例如 `--ccd "NA:1,CL:2"`(NIM 的 CCD 字段接受这类码)。 - `--ccd` 映射为 `ligands[].ccd`,使用裸 CCD 码。 - NIM 没有「数量」字段,因此多拷贝会展开成多条实体:`--protein "x.fasta:2"` 生成两条链 ID 分别为 `A`、`B` 的聚合物(该端点的链 ID 只接受单个字符串)。 - 实体链 ID 按 `protein → dna → rna → peptide → ccd → smiles` 的顺序连续分配大写字母。总数超过 26 时报错(错误码 `210`)。 **前置条件**: 需要设置环境变量 `NVIDIA_API_KEY`(在 获取)。`nim` 不提供 `--api-key` 参数,以免密钥进入 shell 历史或进程列表: ```bash # Linux / macOS export NVIDIA_API_KEY="nvapi-xxxxxxxx" # Windows PowerShell $env:NVIDIA_API_KEY = "nvapi-xxxxxxxx" ``` **示例**: ```bash # Boltz-2:蛋白 + CCD 配体 + 小分子 python pybip.py nim --model boltz2 \ --protein "JAK1_839_1154.fasta:1" \ --ccd "P4G:1" \ --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" \ --output nim_out # Boltz-2:环肽 + 小分子 python pybip.py nim --model boltz2 \ --peptide "ACDEFGHIKLMNPQRSTVWY" \ --cyclic true \ --smiles "CCCC" \ --output nim_out # Boltz-2:蛋白双拷贝 + 两拷贝 CCD python pybip.py nim --model boltz2 \ --protein "HDAC3.fasta:2" \ --ccd "P4G:2" \ --output nim_out ``` **输出文件结构**: 输出文件的基础名由输入派生:提供 `--protein`/`--dna`/`--rna` 时,取所有序列文件的基础名用下划线连接;纯多肽调用时为固定值 `peptide`。 - `.cif`: 第 1 条预测结构。 - `_2.cif`、`_3.cif`...: 第 2、3 条结构,仅当模型返回多条采样时产生。 - `_scores.json`: 评分内容。boltz2 写入 `confidence_scores` 与 `affinities`;openfold3 写入 `structures_with_scores`(含 `confidence_score`、`complex_plddt_score`、`complex_pde_score`、`ptm_score`、`iptm_score`)。其中**不含**结构文本本身。 - `_request.json`: 实际发出的请求内容(`model`、`url`、`payload`),在发请求**之前**写入,便于复现与排查。**不含 API key**。 **错误码**: | 错误码 | 说明 | |--------|------| | 206 | `--peptide` 序列含非字母字符或出现空项 | | 208 | `--timeout` 不是正整数 | | 209 | 环境变量 `NVIDIA_API_KEY` 未设置或为空 | | 210 | 实体总链数超过 26(可用链 ID 用尽),请拆分后分别预测 | | 211 | 指定的模型暂未开放(当前为 `openfold3`) | | 401 | 网络层失败(连不上、超时、TLS 错误) | | 402 | 服务端返回非 2xx。错误信息中会带上 HTTP 状态码与响应体内容,NIM 的参数校验详情会在这里透出 | | 403 | 响应体不符合预期(非法 JSON、缺少结构字段等) | | 404 | 结果写入失败 | **已知限制**: - `--protein`/`--dna`/`--rna` 按 `:` 切分「路径」与「数量」,因此 Windows 下带盘符的绝对路径(如 `D:\data\x.fasta:1`)会被判为格式错误。请使用相对路径。 - `nim` 只调用 NVIDIA 托管端点,不支持本地自建的 NIM 容器(两者的路径前缀不同)。 - 推理参数(`recycling_steps`、`sampling_steps`、`diffusion_samples` 等)不做暴露,一律使用服务端默认值。 - `--model openfold3` 暂未开放(端点强制要求 MSA)。 - `complex_plddt_score` 实测为 `0–100`,而 NVIDIA 官方 API Reference 写的是 `0–1`。`_scores.json` 中的数值原样保留服务端返回值,不做换算。 - 短时间内连续调用会被服务端限流(`HTTP 429`),表现为错误码 `402` 并透出 `Too Many Requests`。`nim` 不自动重试,稍后重跑即可。 ## 项目结构 ``` pybip/ ├── pybip.py # 主脚本文件 ├── exceptions.py # 自定义异常类 ├── commands/ # 命令相关模块 │ ├── __init__.py │ ├── base.py # 命令基类 │ ├── boltz.py # Boltz命令实现 │ ├── protenix.py # Protenix命令实现 │ ├── alphafold3.py # AlphaFold3命令实现 │ ├── openfold3.py # OpenFold3命令实现 │ ├── opendde.py # OpenDDE命令实现 │ ├── mol1.py # Mol-1命令实现 │ ├── registry.py # 模型注册表(供batch复用) │ ├── batch.py # 批量生成子命令实现 │ ├── batch_config.py # 批量配置加载/校验/执行计划(纯函数层) │ └── nim.py # NVIDIA NIM在线预测命令实现 ├── tests/ # 单元与集成测试(python -m unittest discover tests) ├── utils/ # 工具函数 │ ├── __init__.py │ ├── fasta.py # FASTA文件读取 │ ├── csv_reader.py # CSV文件读取 │ ├── seed.py # 随机种子生成 │ └── nim_client.py # NVIDIA NIM API 传输层 ├── requirements.txt # 依赖列表 ├── setup.py # 安装配置 └── README.md # 项目文档 ``` ## 错误处理 脚本使用自定义的 `InputGeneratorError` 异常来处理各种预期错误,例如文件未找到、CSV格式错误、参数解析失败等。当发生此类错误时,脚本会输出详细的错误信息到标准错误流,并以相应的错误码退出。 主要错误码说明: | 错误码范围 | 说明 | |-----------|------| | 1xx | FASTA/CSV/种子文件读取错误 | | 2xx | 参数解析错误(序列、配体、离子格式等) | | 205 | 模型名解析失败:指定了未知模型名或未指定任何模型(`commands/registry.py`,供批量配置读取器使用) | | 206 | `nim` 的 `--peptide` 序列含非字母字符或出现空项 | | 208 | `nim` 的 `--timeout` 不是正整数 | | 209 | `nim` 未找到环境变量 `NVIDIA_API_KEY` | | 210 | `nim` 的实体总链数超过 26(可用链 ID 用尽) | | 211 | `nim` 指定的模型暂未开放(当前为 `openfold3`,因端点要求 MSA) | | 212 | `--msa`/`--msa-paired` 参数格式错误、未与 `--protein` 搭配或路径数量与蛋白文件数量不一致 | | 213 | `batch` 配置JSON读取失败或结构校验失败(版本不支持、未知字段、体系名/输出目录冲突、MSA数量不匹配、model_options 键不合法等) | | 3xx | 输出文件写入错误(301=Boltz, 302=Protenix, 304=AlphaFold3, 305=OpenFold3, 308=OpenDDE, 309=Mol-1) | | 307 | 共价键JSON文件读取/格式错误(OpenDDE/mol1 共用) | | 4xx | `nim` 的调用错误(401=网络层失败, 402=服务端返回非2xx, 403=响应体不符合预期, 404=结果写入失败) | ## 许可证 本项目采用 GNU General Public License v3 (GPLv3) 许可证。详见 LICENSE 文件。 ## 联系方式 如有问题或建议,请通过以下方式联系我们: - 项目地址: