Skip to content

overall_qc.md

Latest commit

 

History

History
253 lines (181 loc) · 13.1 KB

overall_qc.md

File metadata and controls

253 lines (181 loc) · 13.1 KB

docs/overall_qc.md - 整體品質控制 (Overall QC)

1. 模組定位與目標

整體品質控制模組負責收集整個 PowerBarcoder 流程的整體統計資料，包括原始資料品質、各處理階段的資料量變化，以及最終結果的統計摘要。此模組在整個統一 QC 流程中優先執行，為後續的 Locus 特定 QC 與序列推薦提供基礎資訊。

主要目標

  • 收集整個 PowerBarcoder 流程各階段的檔案清單和基本統計
  • 產生 CSV 格式的品質控制報告(整體報告)
  • 驗證序列處理結果的正確性
  • 提供基本的統計資料和 SQLite 資料庫儲存
  • 為後續的序列推薦系統提供統計基礎

設計理念

整體品質控制模組採用直接檔案統計方式，不依賴中間檔案，直接從原始及處理後的檔案收集資料。此方法提供更準確的統計結果，並減少中間檔案的依賴性。

在統一 QC 流程中的定位

整體品質控制在統一 QC 流程中優先執行，為後續的 Locus QC 與序列推薦系統提供基礎統計資訊：

graph TD
    A[run_qc_pipeline] --> B[save_overall_qc_report]
    B --> C[QCDataManager 收集 locus 資料]
    C --> D[SequenceRecommendationEngine 推薦]
    D --> E[export_csv Locus QC CSV]
    E --> F[QCSequenceExtractor 序列萃取]
Loading

執行特色：

  • 優先執行：確保為後續流程提供完整的統計基礎
  • 獨立運作：不依賴其他 QC 模組的結果
  • 全域視角：收集整個 PowerBarcoder 流程的統計概覽

以下示意資料請參考下方「CSV 範例」區塊；文件後段提供 canonical header 與範例行(以實作為準)。

另外要注意實作細節：collect_overall_qc_stats(config) 會回傳一個 List[Tuple]，每筆 tuple 的格式為 (None, step, avg_q, err_q, num_seqs, sum_len, min_len, max_len)，而 insert_overall_qc_report() 會在寫入資料庫前把每筆 tuple 的第一個元素(None)移除(見實作中的 [entry[1:] for entry in stats_entries])，這是實作上的約定用於保持與 DB 欄位對應的一致性。此重建行為可避免舊資料混入新報告中，詳情見 src/qc/save_overall_qc_report.py。

  • 主要實作檔案：src/qc/save_overall_qc_report.py(入口：save_overall_qc_report(config)；重要函式：create_overall_qc_report_table, insert_overall_qc_report, export_to_csv, calc_stats)。
  • 輸出檔案：以 {resultDataPath}/overallQcReport.db 與 {resultDataPath}/overallQcReport.csv 為固定命名；CSV 路徑可由 PowerBarcoderResultPathManager.get_overall_qc_report_path() 取得。

2. 核心功能模組

2.1 模組職責總覽

函式 角色 輸入 產出 / 副作用 失敗處理
calc_stats 多層工具聚合 檔案路徑 dict: avg_q/err_q/num_seqs/sum_len/min_len/max_len 多層 fallback 確保回傳
_run_seqtk_fqchk(_avg_err) 取得 seqtk 統計 檔案 指定欄位 raise → 上層切換策略
_run_seqkit_stats(_nums) 取得 seqkit 統計 檔案 指定欄位 raise → 上層切換策略
_python_fastq_stats FASTQ 直接解析 檔案 基本欄位(品質可能 'N/A') 不 raise，回傳零化
collect_overall_qc_stats 產出全部步驟 tuple config List[(None,...8 欄)] 單步驟錯誤不終止其他
create_overall_qc_report_table 建表 db_path 建立表(刪舊檔後) 例外上拋
insert_overall_qc_report 批次寫入 db_path + entries 新增列 例外上拋
export_to_csv 匯出 db & 路徑 生成 CSV 例外上拋
save_overall_qc_report 協調流程 config DB + CSV 任何例外終止

集中 schema 來源：QCSchemaManager.get_overall_table_sql() / get_csv_headers('overall') 確保 DB/CSV 順序一致。

2.1.1 主要功能

  • 直接從指定的檔案路徑(包括 .gz 檔案)收集整體 QC 統計數據(如序列數、長度、品質等)。
  • 將收集到的統計數據儲存到 SQLite 資料庫 (overallQcReport.db)。
  • 將資料庫中的整體 QC 報告匯出到 CSV 檔案 (overallQcReport.csv)。
  • 包含外部工具 (seqtk, seqkit) 或 Python 實現的統計計算邏輯。

2.1.2 統計項目與資料來源

統計項目 資料來源 說明
Raw data r1/r2 {ampliconInfo}/{R1FastqGz}、{ampliconInfo}/{R2FastqGz} 原始測序 FASTQ 檔案統計
Fastp quality trim r1/r2 由 PowerBarcoderResultPathManager.get_trim_r1_fastq_gz_path() / get_trim_r2_fastq_gz_path() 所返回的路徑 fastp 修剪後 FASTQ 檔案統計
Demultiplex amplicon r1/r2 由 PowerBarcoderResultPathManager.get_locus_amplicon_r1_path() / get_locus_amplicon_r2_path() 所返回的路徑(位於 {resultDataPath}/{locus}_result/) 依 locus primer 分群後的 amplicon FASTQ 檔案統計
  • 各步驟皆由 save_overall_qc_report.py 直接統計對應檔案。
  • 支援多 locus，步驟名稱與檔案來源皆可依 locus 動態擴充。

2.1.2 工具優先順序與混合策略

層級 說明 來源欄位 失敗 → 下一層
1 雙工具混合：seqtk(品質) + seqkit(數量/長度) avg_q, err_q / num_seqs, sum_len, min_len, max_len 任一缺失
2 seqtk 單工具全欄 全部可解析欄位 失敗
3 seqkit 單工具全欄 長度/數量 (+ 可能 avg_qual)；err_q='N/A' 失敗
4 Python FASTQ 解析 長度/數量/粗略 avg_q；err_q='N/A' 無下一層

補充：

  • .gz 由副檔名判斷 → gzip.open。
  • FASTA 情境：品質行缺失 → avg_q/err_q 多為 'N/A'(忽略且不錯誤)。
  • parse_int 保護 inf / 非整數字串。

3. 資料庫與 Schema 管理

Schema 來源集中於 QCSchemaManager：

  • get_overall_table_sql() 建表(8 固定欄位)
  • get_csv_headers('overall') 提供 CSV header(與 DB 欄位一致)
  • 欄位擴充作法：修改 OVERALL_QC_FIELDS & OVERALL_QC_FIELD_TYPES → 重建 DB

Legacy overallQcReport.txt 已淘汰；若目錄仍殘留，可刪除。

3.1 overallQcReport.db 結構

3.1.1 overallQcReport 表

欄位名稱 資料型態 說明
id INTEGER PRIMARY KEY AUTOINCREMENT 自動遞增主鍵
step TEXT 處理步驟名稱
avg_q REAL 平均品質分數
err_q REAL 錯誤率
num_seqs INTEGER 序列數量
sum_len INTEGER 總長度
min_len INTEGER 最短長度
max_len INTEGER 最長長度

3.2 資料庫操作範例

3.2.1 統計資料處理

# 執行整體 QC 報告生成
from src.qc.save_overall_qc_report import save_overall_qc_report

config = PowerBarcoderConfig.from_yaml("config.yml")

# 收集統計資料並儲存到資料庫與 CSV(簡化的單一流程)
save_overall_qc_report(config)

3.2.2 資料存取

註：目前資料存取主要透過產生的 CSV 檔案或直接查詢 SQLite 資料庫：

import sqlite3
import pandas as pd

# 直接查詢 SQLite 資料庫
db_path = "data/result/202506121340/overallQcReport.db"
conn = sqlite3.connect(db_path)

# 查詢所有整體統計資料
all_stats = pd.read_sql_query("SELECT * FROM overallQcReport", conn)

# 查詢特定步驟的統計資料
step_stats = pd.read_sql_query(
    "SELECT * FROM overallQcReport WHERE step = ?", 
    conn, params=["Raw data r1"]
)
conn.close()

4. CSV 匯出格式與報告結構

4.1 overallQcReport.csv 結構

4.1.1 overallQcReport.csv 範例 (單 locus：trnLF)

id step avg_q err_q num_seqs sum_len min_len max_len
1 Raw data r1 35.3 22.1 2410690 725617690 301 301
2 Raw data r2 32.6 18.9 2410690 725617690 301 301
3 Fastp quality trim r1 36.4 26.2 2370686 656197338 31 276.8
4 Fastp quality trim r2 33.9 21.2 2370686 656197338 31 276.8
5 trnLF - Demultiplex amplicon r1 34.5 21 539270 160832570 70 298.2
6 trnLF - Demultiplex amplicon r2 34.5 21 539270 160832570 70 298.2

註：

  • 混合策略詳見 2.1.2；若工具層降級 → err_q 或 avg_q 可能為 'N/A'。
  • seqtk ALL 行典型：ALL num_bases avg_len min_len max_len Q1 Q2 Q3 avg_qual err(%) N(%)(僅取第 2,3,4,5,8,9 欄)。
  • seqkit -T 第 2 行：file format type num_seqs sum_len min_len avg_len max_len ...(取 4~7 欄)。
  • avg_len = sum_len / num_seqs 可重建，故不存獨立欄位。
  • 每次重建 DB/CSV → 非累積。

4.2 詳細欄位說明與統計規則

4.2.1 overallQcReport.csv 各欄欄位說明與統計規則

欄位 說明 主要來源(優先順序) 型態
id 每次產生報告時自動從 1 開始遞增，不受多次執行影響 不適用 整數
step 處理步驟名稱，由流程動態產生 不適用 字串
avg_q 平均品質(per-read 平均後再平均) seqtk avg_qual；或 seqkit avg_qual；fallback Python 或 'N/A' 浮點數 / 'N/A'
err_q seqtk 錯誤率百分比(非 1-Phred) seqtk err(%)；缺失設 'N/A' 浮點數 / 'N/A'
num_seqs 序列總數 seqkit stats 第 2 行第 4 欄(values[3]，整數) 整數
sum_len 所有序列長度總和 seqkit stats 第 2 行第 5 欄(values[4]，整數) 整數
min_len 最短序列長度 seqkit stats 第 2 行第 6 欄(values[5]，整數) 整數
max_len 最長序列長度 seqkit stats 第 2 行第 7 欄(values[6]，整數) 整數

4.2.2 overallQcReport.csv 各步驟與檔案來源與命名規則

步驟名稱 來源檔案路徑範例 說明
Raw data r1 / r2 {ampliconInfo}/{R1FastqGz} 和 {ampliconInfo}/{R2FastqGz} 原始測序 FASTQ 檔案
Fastp quality trim r1 / r2 {resultDataPath}/trim_R1FastqGz.gz 和 {resultDataPath}/trim_R2FastqGz.gz fastp 修剪後 FASTQ 檔案
Demultiplex amplicon r1 / r2 {resultDataPath}/{locus}_result/{locus}_amplicon_r1.fq 和 {resultDataPath}/{locus}_result/{locus}_amplicon_r2.fq 依 locus primer 分群後 FASTQ；步驟命名：<locus> - Demultiplex amplicon r1 / r2

4.3 匯出功能設計

4.3.1 匯出策略

  • 標準化格式：採用統一的 CSV 格式，便於 Excel 等工具開啟
  • 編碼處理：確保輸出檔案使用 UTF-8 編碼，支援中文檔案路徑
  • 欄位排序：按照邏輯順序排列欄位，便於資料分析
  • 資料驗證：在匯出前驗證資料完整性與格式正確性

5. 技術參考與外部依賴

5.1 外部工具參考

5.1.1 seqtk 工具

  • 版本要求：seqtk 1.3 或以上
  • 主要功能：基本序列統計與格式轉換
  • 輸出格式：標準化文本格式
  • 參考連結：seqtk GitHub

5.1.2 seqkit 工具

  • 版本要求：seqkit 2.0 或以上
  • 主要功能：進階序列統計與分析
  • 輸出格式：JSON 與表格格式
  • 參考連結：seqkit 官方網站

5.2 檔案格式規範

5.2.1 FASTQ 格式

  • 標準規範：每個 read 佔 4 行：標頭、序列、分隔符、品質
  • 品質編碼：Phred+33 (Sanger)
  • 參考文件：FASTQ Format Specification

5.2.2 FASTA 格式

  • 標準規範：標頭行以 > 開始，序列行可包含大小寫字母
  • 大小寫意義：小寫代表低品質區段
  • 參考規範：FASTA Format Specification

5.3 相關模組文件

  • src/denoise/denoise.md：DADA2 降噪流程說明，了解 denoiseResult 目錄結構
  • src/merge/merger.md：序列合併流程說明，了解 mergeResult 目錄結構
  • src/demultiplex/demultiplex.md：樣本分群流程說明，了解 demultiplexResult 目錄結構

本文件更新：2025-09-30