# biopipe

**Repository Path**: battlerabbit/biopipe

## Basic Information

- **Project Name**: biopipe
- **Description**: biopipe是一款轻量级的生信流程框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-29
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BioPipe生信流程框架

## 1. 项目介绍

BioPipe是一个轻量级生信流程框架，旨在为生物信息学研究人员提供一个统一的生信流程，方便他们进行高效、准确的分析。BioPipe基于Python语言开发，具有以下特点：

1. 易于部署：BioPipe基于Python语言开发，可以轻松部署到本地或服务器上，并通过命令行进行生信流程的管理。本流程框架无需任何第三方软件或第三方python库依赖，仅需要 `python3 >= 3.6`，可以直接上手使用。
2. 易于上手：BioPipe提供了轻量级的模块和流程衔接接口，全程使用python基本语法进行流程编写，零学习成本，用户可以在30分钟之内快速上手使用BioPipe搭建复杂的生信流程。
3. 高效运行：BioPipe的模块化设计，使得流程的运行速度更快，并通过多线程并行处理提升运行效率。
4. 便于运维：BioPipe提供了完善的日志记录功能，可以记录每个模块的运行信息，方便用户追踪和分析流程运行情况。
5. conda支持：BioPipe原生支持conda后台，可以方便地为每个模块指定对应的conda运行环境。

## 2. 使用说明

BioPipe的开发基于Python语言，并使用了Python的多线程、日志记录、命令行接口等技术。

### 2.1 安装部署

BioPipe的安装部署非常简单，只需要安装Python3环境，然后通过git clone或下载压缩包安装BioPipe即可。git clone命令如下：`git clone https://gitee.com/battlerabbit/biopipe.git`

### 2.2 运行流程

BioPipe的运行流程如下：

1. 准备数据：用户需要准备好待分析的数据，并将数据放到任意可访问的目录下。
2. 配置json：用户需要在配置文件中配置流程运行的各种参数，配置文件的格式为json，除了必须的字段之外，可以根据流程需要，添加其他字段。**注意：配置文件中以下字段必须被包含，json示例如下：**
```json
{
    "project_name": "分析项目名称",
    "sample_info": [
        {
            "sample_name": "样本名称1",
            "fastq1":"fastq1路径",
            "fastq2":"fastq2路径，若为单端数据则此项为空字符串",
            "comments": "样本备注，若无则为空字符串",
            "group": "样本分组信息",
            "species": "物种名称",
            "date": "样本采集日期"
        }，
        // 补充其他样本信息
    ],
    "analysis": {
        "output_dir": "分析输出目录",
        "pipeline_name": "流程名称，需要和pipelines目录下的pipeline名称一致",
        "parallel_jobs": 12, // 并行处理的线程数，不小于1的整数
        "date": "分析日期",
        "database_dir": "数据库路径，若无则为空字符串",
        "pipeline_root": "biopipe所在的目录，用于指定配置文件的路径",
    }
}
```
3. 运行流程：用户在命令行中运行BioPipe，并指定配置文件的路径，BioPipe会自动读取配置文件，并按照配置文件中的参数运行流程。命令行参数如下：
    
    - -i：指定json配置文件的路径
    - --stdout：全局标准输出文件路径，若不指定，则输出到屏幕
    - --stderr：全局标准错误文件路径，若不指定，则输出到屏幕
    - --dryrun：仅打印任务列表，不运行流程（**仅开发调试时使用，正常分析流程时不要加上此参数**）

```bash
# python3 ./main.py -h
usage: main.py [-h] -i INPUT [--stdout STDOUT] [--stderr STDERR] [--dryrun]

Run pipeline

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        Input json file
  --stdout STDOUT       Global stdout file
  --stderr STDERR       Global stderr file
  --dryrun              Dry run, only print tasks
```


4. 结果输出：BioPipe的运行结果会保存在配置文件中指定的`output_dir`目录下，包括模块日志文件、流程运行的中间结果、最终结果和报告文件等。目录结构总体由流程所控制，但是输出目录下会包含一个标准logs目录和html报告文件需要用户注意：logs目录下存放每个模块的运行日志，每个模块的日志文件以模块名称命名，加以`_stdout.log`或`_stderr.log`后缀区分标准输出和标准错误。html报告文件是流程运行的最终结果。

## 3. 开发者指南

BioPipe的开发者指南主要介绍BioPipe的开发流程、模块开发规范、模块测试规范、代码风格规范等。

### 3.1 初始化流程

BioPipe的初始化流程如下：

1. 在pipelines目录下新建一个目录，此目录是分析流程的所有必须文件所在地，可以随意给此目录命名，尽量不要使用中文或其他有可能引起python3语法错误的字符，比如`!`、`@`、`#`、`'\'`等。

2. 在此目录下新建两个个必须的文件夹：`modules\`、`report_source\`和一个固定名称的`module_config.py`脚本文件，其他文件夹或文件可根据流程需要自行创建。

3. 在`module_config.py`脚本文件中，导入必须的模块，并定义一个必须的函数`write_tasks(input_json_path: str, pipeline_root: str, pipeline_name: str) -> dict`用于生成任务列表。函数的输入参数为json配置文件的路径、BioPipe所在的目录、流程名称，函数返回一个字典，字典的键为`"tasks"`和`"report_data"`，分别对应任务列表和报告数据。后面会详细描述任务列表和报告数据如何构建。除了这个函数之外，可以根据需要自行创建其他函数，这些函数会在运行时被调用。

### 3.2 编写分析模块

BioPipe的最小管理单元是一个分析模块，一个流程由多个模块组合而成，模块的呈现形式为linux的shell脚本，此部分介绍如何编写BioPipe的分析模块。

#### 3.2.1 模块的基本结构

在`modules`目录下新建一个模块shell脚本，请务必以`.sh`结尾，否则流程无法识别。模块的基本结构分为两个部分：**头部配置**和**主体代码**。

**头部配置**：用于定义当前模块运行的相对路径，以及模块的运行conda环境和输出参数，头部配置的格式如下：

```bash
##conda_env:ensembly?
#?work_dir:03_assembly?
#%assembly_gtf:^sample_name^/^sample_name^_assembly.gtf?
```

1. `##conda_env:xxx?`：指定当前模块的运行环境，xxx为conda环境名称，必填项。
2. `#?work_dir:xxx?`：指定当前模块的工作目录，xxx为相对路径，必填项。
3. `#%xxx:^yyy^?`：指定当前模块的输出文件路径，xxx为输出参数名称，两个"^"之间的yyy为输出文件的相对项目输出目录的路径，用于传送给python流程记录模块输出文件路径，如果有多个输出参数，可以写多行，若无输出文件，则此项可省略。

**主体代码**：模块的主体代码部分，用于定义当前模块的具体操作，格式为shell脚本，主体代码的格式如下：

```bash
species=^species^
DB=^DB^
sample_name=^sample_name^

mkdir -p ${sample_name}

cd ${sample_name}

if [ ${species} == "human" ]; then
    gtffile=${DB}/reference/${species}/GRCh38/Homo_sapiens.GRCh38.111.gtf
elif [ ${species} == "mouse" ]; then
    gtffile=${DB}/reference/${species}/GRCm39/Mus_musculus.GRCm39.111.gtf
else
    echo "species not supported"
    exit 1
fi

stringtie !{bam}? -G ${gtffile} -p 8 -o ${sample_name}_assembly.gtf
```

1. `species=^species^`：指定当前模块的输入参数，species为输入参数名称，"^"之间的species为输入参数的值，此格式的参数为python传入的字符串类型，可以直接使用，非必填。
2. `!{bam}?`：指定当前模块的输入文件，bam为输入文件名称，"!{bam}?"中的"bam"表示从python输出进来的字符串类型，一般代表输入文件路径，非必填。

#### 3.2.2 模块的命名

模块shell脚本应该以模块名称命名，以`.sh`结尾，比如`01_mapping.sh`、`02_assembly.sh`等，或者使用简写，比如`map.sh`、`asm.sh`等。

#### 3.2.3 将模块添加入流程

在`module_config.py`脚本文件中，在`write_tasks`函数中初始化一个`task.Task`对象，这个对象用于将上述模块脚本和参数添加到任务列表中，`task.Task`初始化方式如下：

```python
quant = task.Task(
    name=f'quant', 
    shell_template="quant.sh", 
    input_files={"bams": " ".join(bam_paths), "bams_index": " ".join(bam_index_paths),"sample_sheet": create_samplesheet.output_files["samplesheet"], "species":species, "DB": database_dir},
    time_out=6000, 
    variables={"species":species, "DB": database_dir},
    parients=[alignment,create_samplesheet],
    pipeline_root_dir=pipeline_root,
    pipeline_name=pipeline_name,
    project_output_dir=out_dir)
```

1. `name=f'quant'`：指定当前模块的名称，必填项。
2. `shell_template="quant.sh"`：指定当前模块的shell脚本文件名，无需带`.sh`后缀，必填项。
3. `input_files={"bams": " ".join(bam_paths), "bams_index": " ".join(bam_index_paths),"sample_sheet": create_samplesheet.output_files["samplesheet"], "species":species, "DB": database_dir}`：指定当前模块的输入文件，输入一个python字典，key值对应模块shell中的`!{xxx}?`的"xxx"部分，value值是实际文件路径，流程运行过程中会进行真实路径的替换，如果模块shell中未定义输入文件，则非必填，否则必填。
4. `time_out=6000`：指定当前模块的运行时间限制，单位为秒，暂未生效，随意填写一个非零正int数值，必填。
5. `variables={"species":species, "DB": database_dir}`：指定当前模块的运行参数，一个python字典，key值对应模块shell中的`^xxx^`的"xxx"部分，value值是实际参数值，流程运行过程中会进行真实参数的替换，如果模块shell中未定义参数，则非必填，否则必填。
6. `parients=[alignment,create_samplesheet]`：指定当前模块的依赖模块，一个python列表，元素为依赖模块的`task.Task`对象，如果当前模块依赖其他模块，则必填， 否则BioPipe认为此模块没有依赖项。
7. `pipeline_root_dir=pipeline_root`：指定当前模块的BioPipe所在目录，必填。
8. `pipeline_name=pipeline_name`：指定模块所属的流程名称，必填。
9. `project_output_dir=out_dir`：指定当前项目的输出目录，必填。

### 3.3 编写流程文件

BioPipe的流程文件是`module_config.py`脚本，用于生成任务列表和报告数据。开发者进行流程搭建过程中只需要关注此文件即可，无需修改其他python脚本。

#### 3.3.1 关联模块

串联模块是指多个模块之间存在依赖关系，即前一个模块的输出作为后一个模块的输入，这种模块的连接方式称为串联。在`module_config.py`脚本文件中，通过`task.Task`对象的`parients`参数指定模块之间的依赖关系，`parients`参数是一个列表，列表中的元素为依赖模块的`task.Task`对象。

开发者在初始化多个模块的过程中，无需关注初始化模块的顺序，所有依赖关系都通过`parients`参数来指定。示例如下：

```python
plot_groups = task.Task(
    name=f'plot_groups', 
    shell_template="plot_groups.sh", 
    input_files={"sample_sheet": create_samplesheet.output_files["samplesheet"], "count_matrix": quant.output_files["gene_matrix"]},
    time_out=6000, 
    variables={"pipeline_root_dir": pipeline_root},
    parients=[quant],
    pipeline_root_dir=pipeline_root,
    pipeline_name=pipeline_name,
    project_output_dir=out_dir)


quant = task.Task(
    name=f'quant', 
    shell_template="quant.sh", 
    input_files={"bams": " ".join(bam_paths), "bams_index": " ".join(bam_index_paths),"sample_sheet": create_samplesheet.output_files["samplesheet"], "species":species, "DB": database_dir},
    time_out=6000, 
    variables={"species":species, "DB": database_dir},
    parients=[alignment,create_samplesheet],
    pipeline_root_dir=pipeline_root,
    pipeline_name=pipeline_name,
    project_output_dir=out_dir)
```

上面的示例中，`plot_groups`模块依赖于`quant`模块的输出，`quant`模块也可以在`plot_groups`之后进行初始化，不会影响流程的运行。若模块之间存在循环依赖关系，则会导致BioPipe无法正常运行，请检查模块之间的依赖关系是否正确。

**注意：每个模块的`name`必须独一无二，如果有重复，则BioPipe会报错。**

#### 3.3.2 任务列表

任务列表是BioPipe运行流程的核心，它记录了每个模块的运行参数、输入文件、输出文件、运行时间等信息，用于后续流程的调度和运行。在`module_config.py`脚本文件中，通过`write_tasks`函数返回的字典，键为`"tasks"`，值为任务列表，任务列表是一个列表，列表中的元素为`task.Task`对象。一个简单的示例如下：

```python
def write_tasks(input_json_path: str, pipeline_root: str, pipeline_name: str) -> dict:
    ALL_TASKS = list() # 初始化任务列表
    dispaly_data = dict() # 初始化报告数据
    import json # 导入json模块
    with open(input_json_path, 'r') as f: # 读取json配置文件
        config_json = json.load(f)
        samples = config_json['sample_info']
        out_dir = config_json['analysis']['output_dir']
        database_dir = config_json['analysis']['database_dir']

    # 初始化create_samplesheet模块
    create_samplesheet = task.Task(name='create_samplesheet',shell_template="create_samplesheet.sh", input_files={"config_json": input_json_path}, time_out=600, variables={"pipeline_root": pipeline_root}, parients=[], pipeline_root_dir=pipeline_root, pipeline_name=pipeline_name, project_output_dir=out_dir)

    ALL_TASKS.append(create_samplesheet) # 将create_samplesheet模块添加到任务列表中

    return {"tasks": ALL_TASKS, "report_data": dispaly_data} # 返回任务列表和报告数据，注意，本示例的报告数据为空，正常情况下还需要根据流程需要生成报告数据。
```

开发者需要将每个模块的`task.Task`对象添加到任务列表中，在这个示例中，`create_samplesheet`模块已经被添加到变量名为`ALL_TASKS`的任务列表中，其他模块的初始化代码可以类似添加。

### 3.4 编写报告内容

#### 3.4.1 初始化段落

段落是报告的基本单元，在BioPipe的报告中，最多支持两级段落，即一级段落和二级段落。段落的初始化也是在`module_config.py`脚本文件中，通过`report.Paragraph`对象来实现，`Paragraph`对象初始化方式如下：

```python
p1 = report.Paragraph(label="p1", header="1. RNA-Seq 数据QC", level=1)
```

1. `label="p1"`：指定段落的标签，必填。
2. `header="1. RNA-Seq 数据QC"`：指定段落的标题，必填。
3. `level=1`：指定段落的级别，1表示一级段落，2表示二级段落，必填。

#### 3.4.2 添加段落文字

在`module_config.py`脚本文件中，通过`Paragraph`对象的`create_text`方法来将python字符串转为html的段落文字，并通过`Paragraph`对象的`add_text`方法将段落文字添加到段落中，示例如下：

```python
p1 = report.Paragraph(label="p1", header="1. RNA-Seq 数据QC", level=1)
p1_text = report.create_text("RNA-Seq 数据质控，展示同批次所有样本的原始数据质控结果，包括碱基质量分布图和质控前后数据量统计。")
p1.add_text(p1_text)
```

#### 3.4.3 添加图片和表格

在`module_config.py`脚本文件中，给段落添加图片和表格前，需要先准备好图片和表格文件，图片文件格式为`.png`，表格文件格式为`.tsv`或`tab`分隔的文本文件。并将上述文件路径添加进`report_data`中，这样做的主要目的是将数据添加进模板的渲染数据中，以便在报告中直接使用，无需依赖原始结果文件。开发者需要注意，对于表格或图片文件，要注意内容大小，过大的图片或表格文件会导致报告生成时间过长，影响运行效率。示例如下：

```python
dispaly_data = dict() # 初始化报告数据

dispaly_data[f'{sample_name}_quality_plot'] = fastq_qc_plot.output_files["quality_plot"] # 将fastq_qc_plot模块的输出图片文件路径添加到报告数据
p12_image_select_list.append(f'{sample_name}_quality_plot') # 将图片文件名添加到图片选择列表，用于html网页的图片选择器

dispaly_data['gene_matrix'] = quant.output_files["gene_matrix"]+'{table}' # 将quant模块的输出表格文件路径添加到报告数据，并添加"{table}"标记，以便在报告模板中直接渲染成表格数据，无需依赖源文件
max_line_dict['gene_matrix'] = 30 # 设置表格最大显示行数，超过此行数的表格数据将被截断

report_data = {"dispaly_data": dispaly_data, "paragraph_list": paragraph_list, "max_line_dict": max_line_dict, "template_path": f"{pipeline_root}/pipelines/{pipeline_name}/report_source/template.html", "report_html_path":f"{out_dir}/report.html"} # report_data是一个字典，用于渲染报告模板，其中"dispaly_data"键对应报告模板的渲染数据，"paragraph_list"键对应报告的段落列表，后续会详细介绍，"max_line_dict"键对应报告模板中表格的最大显示行数，"template_path"键对应报告模板的路径，"report_html_path"键对应报告的输出路径。
```

接下来需要将需要展示的图片和表格文件数据添加到具体的段落中，添加图片和表格分别使用`Paragraph`对象的`create_complex_image`和`create_complex_table`函数，示例如下：

```python
p12 = report.Paragraph(label="p12", header="1.2 过滤后数据质控", level=2) # 初始化二级段落
p12_text = report.create_text("过滤后数据质控，展示过滤后数据质控结果，包括碱基质量分布图和质控前后数据量统计。") # 添加段落文字
p12_text += report.create_complex_image("p12_image", p12_image_select_list, "质控结果图", 1) # 添加图片，添加上述示例中的图片选择列表，参数为html中的图片标签、图片选择列表、图片标题、图片选择器数量
p12.add_text(p12_text) # 将段落文字和图片添加到段落中

p2 = report.Paragraph(label="p2", header="2. 计算基因Counts矩阵", level=1) # 初始化一级段落
p2_text = report.create_text("计算基因Counts矩阵，包括每个样本的基因表达量矩阵。") # 添加段落文字
header = {"Geneid":"Ensembl基因ID", "Chr":"染色体", "Start":"基因起始位置", "End":"基因终止位置", "Strand":"染色体方向", "Length":"基因长度", "transcript_id":"Ensembl转录本ID", "gene_name":"基因名称"} # 表格的表头
for i in range(len(samples)): # 遍历每个样本，将样本名称补充在表头中
    header[f"{samples[i]['sample_name']}.bam"] = f"{samples[i]['sample_name']}的Counts"
p2_text += report.create_complex_table("p2_table", ["gene_matrix"], header, "基因表达量矩阵", 1) # 添加表格，添加上述示例中的表格标签、表格选择列表、表头、表格选择器数量
p2.add_text(p2_text) # 将段落文字和表格添加到段落中
```

`create_complex_image`函数参数说明如下：

1. `label`：指定图片的标签，字符串，必填。
2. `image_list`：指定图片选择列表， 列表，元素为字符串，必填。
3. `title`：指定图片标题，字符串，必填。
4. `select_num`：指定图片选择器数量，可选数值为1或2，分别表示关联一个或两个图片选择器，int类型，必填。

`create_complex_table`函数参数说明如下：

1. `label`：指定表格的标签，字符串，必填。
2. `table_list`：指定表格选择列表，列表，元素为字符串，必填。
3. `header`：指定表格的表头，字典，键为字符串，值为字符串，必填。
4. `title`：指定表格标题，字符串，必填。
5. `select_num`：指定表格选择器数量，可选数值为1或2，分别表示关联一个或两个表格选择器，int类型，必填。

#### 3.4.4 添加段落分隔行

在`module_config.py`脚本文件中，通过`Paragraph`对象的`add_section_end`方法来添加段落分隔行，用于分隔不同模块的报告内容，示例如下：

```python
p12.add_section_end() # 添加段落分隔行
```

#### 3.4.5 串联段落

在`module_config.py`脚本文件中，需要将不同段落串联起来到一个list中，list顺序即是html报告中段落的顺序，示例如下：

```python
paragraph_list = [p1, p12, p2] # 串联段落
```

#### 3.4.6 生成报告数据并返回

在`module_config.py`脚本文件中，需要将串联好的段落和html展示的图片和表格数据添加到报告数据中，并返回报告数据，示例如下：

```python
report_data = {"dispaly_data": dispaly_data, "paragraph_list": paragraph_list, "max_line_dict": max_line_dict, "template_path": f"{pipeline_root}/pipelines/{pipeline_name}/report_source/template.html", "report_html_path":f"{out_dir}/report.html"} # report_data是一个字典，用于渲染报告模板，其中"dispaly_data"键对应报告模板的渲染数据，"paragraph_list"键对应报告的段落列表，后续会详细介绍，"max_line_dict"键对应报告模板中表格的最大显示行数，"template_path"键对应报告模板的路径，"report_html_path"键对应报告的输出路径。
    
return {"tasks": ALL_TASKS, "report_data": report_data} # 返回任务列表和报告数据，本示例的任务列表构建过程没有展示，正常情况下需要将任务列表添加到报告数据中。
```

## 技术支持

如有疑问，请联系作者：<tianyu_cui@outlook.com>。

## 许可证

本项目采用MIT许可证，详情请参见[LICENSE](https://gitee.com/battlerabbit/biopipe/blob/master/LICENSE)文件。