# PyBIP

**Repository Path**: coding_playground/pybip

## Basic Information

- **Project Name**: PyBIP
- **Description**: Python Boltz/Protenix Input Generator 是一个Python脚本，旨在简化为生物信息学工具 Boltz-2 (输出YAML格式) 和 Protenix (输出JSON格式) 生成输入文件的过程。它能够解析FASTA格式的蛋白质、DNA、RNA序列文件，CCD配体信息，以及包含化合物ID和SMILES的CSV文件，然后生成相应的结构化输入文件。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: 0.2.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-09
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python Boltz/Protenix Input Generator

## 简介

`Python Boltz/Protenix Input Generator` (简称 PyBIP) 是一个Python脚本，旨在简化为生物信息学工具 **Boltz-2** (输出YAML格式) 和 **Protenix** (输出JSON格式) 生成输入文件的过程。它能够解析FASTA格式的蛋白质、DNA、RNA序列文件，CCD配体信息，以及包含化合物ID和SMILES的CSV文件，然后根据所选工具的要求生成相应的结构化输入文件。

## 功能特性

*   **多类型序列支持**: 从FASTA文件读取蛋白质、DNA、RNA序列，并支持指定每个序列的复制数量。
*   **CCD配体支持**: 支持通过命令行指定CCD配体及其数量。
*   **化合物数据集成**: 从CSV文件中读取化合物ID和SMILES，并将其整合到生成的输入文件中。
*   **Boltz-2 YAML生成**:
    *   为每种序列和CCD配体生成带有唯一ID的条目。
    *   为CSV中的每个化合物生成一个独立的YAML文件，化合物在YAML中固定ID为`B`。
*   **Protenix JSON生成**:
    *   为每种序列和CCD配体生成条目，**不包含ID字段**。
    *   将CSV中的每个化合物作为一个独立条目整合到一个JSON文件中，化合物不包含ID字段。
    *   在输出JSON文件同目录下生成一个随机种子文件 `seed.txt`。
*   **统一错误处理**: 使用自定义异常 `InputGeneratorError` 和错误码，提供清晰的错误信息。
*   **详细日志**: 提供生成过程中的信息、警告和错误日志。
*   **PEP8兼容**: 代码风格符合Python PEP8规范。
*   **类型注解**: 广泛使用类型注解，增强代码可读性和可维护性。
*   **单元测试**: 包含完整的单元测试，确保代码质量和功能正确性。

## 版本

当前版本: 0.2.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` 两个主命令。

### 通用参数

以下参数可用于 `boltz` 和 `protenix` 子命令，用于指定输入数据：

*   `--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_P4G:1,CCD_6OI:2"`
*   `--csv CSV_FILE_PATH`: **(必需)** 包含化合物ID和SMILES的CSV文件路径。CSV文件必须包含 `id` 和 `smiles` 两列。

### 1. 生成 Boltz-2 YAML 输入文件

使用 `boltz` 子命令生成 Boltz-2 YAML 文件。

**特定参数**:

*   `--output-dir DIR_PATH`: YAML文件的输出目录（默认: `.` 当前目录）。

**输出文件结构**:

*   每个化合物会生成一个独立的YAML文件，命名格式为 `[第一个序列文件基础名]_[化合物ID].yaml`。
*   YAML文件中的序列（蛋白质、DNA、RNA）和CCD配体都会被分配一个唯一的 `id` (如 `P1`, `D2`, `CCD_P4G`)。
*   从CSV读取的化合物在YAML中将固定使用 `id: B`。

**示例**:

假设您有以下文件：
*   `protein.fasta` (包含一个蛋白质序列)
*   `compounds.csv` (内容如下: `id,smiles\nCOMP1,CCCC\nCOMP2,O=C(N)C`)

```bash
python pybip.py boltz \
    --protein "protein.fasta:1" \
    --ccd "CCD_P4G:1" \
    --csv compounds.csv \
    --output-dir boltz_inputs
```

这将会在 `boltz_inputs` 目录下生成类似的文件：
*   `protein_COMP1.yaml`
*   `protein_COMP2.yaml`

`protein_COMP1.yaml` 的大致内容:
```yaml
version: 1
sequences:
- proteinChain:
    id: P1
    sequence: YOUR_PROTEIN_SEQUENCE_HERE
    count: 1
- ligand:
    id: CCD_P4G
    ligand: CCD_P4G
    count: 1
- ligand:
    id: B
    smiles: CCCC
    count: 1
properties:
- affinity:
    binder: B
```

### 2. 生成 Protenix JSON 输入文件

使用 `protenix` 子命令生成 Protenix JSON 文件。

**特定参数**:

*   `--output FILE_PATH`: 输出JSON文件的名字（默认: `input.json`）。

**输出文件结构**:

*   所有化合物的条目都会被整合到一个JSON文件中。
*   JSON文件中的序列（蛋白质、DNA、RNA）和CCD配体 **不会** 包含 `id` 字段。
*   JSON文件中的化合物也不会包含 `id` 字段，只有 `ligand` 和 `count`。
*   在输出JSON文件所在的目录下，会生成一个名为 `seed.txt` 的文件，其中包含一个随机生成的整数种子。

**示例**:

```bash
python pybip.py protenix \
    --protein "protein.fasta:1" \
    --dna "dna.fasta:1" \
    --ccd "CCD_6OI: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
                }
            },
            {
                "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
                }
            },
            {
                "ligand": {
                    "ligand": "O=C(N)C",
                    "count": 1
                }
            }
        ],
        "name": "protein_COMP2"
    }
]
```

## 单元测试

项目包含完整的单元测试，您可以使用以下命令运行测试：

```bash
python tests/test_utils.py
```

## 项目结构

```
pybip/
├── pybip.py              # 主脚本文件
├── exceptions.py          # 自定义异常类
├── commands/              # 命令相关模块
│   ├── __init__.py
│   ├── base.py           # 命令基类
│   ├── boltz.py          # Boltz命令实现
│   └── protenix.py       # Protenix命令实现
├── utils/                # 工具函数
│   ├── __init__.py
│   ├── fasta.py          # FASTA文件读取
│   ├── csv_reader.py     # CSV文件读取
│   └── seed.py           # 随机种子生成
├── tests/                # 单元测试
│   └── test_utils.py     # 工具函数测试
├── requirements.txt       # 依赖列表
├── setup.py              # 安装配置
└── README.md             # 项目文档
```

## 错误处理

脚本使用自定义的 `InputGeneratorError` 异常来处理各种预期错误，例如文件未找到、CSV格式错误、参数解析失败等。当发生此类错误时，脚本会输出详细的错误信息到标准错误流，并以相应的错误码退出。

## 许可证

本项目采用 GNU General Public License v3 (GPLv3) 许可证。详见 LICENSE 文件。

## 联系方式

如有问题或建议，请通过以下方式联系我们：

*   邮箱: dengzho5068@foxmail.com
*   项目地址: https://gitee.com/coding_playground/pybip

## 版本历史

*   **0.2.0** (2025-11-26):
    *   重构了代码结构，增强了模块化和可维护性
    *   完善了文档
    *   修复了一些bug

*   **0.1.0** (2025-10-16):
    *   初始版本
    *   支持Boltz-2 YAML生成
    *   支持Protenix JSON生成
    *   支持多类型序列和CCD配体
    *   支持化合物数据集成