davelabhub/qcparser

QCParser

镜像概述和主要用途

QCParser是一款命令行工具，用于从主流生物信息学输出文件中解析信息，并将数据存储为通用格式（QCReport）。其模块化设计允许用户添加新模块以满足特定需求，旨在为生物信息学工作流提供集中式质量控制解决方案。

核心功能和特性

工作流集中式质量控制

• 将非结构化QC数据解析为标准化JSON格式
• 聚合功能支持将所有QC信息合并为单个报告
• 跨工作流组合QC信息，生成项目级别的统一QC报告

内置主流工具支持

• FastQC
• Bedtools Intersect
• Samtools Depth、Flagstat、Idxstat
• Trimmomatic
• Mosdepth
• Picard CollectInsertSizeMetrics

模块化/可扩展性

• 轻松添加或自定义模块以解析任何非结构化数据文件

详细的类型/错误检查

• 内置检查机制，当输入数据与预期结构不匹配时发出警告或退出
• 若未找到所需数据类型，提供清晰的错误提示

使用场景和适用范围

适用于生物信息学数据分析流程中，需要对多种工具输出的质量控制数据进行标准化整合、解析和报告生成的场景。尤其适合需要跨样本、跨工具整合QC信息的项目，以及需要自定义解析特定格式数据的研究需求。

系统设置

QCParser目前仅支持Linux系统。需安装并配置以下工具：

1. Python v2.7.*

检查Python版本：

sh
$ python -V
Python 2.7.10

安装方法：访问Python官方网站下载并安装对应版本。

2. Python包：numpy、scipy、pandas、matplotlib

需通过pip安装上述包。安装pip后，执行以下命令：

sh
# 升级pip
sudo pip install -U pip

pip install numpy
pip install scipy
pip install pandas
pip install matplotlib

3. 克隆QCParser仓库

sh
# 克隆仓库
git clone https://github.com/alexwaldrop/QCParser.git

使用方法

QCParser通过指定可用的解析器模块解析单个输入文件，并生成名为QCReport的输出文件。运行顶层QCParser.py程序可查看可用解析模块：

sh
./QCParser.py <tool> [tool_args]
工具列表：
    SamtoolsDepth		    从Samtool depth输出中汇总覆盖深度
    Cbind		            按列连接两个或多个QCReport（如合并同一样本的多个报告）
    FastQC		            解析Fastqc文本输出
    PrintTable		        将QCReport输出为制表符分隔的表格
    PicardInsertSize        解析Picard InsertSize Metrics输出
    MosdepthDist		    解析Mosdepth的读长深度分布输出
    SamtoolsIdxstats	    解析Samtools idxstats输出（v1.3及更高版本）
    TNADemuxReport		    解析TNA demux脚本的RNA/DNA报告
    Rbind		            按行连接两个或多个QCReport（如合并多个样本的报告）
    BedtoolsIntersect	    从Bedtools Intersect输出中汇总重叠百分比
    SamtoolsFlagstat	    解析Samtools flagstat输出（v1.3及更高版本）
    GATKCollectReadCount	统计映射到基因组特征的总读长数
    Trimmomatic		        解析Trimmomatic的标准错误日志

每个解析器模块都有自己的命令行参数，可通过--help查看：

sh
./QCParser.py FastQC --help

FastQC模块示例参数：

解析Fastqc文本输出

可选参数:
-h, --help            显示此帮助消息并退出
-v                    增加程序详细程度。多个-v增加详细级别：0=错误 1=错误+警告 2=错误+警告+信息 3=错误+警告+信息+调试
-i INPUT_FILE, --input INPUT_FILE
    FastQC输出文件路径（fastqc_data.txt）
-s SAMPLE_NAME, --sample SAMPLE_NAME
    样本名称
-n NOTE, --note NOTE  
    关于被解析文件的备注

QCReport输出格式

QCParser将非结构化信息解析为统一的JSON文件，称为QCReport。本质上，QCReport是具有一致列类型的表格的JSON表示。

QCReport语法定义

QCReport        ::= { QCSample* }
QCSample        ::= "SampleName" : [ QCEntry+ ]
QCEntry         ::= {   
                        "Module" : String,
                        "Name"   : String,
                        "Note"   : String,
                        "Source" : String,
                        "Value"  : Int | String
                    }

通俗定义

QCParser生成的QCReport保证满足以下条件：

1. 是有效的JSON对象
2. 包含0个或多个QCSample
3. QCSample是包含1个或多个QCEntry的列表
4. QCEntry是包含以下信息的JSON对象：
   • Value: 从文件中解析的QC值
   • Name: QC值数据类型（如"Raw Reads"）
   • Source: QC值的源文件路径
   • Module: 用于解析源文件的QCParser模块
   • Note: 可选字段，用于添加额外信息

此外，QCReport还满足以下特性：

• 方正性：所有QCSample包含相同数量的QCEntry
• 有序性：所有QCSample包含相同的QCEntry数据类型，且顺序一致（若QCEntry由相同"Module"和"Name"产生，则视为等效）

示例QCReport

JSON格式

json
{
"Sample_1": 
    [
        {
        "Module": "FastQC", 
        "Name": "Total_Reads", 
        "Note": "rna raw fastqs", 
        "Source": "/home/sample_1/fastqc_data.txt", 
        "Value": 18346
        }, 
        {
        "Module": "FastQC", 
        "Name": "LQ_Reads", 
        "Note": "rna raw fastqs", 
        "Source": "/home/sample_1/fastqc_data.txt", 
        "Value": 0
        }
    ],
"Sample_2": 
    [
        {
        "Module": "FastQC", 
        "Name": "Total_Reads", 
        "Note": "rna raw fastqs", 
        "Source": "/home/sample_2/fastqc_data.txt", 
        "Value": 233990
        }, 
        {
        "Module": "FastQC", 
        "Name": "LQ_Reads", 
        "Note": "rna raw fastqs", 
        "Source": "/home/sample_2/fastqc_data.txt", 
        "Value": 59
        }
    ]
}

表格格式

Sample      Total_Reads LQ_Reads
Sample_1    18346       0
Sample_2    233990      59

QCReport操作功能

QCParser包含三个基本QCReport操作功能，用于合并来自多个文件、样本或工作流的QCReport。

1. PrintTable

将QCReport输出为TSV表格格式到标准输出：

sh
./QCReport PrintTable -i sample_1.qc_report.txt

2. Cbind

按列连接两个或多个具有相同样本的QCReport（适合同一样本的多个QCReport合并）：

sh
./QCReport Cbind -i sample_1.fastqc.qc_report.txt sample_1.trimmomatic.qc_report.txt

3. Rbind

按行连接两个或多个具有相同QCEntry的QCReport（适合多个样本的QCReport合并）：

sh
./QCReport Rbind -i sample_1.qc_report.txt sample_2.qc_report.txt

自定义解析器模块

QCParser的核心优势在于可扩展性，支持解析几乎任何数据类型。以下是创建自定义模块以解析新输入类型的步骤：

1. 创建新Python文件

在QCModules/Parsers目录下创建新Python文件。

2. 创建类构造函数

需满足以下条件：

• 继承BaseParser模块
• 仅接受sys_args作为参数
• 导入QCParseException用于抛出解析相关错误
• 重写BaseParser的DESCRIPTION字段（CLI帮助消息中显示）
• 重写BaseParser的INPUT_FILE_DESC字段（CLI帮助消息中显示输入文件类型）
• 调用super()实例化基类属性

python
from BaseParser import BaseParser
from QCModules.BaseModule import QCParseException

class MyNewParser(BaseParser):

    DESCRIPTION     = "这是一个测试类"
    INPUT_FILE_DESC = "生物信息学工具X的文本输出"

    def __init__(self, sys_args):
        super(MyNewParser, self).__init__(sys_args)

继承BaseParser后，新类自动集成到基础CLI：

sh
./QCParser.py --help
工具列表：
    SamtoolsDepth		    从Samtool depth输出中汇总覆盖深度
    ...
    MyNewParser             这是一个测试类

并继承工具特定CLI：

sh
./QCParser.py MyNewParser --help
usage: MyNewParser [-h] [-v] -i INPUT_FILE -s SAMPLE_NAME [-n NOTE]  

这是一个测试类

可选参数:
-h, --help            显示此帮助消息并退出
-v                    增加程序详细程度。多个-v增加详细级别：0=错误 1=错误+警告 2=错误+警告+信息 3=错误+警告+信息+调试
-i INPUT_FILE, --input INPUT_FILE
    生物信息学工具X的文本输出路径
-s SAMPLE_NAME, --sample SAMPLE_NAME
    样本名称
-n NOTE, --note NOTE  
    关于被解析文件的备注

3. 实现define_required_colnames()函数

声明类将从输入文件中解析的数据类型：

python
# 定义FastQC解析器类的输出数据类型
def define_required_colnames(self):
    return ["FastQC_Tests", "Total_Reads", "LQ_Reads", "Read_Len", "GC"]

QCParser使用此函数检查是否提取了所有所需数据类型，若缺失则退出并报错。

4. 实现parse_input()方法

该方法主要功能：

1. 从文件中解析所需数据类型并添加到QCReport
2. 检查输入文件格式是否正确

若检测到文件格式错误，抛出QCParseException：

python
# 检查文件是否为正确类型
if first_line and "FastQC" not in line:
    raise QCParseException("FastQC文件'%s'第一行不包含'FastQC'。请确认是fastq_data.txt文件。")
else:
    first_line = False

使用add_entry()方法添加数据点到QCReport：

python
# 将读长数量添加到QCReport
num_reads = line.split()[0]
self.add_entry(colname= "Num_Reads", value=num_reads)

（注：Module、Source和可选Note属性由类在实例化时自动设置）

高级主题：为模块CLI添加参数

如需添加额外命令行参数，可重写configure_arg_parser()方法。以下是SamtoolsDepth模块添加深度阈值参数的示例：

python
def configure_arg_parser(self, base_parser):
    base_parser = super(SamtoolsDepth, self).configure_arg_parser(base_parser)
    
    # 添加深度阈值选项
    base_parser.add_argument('--ct',
                            action='append',
                            dest='cutoffs',
                            default=[5],
                            type=int,
                            help="指定覆盖深度阈值，计算高于该深度的碱基百分比（整数）。可多次指定以设置多个阈值。")
    return base_parser

Docker支持

QCParser提供Docker镜像，可在任何安装Docker的环境中使用。

前提条件

需安装Docker客户端。检查Docker是否安装：

bash
$ sudo docker --version

若未安装，从Docker-client获取安装包。

拉取镜像

从https://hub.docker.com/拉取QCParser镜像：

bash
$ sudo docker pull alexwaldrop/qcparser:latest

运行容器

bash
$ sudo docker run --rm --user root alexwaldrop/qcparser:latest "./QCParser.py --help"

项目状态

QCParser正在积极开发中。如需请求功能，请联系下方作者。

作者

• https://github.com/alexwaldrop