docs/data_flow.md - PowerBarcoder 資料流向與格式規範

概述

本文件詳細記錄 PowerBarcoder 各步驟的輸入與輸出格式，標準化資料格式，提升系統穩定性與可維護性。

重要路徑說明：

{resultDataPath} 指批次結果根目錄，以 time stamp 命名，如：result/202506271921/
{locus} 指基因座名稱，如 trnLF, rbcLN 等
完整路徑範例：result/202506271921/trnLF_result/demultiplexResult/untrimmed/

整體流程架構

flowchart LR
    %% Denoise 階段
    subgraph "Denoise 階段"
        C1["DADA2 過濾"] --> C2["DADA2 降噪"]
        C2 --> C3["序列品質評估"]
    end

    %% Merge 階段
    subgraph "Merge 階段"
        D1["DADA2 合併"] --> D2["10N 序列串接"]
        D2 --> D3["BLAST 比對"]
        D3 --> D4["最終合併結果"]
    end

    %% QC 階段
    subgraph "QC 階段"
        E1["整體統計報告"] --> E2["樣本級別報告"]
        E2 --> E3["序列萃取整理"]
    end

    %% 子流程間連線
    A["原始測序資料 (FASTQ.gz)"] --> B1
    B4 --> C1
    C3 --> D1
    D4 --> E1

1. Demultiplex 模組

1.1 fastp 品質修剪

輸入格式：

{ampliconInfo}/
├── {R1FastqGz}          # 原始 R1 FASTQ 檔案 (*.fastq.gz)
└── {R2FastqGz}          # 原始 R2 FASTQ 檔案 (*.fastq.gz)

輸出格式：

{resultDataPath}/
├── trim_R1FastqGz.gz    # 修剪後 R1 檔案 (固定命名)
├── trim_R2FastqGz.gz    # 修剪後 R2 檔案 (固定命名)
├── summary.json         # fastp JSON 格式品質統計報告
└── summary.html         # fastp HTML 互動式品質報告

檔案命名規範：

輸出檔案名稱固定，不依賴輸入檔案名稱
統一使用 .gz 壓縮格式
fastp 會自動產生 summary.json(機器可讀)與 summary.html(人工瀏覽用)兩種 QC 報告，內容包含修剪前後的品質統計、長度分布、N base 統計等

1.2 Locus 引子解複用

輸入格式：

{resultDataPath}/
├── trim_R1FastqGz.gz    # fastp 修剪後 R1
└── trim_R2FastqGz.gz    # fastp 修剪後 R2

配置檔案：

config.yml
├── nameOfLoci: [ "trnLF", "ITS", ... ]     # locus 名稱清單
├── F_primer: { locus: "PRIMER_SEQ", ... }  # 正向引子序列
└── R_primer: { locus: "PRIMER_SEQ", ... }  # 反向引子序列

輸出格式：

{resultDataPath}/
└── {locus}_result/
    ├── {locus}_amplicon_r1.fq    # locus 專屬 R1 amplicon (固定命名)
    └── {locus}_amplicon_r2.fq    # locus 專屬 R2 amplicon (固定命名)

檔案命名規範：

檔案名稱格式：{locus}_amplicon_{r1|r2}.fq
不使用壓縮格式，為 plain FASTQ

1.3 樣本條碼解複用

輸入格式：

{resultDataPath}/{locus}_result/
├── {locus}_amplicon_r1.fq    # locus amplicon R1
└── {locus}_amplicon_r2.fq    # locus amplicon R2

配置檔案：

{barcodesFile1}    # R1 條碼檔案 (FASTA 格式)
{barcodesFile2}    # R2 條碼檔案 (FASTA 格式)

條碼檔案格式範例：
>barcode001
ATCGATCG
>barcode002
CGATCGAT

輸出格式：

{resultDataPath}/{locus}_result/demultiplexResult/untrimmed/
├── {locus}_{name1}_{name2}_r1.fq    # 樣本條碼解複用結果 R1
├── {locus}_{name1}_{name2}_r2.fq    # 樣本條碼解複用結果 R2
├── {locus}_{name3}_{name4}_r1.fq    # 其他樣本 R1
├── {locus}_{name3}_{name4}_r2.fq    # 其他樣本 R2
└── ...

檔案命名規範：

檔案名稱格式：{locus}_{name1}_{name2}_{r1|r2}.fq
{name1} 和 {name2} 分別對應 R1 和 R2 條碼檔案中的條碼名稱
cutadapt 會自動使用條碼檔案中的標頭名稱(去除 > 符號)
不使用壓縮格式

1.4 引子修剪

輸入格式：

{resultDataPath}/{locus}_result/demultiplexResult/untrimmed/
├── {locus}_{name1}_{name2}_r1.fq    # 各樣本 untrimmed R1
└── {locus}_{name1}_{name2}_r2.fq    # 各樣本 untrimmed R2

輸出格式：

{resultDataPath}/{locus}_result/demultiplexResult/trimmed/
├── {locus}_{name1}_{name2}_r1.fq    # 修剪後 R1
└── {locus}_{name1}_{name2}_r2.fq    # 修剪後 R2

檔案命名規範：

檔案名稱格式：{locus}_{name1}_{name2}_{r1|r2}.fq
採用「資料夾負責階段，檔名負責唯一識別」原則，保持與 untrimmed 檔案的條碼名稱一致性

2. Denoise 模組

2.1 DADA2 過濾

輸入格式：

{resultDataPath}/{locus}_result/demultiplexResult/trimmed/
├── {locus}_{name1}_{name2}_r1.fq    # 修剪後 R1
└── {locus}_{name1}_{name2}_r2.fq    # 修剪後 R2

輸出格式：

{resultDataPath}/{locus}_result/demultiplexResult/
├── filtered/
│   ├── {locus}_{name1}_{name2}_r1.fq    # 過濾後 R1
│   └── {locus}_{name1}_{name2}_r2.fq    # 過濾後 R2
└── error_learning_2nd/                  # 二階段錯誤學習目錄
    ├── {selected_barcode}_r1.fq         # 選中用於二階段學習的 R1 檔案
    └── {selected_barcode}_r2.fq         # 選中用於二階段學習的 R2 檔案

檔案命名規範：

filtered 檔案格式：{locus}_{name1}_{name2}_{r1|r2}.fq
採用「資料夾負責階段，檔名負責唯一識別」原則
error_learning_2nd 為 mode=2 時使用，由 error_learning_2nd_selector.py 篩選非污染序列產生
維持條碼名稱一致性

2.2 錯誤學習配置 (Error Learning)

Error Learning 資料來源規則：

根據 denoise_mode 參數決定錯誤學習的資料來源：

mode=0 (DEFAULT)：進行錯誤學習
mode=1 (NO_ERROR_LEARNING)：跳過錯誤學習
mode=2 (SECOND_ERROR_LEARNING)：進行二階段錯誤學習

資料來源決定邏輯：

if dada2LearnErrorFile 已指定:
    使用 {dada2LearnErrorFileHelper}/{dada2LearnErrorFile}/ 目錄
else:
    使用 {resultDataPath}/{locus}_result/demultiplexResult/filtered/ 目錄

二階段錯誤學習流程：

第一階段 → error_learning_2nd_selector.py → 
selection_results/ → error_learning_2nd/ → 第二階段錯誤學習

檔案過濾規則：

R1 檔案：檔名包含 _r1 或 .r1 (不區分大小寫)
R2 檔案：檔名包含 _r2 或 .r2 (不區分大小寫)
支援 .fq, .fastq, .fq.gz, .fastq.gz 格式

2.3 DADA2 降噪

輸入格式：

{resultDataPath}/{locus}_result/demultiplexResult/filtered/
├── {locus}_{name1}_{name2}_r1.fq    # 過濾後 R1
└── {locus}_{name1}_{name2}_r2.fq    # 過濾後 R2

配置檔案：

{resultDataPath}/{locus}_result/denoiseResult/denoise_pairs.txt

格式 (支援 tab 或逗號分隔)：
{locus}_{name1}_{name2}    sample001
{locus}_{name3}_{name4}    sample002
或
{locus}_{name1}_{name2},sample001
{locus}_{name3}_{name4},sample002

輸出格式：

{resultDataPath}/{locus}_result/denoiseResult/
├── denoise_pairs.txt           # 條碼與樣本對應檔案 (固定命名)
├── r1/
│   ├── sample001.fas          # 樣本 R1 降噪結果 (FASTA)
│   ├── sample002.fas          # 樣本 R1 降噪結果
│   └── ...
├── r2/
│   ├── sample001.fas          # 樣本 R2 降噪結果 (FASTA)
│   ├── sample002.fas          # 樣本 R2 降噪結果
│   └── ...
└── selection_results/          # 二階段錯誤學習選擇結果目錄
    ├── diverse_asv_samples.txt   # 多樣性 ASV 樣本清單
    ├── dominant_asv_samples.txt # 主導性 ASV 樣本清單
    ├── single_r1_denoised_samples.txt          # R1 單獨降噪樣本清單
    └── single_r2_denoised_samples.txt          # R2 單獨降噪樣本清單

檔案命名規範：

降噪結果檔案格式：{sample_name}.fas
使用 sample_name 而非 barcode 作為檔案名稱
檔案格式為 FASTA (.fas)
R1 和 R2 分別存放在不同目錄
selection_results 目錄由 error_learning_2nd_selector.py 產生，用於 mode=2 二階段錯誤學習

3. Merge 模組

3.1 Merge 整合處理

輸入格式：

{resultDataPath}/{locus}_result/denoiseResult/
├── r1/{sample_name}.fas    # R1 降噪結果
└── r2/{sample_name}.fas    # R2 降噪結果

輸出格式：

{resultDataPath}/{locus}_result/mergeResult/
├── dada2/
│   └── merged/
│       ├── {sample_name}.fas   # DADA2 合併結果 (固定格式)
│       └── ...
└── merger/
    ├── merged/
    │   ├── {sample_name}.fas   # 最終合併結果
    │   └── ...
    ├── nCatR1R2/
    │   ├── {sample_name}.fas   # 10N 串接結果
    │   └── forSplit/           # 分割用中間檔案
    ├── aligned/
    │   └── mafft/              # MAFFT 比對結果目錄
    ├── r1/                     # R1 序列目錄
    ├── r2/                     # R2 序列目錄
    ├── r1Ref/                  # R1 參考序列目錄
    ├── r2Ref/                  # R2 參考序列目錄
    └── rawMerged/              # 原始合併結果目錄

檔案命名規範：

所有檔案名稱格式：{sample_name}.fas
維持與 denoise 階段的 sample_name 一致性
FASTA 格式 (.fas)
nCatR1R2 目錄存放 10個 'N' 字元串接的 R1 和 R2 序列
aligned/mafft 目錄存放序列比對結果
forSplit 目錄存放分割處理的中間檔案

3.2 BLAST 比對與最終輸出

輸入與中介檔：

{resultDataPath}/{locus}_result/mergeResult/merger/nCatR1R2/      # blastReadChoosingMode=0 時 cat 為查詢
{resultDataPath}/{locus}_result/mergeResult/merger/r1/            # blastReadChoosingMode=1 時 r1 ASV 來源
{resultDataPath}/{locus}_result/mergeResult/merger/r2/            # blastReadChoosingMode=1 時 r2 ASV 來源
{resultDataPath}/{locus}_result/blastResult/{locus}_catQuery.fas  # 程式生成查詢集合
{resultDataPath}/{locus}_result/blastResult/{locus}_refDB.*       # makeblastdb 建立的資料庫前綴
{resultDataPath}/{locus}_result/blastResult/{locus}_refResult.txt # 原始 blastn outfmt6 結果

過濾與最終輸出：

{resultDataPath}/{locus}_result/blastResult/
└── {locus}_blastResult.txt    # 5+1 過濾後結果 (最終匯出)

過濾流程 (5+1)： (可選)ASV豐度前K → r1/r2 交集參考 → 計算 coverage_length/identity → 依 coverage_length 最大 → 依 identity 最大 → combined_score 決勝。

匯出格式要點：

預設 tab：每配對兩行(r1/r2)，15欄：1–12 標準 BLAST 欄位( qseqid 自動補 .fas，bitscore 去小數 )，13:qstart-qend，14:sstart-send，15:rwho
可選 csv/json：額外輸出 Coverage_Length / Identity_Score / Combined_Score
coverage_length 為程式計算(含 gap 與效率懲罰)，非單純 alignment_length

檔名區分：{locus}_refResult.txt = 原始 blastn；{locus}_blastResult.txt = 過濾後使用於後續 alignment/merger。

4. QC 模組

4.1 整體統計報告

輸入格式：

{resultDataPath}/
├── {R1FastqGz}                          # 原始 R1
├── {R2FastqGz}                          # 原始 R2
├── trim_R1FastqGz.gz                    # fastp 修剪後 R1
├── trim_R2FastqGz.gz                    # fastp 修剪後 R2
└── {locus}_result/
    ├── {locus}_amplicon_r1.fq           # locus amplicon R1
    └── {locus}_amplicon_r2.fq           # locus amplicon R2

輸出格式：

{resultDataPath}/
├── overallQcReport.db      # 整體統計 SQLite 資料庫 (固定命名)
└── overallQcReport.csv     # 整體統計 CSV 報告 (固定命名)

Implementation anchor: 以上整體報告的產生與輸出由 src/qc/save_overall_qc_report.py 負責(輸出檔名固定為 overallQcReport.db / overallQcReport.csv，位於 resultDataPath 根目錄)。

overallQcReport.csv 格式：

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

4.2 樣本級別報告

輸入格式：

{resultDataPath}/{locus}_result/
├── denoiseResult/
│   ├── denoise_pairs.txt               # 條碼樣本對應
│   ├── r1/{sample_name}.fas           # DADA2 R1 結果
│   └── r2/{sample_name}.fas           # DADA2 R2 結果
├── mergeResult/
│   ├── dada2/merged/{sample_name}.fas  # DADA2 合併結果
│   ├── merger/nCatR1R2/{sample_name}.fas # 10N 串接結果
│   └── merger/merged/{sample_name}.fas # 最終合併結果
├── blastResult/
│   └── {locus}_blastResult.txt         # BLAST 結果
└── demultiplexResult/
    ├── untrimmed/{locus}_{name1}_{name2}_{r1|r2}.fq
    ├── trimmed/{locus}_{name1}_{name2}_{r1|r2}.fq
    └── filtered/{locus}_{name1}_{name2}_{r1|r2}.fq

輸出格式：

{resultDataPath}/{locus}_result/qcResult/
├── {locus}_qcReport.db                  # 核心欄位 schema 由 qc/constants.py 管理
├── {locus}_qcReport.csv                 # CSV (hash/created_at 等內部欄位略過)
├── {locus}_recommended_sequences.fas    # 推薦序列彙總 (若存在)
└── extracted_sequences/
    ├── {sample_name}.fas               # 單檔多序列；標頭步驟前綴 (denoise_r1 / merger_merged ...)
    └── ...

5. 檔案命名標準化規範與實施

5.1 標準化規範

5.1.1 統一檔案副檔名

FASTQ: 統一使用 .fq
FASTA: 統一使用 .fas
壓縮檔: 僅在必要時使用 .gz

5.1.2 統一命名規則

階段前綴明確: {identifier}_{direction}.{ext}
範例: {locus}_{name1}_{name2}_r1.fq

5.1.3 統一識別符使用

demultiplex 階段: 使用條碼組合 ({locus}_{name1}_{name2})
denoise 之後: 使用 sample_name

5.3 標準化實施報告

5.3.1 建立標準化常數模組

檔案: src/utils/file_naming_standards.py

功能:

定義標準化檔案副檔名常數(FASTQ_EXTENSION, FASTA_EXTENSION)
提供標準化檔案命名函數(get_demultiplex_filename, get_sample_filename)
提供檔案名稱驗證與解析函數
支援 demultiplex 階段的複雜命名格式解析

5.3.2 路徑管理模組標準化更新

檔案: src/path/path_manager.py

功能:

使用 FASTQ_EXTENSION 常數
FASTQ 檔案路徑產生方法以使用標準化副檔名
get_raw_r1_fastq_path() 和 get_raw_r2_fastq_path() 使用 FASTQ_EXTENSION
get_locus_amplicon_r1_path() 和 get_locus_amplicon_r2_path() 使用 FASTQ_EXTENSION

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs/data_flow.md - PowerBarcoder 資料流向與格式規範

概述

整體流程架構

1. Demultiplex 模組

1.1 fastp 品質修剪

1.2 Locus 引子解複用

1.3 樣本條碼解複用

1.4 引子修剪

2. Denoise 模組

2.1 DADA2 過濾

2.2 錯誤學習配置 (Error Learning)

2.3 DADA2 降噪

3. Merge 模組

3.1 Merge 整合處理

3.2 BLAST 比對與最終輸出

4. QC 模組

4.1 整體統計報告

4.2 樣本級別報告

5. 檔案命名標準化規範與實施

5.1 標準化規範

5.1.1 統一檔案副檔名

5.1.2 統一命名規則

5.1.3 統一識別符使用

5.3 標準化實施報告

5.3.1 建立標準化常數模組

5.3.2 路徑管理模組標準化更新

FilesExpand file tree

data_flow.md

Latest commit

History

data_flow.md

File metadata and controls

docs/data_flow.md - PowerBarcoder 資料流向與格式規範

概述

整體流程架構

1. Demultiplex 模組

1.1 fastp 品質修剪

1.2 Locus 引子解複用

1.3 樣本條碼解複用

1.4 引子修剪

2. Denoise 模組

2.1 DADA2 過濾

2.2 錯誤學習配置 (Error Learning)

2.3 DADA2 降噪

3. Merge 模組

3.1 Merge 整合處理

3.2 BLAST 比對與最終輸出

4. QC 模組

4.1 整體統計報告

4.2 樣本級別報告

5. 檔案命名標準化規範與實施

5.1 標準化規範

5.1.1 統一檔案副檔名

5.1.2 統一命名規則

5.1.3 統一識別符使用

5.3 標準化實施報告

5.3.1 建立標準化常數模組

5.3.2 路徑管理模組標準化更新