QC 總覽 (Overview)

圖 1: 品質控制概念圖。層次化品管架構圖，展示分類 (Classification)、決策 (Decision)、持久化 (Persistence) 三層資料流向。

概述

PowerBarcoder QC 模組提供「中心化資料庫 + 規則分類 + rule as judge 品質裁決 + LLM 仲裁 + 統一序列輸出」的品質控制框架。整體佈局採「分類 → 決策 → 持久化」三層，確保單一樣本失敗不阻斷其餘樣本。

模組架構

graph TD
    A[QC Pipeline] --> B[整體品質控制]
    A --> C[Locus 品質控制與推薦]
    A --> D[統一序列萃取]
    
    B --> B1[overallQcReport.db]
    B --> B2[overallQcReport.csv]
    
    C --> C1["{locus}_qcReport.db"]
    C --> C2["{locus}_qcReport.csv"]
    C --> C3[序列推薦引擎]

    %% 新增索引層級
    C1 --> IDX[SequenceIndexer]
    IDX --> ASV["asv_sequences (metadata index)"]
    ASV -->|lazy-load| D1[extracted_sequences/]

    C3 --> C4[Rule 1-6: 規則分類]
    C4 --> C5[統一仲裁流程:<br/>所有樣本進入 Rule-based Judge]
    C5 --> C6[品質過濾結果]
    C6 -->|品質過濾失敗| C6A[Quality Filter Rejected<br/>confidence=0.1]
    C6 -->|單一合格序列| C6B[Rule-based Judge Success<br/>Merger/DADA2 Preferred]
    C6 -->|兩個序列且完全相同| C6C[Identical Sequences<br/>依豐度選擇]
    C6 -->|多個序列| C6D[Multiple Sequences<br/>LLM Arbitration]
    C6D --> C6E[Fallback 最高豐度<br/>若 LLM 停用或失敗]
    C6A --> D2[推薦序列 FASTA]
    C6B --> D2
    C6C --> D2
    C6D --> D2
    C6E --> D2

    style A fill:#e1f5fe
    style C fill:#fff3e0
    style C1 fill:#fff3e0
    style C2 fill:#fff3e0
    style C5 fill:#fff9c4
    style D2 fill:#fce4ec
    style IDX fill:#fff8e1
    style ASV fill:#e8f5e8

核心模組與分層

層級	模組	職責摘要	是否必須	失敗影響
Overall 基線	`save_overall_qc_report`	產出全局 reads / 長度基線	是	無(僅缺少基線)
Locus 資料收集	`QCDataManager.collect_all_qc_data`	解析 denoise_pairs, 索引 ASV metadata, 彙整統計, 生成 validation_code	是	該 locus 無法進入推薦
規則分類	`_classify_sample_by_rules`	以 identical 與序列存在性分派 Rule 1–6	是	單樣本分類錯誤 → 後續路徑偏差
品質裁決	`rule_judge.evaluate_sample`	所有樣本(當前端啟用規則時)初步決策 / 過濾 / INCONCLUSIVE	是(統一流程)	INCONCLUSIVE 或錯誤 → 直接 LLM/ fallback
LLM 仲裁	`LLMAnalysisPipeline.run_single_locus_analysis`	對 INCONCLUSIVE 样本給最終偏好	可關閉	關閉或失敗 → Fallback(比較最高絕對豐度，conf=0.30)
推薦寫回	`_save_recommendation_to_db`	每樣本即時 UPDATE 推薦欄位	是	單樣本失敗不影響其他
序列萃取	`_extract_recommended_sequences`	彙整推薦結果 FASTA	是	FASTA 缺失；不影響 DB
Debug 序列合併	`QCSequenceExtractor`	可選，輸出多來源整合序列	否	只影響 debug 資料

📊 整體品質控制 (Overall QC)

收集整個 PowerBarcoder 流程的整體統計資料，產生 overallQcReport.db 和 overallQcReport.csv。

🧬 Locus 品質控制與序列推薦 (Locus QC)

針對每個基因座建立 {locus}_qcReport.db 與 {locus}_qcReport.csv。推薦決策流程分兩階段：

規則分類(Classification)— 不讀取完整序列，只依 metadata/hash 存在性與 identical_to_topK_dada2_merge 值判斷 Rule 1–6。
決策(Decision)— 所有樣本統一進入 RuleAsJudge 品質預篩選；若判為 INCONCLUSIVE，僅在前端啟用規則時才啟用 LLM 仲裁，否則直接走最高豐度 Fallback。

🤖 LLM 模組整合 (LLM Integration)

當前端啟用規則時，所有樣本統一進入 RuleAsJudge 品質預篩選。若 rule as judge 無法得出具體偏好(INCONCLUSIVE)且 llm_analysis_enabled=True 時進行 LLM 仲裁；否則使用 Fallback(比較最高絕對豐度，confidence=0.30)。

執行流程

QC 模組採用統一架構，將品質控制與序列推薦原生整合。以下為完整的執行流程圖：

graph TD
    A[run_qc_pipeline 啟動] --> B[save_overall_qc_report]
    B --> C[整體統計資料收集]
    C --> D[overallQcReport.db/.csv 生成]
    
    D --> E[開始 Locus QC 迴圈]
    E --> F[QCDataManager 初始化]
    F --> G[collect_all_qc_data 資料收集]
    
    G --> G0["步驟 0: index_denoise_sequences_to_database<br/>ASV 元資料索引建立 (清除舊 locus 索引後重建)"]
    G0 --> G1[步驟 1: denoise_pairs.txt 解析]
    G0 --> G2[步驟 2: FASTQ/FASTA 檔案統計]
    G0 --> G3[步驟 3: BLAST 結果分析]
    G0 --> G4[步驟 4: ASV 豐度解析]
    G0 --> G5[步驟 5: validation code 生成]
    
    G1 --> H["資料儲存至 {locus}_qcReport.db"]
    G2 --> H
    G3 --> H
    G4 --> H
    G5 --> H
    
    %% 索引結果已在步驟 0 建立
    G0 --> ASV["asv_sequences 表已建立<br/>(metadata + file offset)"]
    ASV -->|on-demand| LOAD[Lazy-Load sequence from file]
    LOAD --> P[QCSequenceExtractor 序列萃取]

    H --> I[SequenceRecommendationEngine 啟動]
    I --> J["Step 1: 樣本規則 (Rule1–6) 分類"]
    J --> K["Step 2: 統一仲裁流程(所有樣本進入 Rule-based Judge)"]
    K --> L["Rule-based Judge 品質過濾"]
    L --> L0["品質過濾失敗 → Quality Filter Rejected (conf=0.1)"]
    L --> L1["單一合格序列 → Rule-based Judge Success (Merger/DADA2)"]
    L --> L2["兩個序列且完全相同 → Identical Sequences (依豐度選擇)"]
    L --> L3["多個序列 → Multiple Sequences, LLM Arbitration"]
    L3 --> L4["Fallback (最高豐度比較；conf=0.30) 若 LLM 停用或失敗"]
    L0 --> M
    L1 --> M
    L2 --> M
    L3 --> M
    L4 --> M
    M --> N[export_csv 生成報告]
    N --> O["{locus}_qcReport.csv 生成"]
    O --> P
    P --> S{還有其他 locus?}
    S -->|是| E
    S -->|否| T[QC 流程完成]
    
    style A fill:#e3f2fd
    style B fill:#e8f5e8
    style I fill:#fff3e0
    style K fill:#fff9c4
    style M fill:#f3e5f5
    style T fill:#c8e6c9
    style ASV fill:#e8f5e8
    style LOAD fill:#fff3e0

執行順序：

序	理想	現況	備註
1	Overall QC	✓	啟用需解除註解
2	Locus 資料收集	✓	必須成功
3	規則分類 (Rule 1–6)	✓	提前建立分類統計
4	統一仲裁流程(所有樣本)	✓	所有樣本進入 rule as judge → 品質過濾 + 決策或 INCONCLUSIVE
5	LLM 仲裁(INCONCLUSIVE 時)	視旗標	llm_analysis_enabled=False → 跳過
6	推薦寫回 DB	✓	每樣本即時 UPDATE
7	匯出 locus CSV	✓	包含推薦欄位
8	推薦 FASTA / Debug extraction	✓	Debug 視旗標

規則分類與判斷邏輯

規則優先級與條件

分類優先順序(出現即返回，不再繼續)：

失敗類：缺 Merger / 缺 DADA2 → Rule 4 / 5；雙缺 → Rule 6
成功類：若 identical_to_topK_dada2_merge 含 1 → Rule 1
若含 2..K 並且不含 1 → Rule 2
其餘(含 N/A / Error / 空值 / 大於 K 的值)→ Rule 3

identical_to_topK_dada2_merge 解析：允許逗號清單；非數字與空白過濾。錯誤/空值視為無交集(Rule 3)。

Rule 路徑矩陣

Rule	描述	初始來源條件	決策函式	是否進 rule as judge	是否進 LLM	fallback 來源	基礎 confidence 範圍
1	merger top1 與 DADA2 top1 hash 一致	identical 包含 1	`_process_sample`	是	可能(若 INCONCLUSIVE)	DADA2 或 Merger	0.9 / 0.6 (Warning 6-1)
2	有交集但不含 top1	identical 含 2..K	`_process_sample`	是	可能(若 INCONCLUSIVE)	DADA2 或 Merger	0.8 / 0.6 / 0.5 / 0.3
3	無交集	identical = N/A / 無數值 / >K	`_process_sample`	是	可能(若 INCONCLUSIVE)	DADA2 或 Merger	0.6 / 0.5 / 0.3
4	DADA2 失敗 Merger 有	缺 DADA2	`_process_sample`	是	可能(若 INCONCLUSIVE)	Merger	0.5
5	Merger 失敗 DADA2 有	缺 Merger	`_process_sample`	是	可能(若 INCONCLUSIVE)	DADA2	0.4
6	雙重失敗	缺雙方	`_process_sample`	是	否	manual_review	0.1

rule as judge 決策輸出

Decision	說明	後續	Confidence 典型值
MERGER_PREFERRED	Merger 品質較佳	直接推薦 Merger	0.8 或 0.6(低豐度/差異)
DADA2_PREFERRED	DADA2 品質較佳	直接推薦 DADA2	0.8 或 0.6
INCONCLUSIVE	品質差異不顯著	進 LLM(若啟用)或 fallback	0.5 / 0.3 (判為不確定)
REJECT_ALL (via confidence=0.0)	所有來源被過濾	manual_review	0.1

Confidence 匯總表

場景	Confidence
Rule 1 正常	0.9
Rule 1 + Warning 6-1	0.6
rule as judge 單一來源合格	0.8 / 0.6
INCONCLUSIVE → LLM 成功	來源自 LLM (confidence 由 LLM JSON) 預設 0.7 fallback
INCONCLUSIVE → LLM disabled	0.30(Fallback：比較 DADA2 與 Merger 最高豐度 ASV，選擇絕對豐度較高者)
INCONCLUSIVE → LLM 失敗	0.30(同上 Fallback)
INCONCLUSIVE 低品質不確定	0.5 / 0.3
Rule 4	0.5
Rule 5	0.4
Rule 6	0.1
品質過濾全拒 (manual_review)	0.1

LLM 分析狀態

status	行為	後續
completed	使用結果	生成 markdown 報告
completed_with_parsing_error	仍嘗試提取 recommendation	報告生成 + 警示
其他 / error	fallback	比較 DADA2 與 Merger 各自最高豐度，取絕對較高者(0.30)

Quick Start

執行完整 QC 與推薦流程

from src.qc.qc_pipeline import run_qc_pipeline
from src.config.config_manager import load_config

# 載入設定
config = load_config("your_batch_name")

# 執行統一 QC 與推薦流程
success = run_qc_pipeline(config)

輸出檔案與目錄結構

{resultDataPath}/
├── overallQcReport.db                # 整體統計資料庫
├── overallQcReport.csv               # 整體統計報告
└── {locus}_result/
    └── qcResult/
        ├── {locus}_qcReport.db       # 樣本級統計資料庫(含推薦結果)
        ├── {locus}_qcReport.csv      # 樣本級統計報告(含推薦結果)
        ├── {locus}_recommended_sequences.fas  # 推薦序列 FASTA
        ├── llm_analysis/             # 單樣本 LLM Markdown 報告
        └── extracted_sequences/      # Debug 模式(enable_debug_sequence_extraction=True)才生成多步驟合併序列檔

注意：推薦序列 FASTA 由 SequenceRecommendationEngine 主動生成；QCSequenceExtractor 僅在 debug 模式產出額外聚合序列，尚未實作去重與來源標記統一。

序列索引 / Lazy-Load 設計

SequenceIndexer 於 資料收集步驟 0 建立 asv_sequences 資料表：僅儲存 metadata(hash、長度、豐度、來源、檔案 offset)，真正序列內容在需要(推薦輸出或 DADA2 擷取)時以 offset 從原 FASTA/FASTA+ref 檔按需載入，避免將所有 ASV 一次載入記憶體。

優點：

大量樣本 / 多 locus 下記憶體穩定。
規則分類階段不讀取序列正文，降低 IO。
不同來源(dada2_merge / merger_final / 10n_concat)統一抽象。

資料庫 vs CSV 欄位差異

類別	資料庫 (DB)	CSV 匯出	備註
Hash 欄位 (`*_hash_value`)	保存	移除	內部使用，不列入報表
`created_at`	保存	移除	寫入時間戳
Recommendation 欄位	全部	全部	source/header/sequence/confidence/reasoning/timestamp/llm_model
Validation code	保存	保存	與 rule as judge 判斷互動

identical_to_topK_dada2_merge 欄位語義

以逗號分隔的 merger_final ASV index(按豐度排序)清單，表示 merger 中哪些 ASV 的 hash 出現在 DADA2 merge 前 K(K=top_k_identical)個 ASV 的 hash 集合中：

值範例	語義
`1`	merger 豐度第1名 ASV 出現在 DADA2 top K 集合中(Rule 1 條件)
`2`	merger 豐度第2名 ASV 出現在 DADA2 top K 集合中，但第1名未出現(Rule 2 條件)
`2,3`	merger 豐度第2和第3名 ASV 都出現在 DADA2 top K 集合中，但第1名未出現(仍屬 Rule 2)
`N/A`	merger 所有 ASV 的 hash 都未出現在 DADA2 top K 集合中(可能進 Rule 3)

配置與旗標

參數	預設值	說明
`llm_analysis_enabled`	`False`	關閉時統一仲裁流程中的 INCONCLUSIVE 樣本直接 Fallback(比較最高絕對豐度；confidence=0.30)
`enable_debug_sequence_extraction`	`False`	True 時輸出 extracted_sequences/ 合併檔(多步驟匯總)
`top_k_sequences`	`1`	Debug 合併萃取各步驟檔案保留序列級 TOP K(與推薦流程無關)
`topKIdenticalDada2Merge`	`2`	(list per locus) identical_to_topK_dada2_merge 計算 K；影響 Rule 1/2/3 分類與 Rule 2 交集範圍
`qc_rules` (dict)	預設僅 rule3 True	過濾啟用規則；程式強制保持 rule3=True；當啟用除 rule3 外的任何規則時觸發統一仲裁流程

Fallback 策略與錯誤控制(PRD 對齊)

情境	處理	Confidence	記錄統計欄位
LLM disabled	比較 DADA2 與 Merger 各自最高豐度，取絕對較高者	0.30	llm_fallback_count++
LLM pipeline 例外	同上 Fallback	0.30	llm_fallback_count++
LLM 無結果 / best_result 無法解析	同上 Fallback	0.30	llm_fallback_count++
品質過濾全部拒絕	manual_review	0.1	rule_X_quality_filter_rejected_count++
rule as judge INCONCLUSIVE	進 LLM 或 fallback	見上表	rule_X_judgment_inconclusive_count++

例外不 raise 原則：大部分錯誤以 [WARN] / [ERROR] 印出，保證單樣本不影響其餘樣本流程；DB 寫入逐樣本進行，可能導致「部分完成」。

統計欄位總表

classification_stats

Key	說明
rule_1_classified ... rule_6_classified	規則分類階段樣本計數

recommendation_stats(節選 + 重要)

Key	說明
total_samples	樣本總數
rule_X_count	各規則實際進入決策樣本數(與 classified 可不同：某些規則可能被過濾)
rule_X_direct_merger_count / _direct_dada2_count	rule as judge 直接推薦來源
rule_X_quality_filter_rejected_count	品質過濾全部拒絕
rule_X_judgment_inconclusive_count	需 LLM 仲裁或 fallback
rule_as_judge_count	成功由 rule as judge 完成決策之樣本數
llm_available_count	LLM 成功產生解析結果
llm_fallback_count	LLM 失敗/停用 fallback 次數
sequences_extracted	成功將推薦序列寫入聚合 FASTA 的樣本數

其餘數值(如 direct_* 對 Rule 2/3)視規則類別存在。

規則	條件(摘要)	決策來源	預設 confidence (基礎)	備註
1	merger[0] 與 DADA2 top1 hash 一致	merger	0.9(若含 Warning 6-1 降 0.6)	雙重驗證
2	與 DADA2 topK (2..K) 有交集但不含 1	rule as judge → 可直接 Merger/DADA2 或進 LLM	0.8/0.6/0.5/0.3 變動	品質過濾後可能直接決策
3	無交集 (N/A)	rule as judge → LLM 或 fallback	0.6/0.5/0.3	主仲裁路徑
4	DADA2 無序列，Merger 有	merger	0.5	單來源
5	DADA2 有序列，Merger 無	dada2	0.4	單來源
6	雙重失敗	manual_review	0.1	無有效序列

rule as judge 品質過濾邏輯

Model A(寬鬆過濾)：以 min_relative_proportion(預設 0.10)過濾 DADA2 與 Merger 候選
Model B(高豐度採納)：當序列比例 >= 0.85 可直接推薦(confidence=0.95)
Rule-as-Judge 不再使用固定的 abundance/ambiguous/lowercase 門檻作為主要決策依據
Warning 6-1(validation code 中)→ 標記 abundance disparity，降低 confidence
若僅 1 個來源通過 → 直接推薦(Merger 或 DADA2)，confidence 0.8(正常)/0.6(低豐度或 disparity)
多個通過但無明顯偏好 → INCONCLUSIVE(信心 0.5 或 0.3) → 進 LLM
全部被過濾 → manual_review(confidence=0.1 或 0.0 → 以 0.1 對齊表格)

LLM 與 Fallback 補充

llm_analysis_enabled=False → 對 INCONCLUSIVE 樣本使用 Fallback(比較最高絕對豐度；confidence=0.30)
LLM 執行失敗或結果無法解析 → Fallback(比較最高絕對豐度；confidence=0.30)

Validation code 影響

validation_code 中若含 Warning 6-1(豐度懸殊)→ Rule 1 降級 confidence 0.9 → 0.6。

場景	Confidence
Rule 1 正常	0.9
Rule 1 含 Warning 6-1	0.6
Rule 2/3 rule as judge 單一來源合格正常	0.8
Rule 2/3 單一來源合格且低絕對豐度或 disparity	0.6
Rule 2/3 多來源合格(正常)需 LLM	0.5
Rule 2/3 多來源合格但低豐度/比例懸殊	0.3
Rule 2/3 Fallback (LLM disabled / failure)	0.30
Rule 4	0.5
Rule 5	0.4
Rule 6	0.1
全部過濾失敗(manual_review)	0.1 (若無序列)

LLM Markdown 報告

當 LLM status ∈ {completed, completed_with_parsing_error} 時生成單樣本報告於：qcResult/llm_analysis/{sample_id}.md。Parsing error 仍嘗試抽取 final_recommendation；若失敗則 fallback。

Recommendation 統計輸出

SequenceRecommendationEngine 最後列印統計(部分)：

規則分類數量(rule_X_classified)
已處理數量(rule_X_count)
rule as judge 成功直接決策(direct_merger_count / direct_dada2_count)
品質全拒(quality_filter_rejected_count)
判斷不確定(judgment_inconclusive_count)
LLM 取得有效結果(llm_available_count)
LLM 失敗 fallback 次數(llm_fallback_count)
總推薦序列成功寫入數(sequences_extracted)

資料流摘要

解析 denoise_pairs.txt → 取得 barcode → sample 對映
重建(清除後再索引)denoise / merger / dada2_merge / 10N / merger_r1_ref / merger_r2_ref / merger_final 序列元資料到 asv_sequences(僅 metadata + file offsets)
逐樣本平行收集讀數統計、序列計數、BLAST 資料、hash 比對、最高豐度 Merger ASV 特徵
寫入 {locus}_qcReport.db 主表；計算 identical_to_topK_dada2_merge
規則分類 + rule as judge +(需要時)LLM 即時仲裁 → 更新推薦欄位
匯出雙層表頭 CSV + summary row
生成推薦序列 FASTA(always)與(可選)debug 合併序列
LLM Markdown 報告輸出至 qcResult/llm_analysis/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

QC 總覽 (Overview)

概述

模組架構

核心模組與分層

📊 整體品質控制 (Overall QC)

🧬 Locus 品質控制與序列推薦 (Locus QC)

🤖 LLM 模組整合 (LLM Integration)

執行流程

規則分類與判斷邏輯

規則優先級與條件

Rule 路徑矩陣

rule as judge 決策輸出

Confidence 匯總表

LLM 分析狀態

Quick Start

執行完整 QC 與推薦流程

輸出檔案與目錄結構

序列索引 / Lazy-Load 設計

資料庫 vs CSV 欄位差異

identical_to_topK_dada2_merge 欄位語義

配置與旗標

Fallback 策略與錯誤控制(PRD 對齊)

統計欄位總表

classification_stats

recommendation_stats(節選 + 重要)

rule as judge 品質過濾邏輯

LLM 與 Fallback 補充

Validation code 影響

LLM Markdown 報告

Recommendation 統計輸出

資料流摘要

相關文件

FilesExpand file tree

qc.md

Latest commit

History

qc.md

File metadata and controls

QC 總覽 (Overview)

概述

模組架構

核心模組與分層

📊 整體品質控制 (Overall QC)

🧬 Locus 品質控制與序列推薦 (Locus QC)

🤖 LLM 模組整合 (LLM Integration)

執行流程

規則分類與判斷邏輯

規則優先級與條件

Rule 路徑矩陣

rule as judge 決策輸出

Confidence 匯總表

LLM 分析狀態

Quick Start

執行完整 QC 與推薦流程

輸出檔案與目錄結構

序列索引 / Lazy-Load 設計

資料庫 vs CSV 欄位差異

identical_to_topK_dada2_merge 欄位語義

配置與旗標

Fallback 策略與錯誤控制(PRD 對齊)

統計欄位總表

classification_stats

recommendation_stats(節選 + 重要)

rule as judge 品質過濾邏輯

LLM 與 Fallback 補充

Validation code 影響

LLM Markdown 報告

Recommendation 統計輸出

資料流摘要

相關文件