Bioconvert开发者指南：生物信息格式转换工具开发详解

项目概述

Bioconvert是一个强大的生物信息学格式转换工具，支持超过200种不同格式之间的转换。本文将为开发者提供详细的开发指南，帮助您了解如何为Bioconvert贡献新的格式转换器。

开发环境搭建

虚拟环境配置

推荐使用Python虚拟环境进行开发：

python3.7 -m venv py37
source py37/bin/activate

依赖安装

安装开发所需的额外依赖：

pip install -e .[testing]

注意：某些依赖如pygraphviz需要系统级依赖graphviz，在基于Debian的系统上需要安装libcgraph6、libgraphviz-dev和graphviz包。

添加新转换器

基本结构

Bioconvert主要支持一对一格式转换。每个转换器应放在bioconvert目录下，命名遵循input2output.py格式，全部小写。

例如，添加FastQ到FastA的转换器：

1. 创建文件fastq2fasta.py
2. 定义转换类FASTQ2FASTA（全部大写）

快速初始化

可以使用内置工具快速生成转换器模板：

bioconvert_init -i fastq -o fasta > fastq2fasta.py

类结构示例

"""Convert :term:`FastQ` format to :term:`FastA` formats"""
from bioconvert import ConvBase

__all__ = ["FASTQ2FASTA"]

class FASTQ2FASTA(ConvBase):
    _default_method = "v1"

    def __init__(self, infile, outfile):
        super().__init__(infile, outfile)

    @requires(external_library="awk")
    def _method_v1(self, *args, **kwargs):
        # 转换逻辑实现
        self.execute(cmd)

关键组件说明

1. 文档字符串：首行应说明转换功能，使用术语表中的术语
2. 类命名：全部大写，格式为INPUT2OUTPUT
3. 默认方法：_default_method指定默认转换方法
4. 转换方法：以_method_为前缀，后接方法名称

方法实现规范

方法装饰器

Bioconvert提供了多种装饰器来标记方法特性：

1. @in_gz：标记方法能处理.gz压缩输入
2. @compressor：自动处理输入解压和输出压缩
3. @out_compressor：仅处理输出压缩
4. @requires：声明方法依赖

依赖声明示例

@requires_nothing  # 纯Python实现
def _method_python(self):
    pass

@requires(python_library="mappy")  # 依赖Python库
def _method_mappy(self):
    pass

@requires("awk")  # 依赖外部工具
def _method_awk(self):
    pass

测试开发

测试文件规范

测试文件应放在test/data目录下，命名格式为ext/converter_name.ext。

测试用例示例

import pytest
from bioconvert.fastq2fasta import FASTQ2FASTA

@pytest.mark.parametrize("method", FASTQ2FASTA.available_methods)
def test_fastq2fasta(method):
    infile = "test/data/fastq/test.fastq"
    expected = "test/data/fasta/test.fasta"
    with TempFile(suffix=".fasta") as tempfile:
        converter = FASTQ2FASTA(infile, tempfile.name)
        converter(method=method)
        assert md5(tempfile.name) == md5(expected)

测试执行

运行全部测试：

pytest test/ -v

运行特定测试：

pytest test/test_fastq2fasta.py -v

性能基准测试

Bioconvert内置了性能比较框架：

from bioconvert import Benchmark
from bioconvert.fastq2fasta import FASTQ2FASTA

converter = FASTQ2FASTA(infile, outfile)
b = Benchmark(converter)
b.plot()

文档更新

添加新转换器后需要更新文档：

1. 在doc/ref_converters.rst中添加模块引用
2. 更新README.rst文件
3. 如有新格式，更新术语表glossary.rst

代码规范

遵循PEP8规范，特别注意：

• 类与函数间2个空行
• 方法间1个空行
• 运算符周围空格
• 行宽不超过80字符
• 充分的文档注释

高级主题

多格式转换

Bioconvert支持一对多和多对一转换，使用下划线连接格式名称，如fastq2fasta_qual。

格式规范

在core/extensions.py中添加新格式的扩展名。

格式元数据

文档中的格式应包含以下元数据：

• Type: sequence, assembly, alignment等
• Format: binary或human-readable
• Status: deprecated, included等

持续集成

添加新转换器时，需在CI配置中添加对应的测试工作流。

总结

本文详细介绍了为Bioconvert开发新转换器的完整流程，从环境搭建、代码实现到测试验证和文档更新。遵循这些规范可以确保您的贡献与项目保持一致性，并易于维护。Bioconvert的强大之处在于其模块化设计和丰富的转换方法比较功能，期待您的贡献能进一步丰富这个生物信息学工具生态系统。