降噪 (Denoising)

圖 1: 降噪流程概念圖。示意訊號處理過濾器，並透過錯誤學習迴圈 (Error Learning) 回饋優化，將真實 ASV 從背景雜訊中分離。

1. 模組概述

1.1 模組功能

PowerBarcoder Denoise 模組負責將 demultiplex 後的樣本序列進行品質過濾、錯誤率學習、ASV 降噪與配對合併，最終產生高品質的無冗餘序列資料。主流程以 Python 控制(src/denoise/dada2_denoise.py)，支援三種錯誤學習(Error Learning)的降噪(Denoise)模式，各步驟模組化設計提升維護性與擴展性。

1.2 術語說明

ASV (Amplicon Sequence Variant)：擴增子序列變體，代表真實的生物序列
Error Learning：錯誤率學習，分析定序錯誤模式用於降噪
Denoise：降噪處理，區分真實變異與技術錯誤

1.3 技術特色簡述

三種降噪模式：彈性高，適用多種資料特性
二階段錯誤學習：提升高雜訊資料的降噪準確度
Rscript 內部支援多核心平行運算：加速處理
詳細的進度與錯誤回報：利於自動化與前端監控

1.4 輸入資料

主要輸入：demultiplex 階段產生的 trimmed → filtered FASTQ 檔案(demultiplexResult/filtered/)
配置檔案：barcode mapping file、引子資訊、品質參數設定
可選輸入：自訂錯誤學習資料目錄(覆蓋預設 filtered)

1.5 預期輸出

降噪序列：去除技術雜訊後的 ASV 序列 (FASTA 格式)
合併序列：R1/R2 配對合併的完整序列
品質報告：錯誤率學習圖表、處理統計資訊
配對資訊：denoise_pairs.txt 檔案，記錄樣本與序列對應關係

1.6 處理流程

flowchart TD
    A["src/powerBarcode.py 主流程啟動"] --> B["讀取 config.denoise_mode"]
    B --> C{"denoise_mode 判斷"}
    
    %% Mode 0: Default
    C -- "mode=0 (DEFAULT)" --> D0["檢查 config.dada2LearnErrorFile"]
    D0 --> E0{"是否有自定錯誤學習路徑?"}
    E0 -- "有" --> F0["error_dir = config.dada2LearnErrorFileHelper + dada2LearnErrorFile"]
    E0 -- "無或空" --> G0["error_dir = filtered/ (預設路徑)"]
    F0 --> H0["run_filter_and_trim(locus)"]
    G0 --> H0
    H0 --> I0["run_denoise_pipeline(do_error_learning=True, error_dir)"]
    I0 --> J0["pipeline.run_learn_error_rates(locus, error_dir)"]
    J0 --> K0["pipeline.run_denoise_and_merge(locus, error_dir, do_error_learning=True)"]
    K0 --> L0["Mode 0 完成"]
    
    %% Mode 1: No Error Learning  
    C -- "mode=1 (NO_ERROR_LEARNING)" --> D1["忽略 config.dada2LearnErrorFile"]
    D1 --> H1["run_filter_and_trim(locus)"]
    H1 --> I1["run_denoise_pipeline(do_error_learning=False, error_dir=None)"]
    I1 --> K1["pipeline.run_denoise_and_merge(locus, None, do_error_learning=False)"]
    K1 --> M1["R腳本使用 selfConsist=TRUE"]
    M1 --> L1["Mode 1 完成"]
    
    %% Mode 2: Second Error Learning
    C -- "mode=2 (SECOND_ERROR_LEARNING)" --> D2["檢查 config.dada2LearnErrorFile"]
    D2 --> E2{"是否有自定錯誤學習路徑?"}
    E2 -- "有" --> F2["error_dir = config.dada2LearnErrorFileHelper + dada2LearnErrorFile"]
    E2 -- "無或空" --> G2["error_dir = filtered/ (預設路徑)"]
    F2 --> H2["run_filter_and_trim(locus)"]
    G2 --> H2
    H2 --> I2["第一階段: run_denoise_pipeline(do_error_learning=True, error_dir)"]
    I2 --> J2["pipeline.run_learn_error_rates(locus, error_dir)"]
    J2 --> K2["pipeline.run_denoise_and_merge(locus, error_dir, do_error_learning=True)"]
    K2 --> N2["執行 error_learning_2nd_selector.py"]
    N2 --> O2["分析第一階段降噪結果"]
    O2 --> P2["篩選適合錯誤學習的樣本"]
    P2 --> Q2["複製到 error_learning_2nd/ 目錄"]
    Q2 --> R2["第二階段: error_learning_dir_2nd = {locus}_result/demultiplexResult/error_learning_2nd"]
    R2 --> S2["run_denoise_pipeline(do_error_learning=True, error_learning_dir_2nd)"]
    S2 --> T2["pipeline.run_learn_error_rates(locus, error_learning_dir_2nd)"]
    T2 --> U2["pipeline.run_denoise_and_merge(locus, error_learning_dir_2nd, do_error_learning=True)"]
    U2 --> L2["Mode 2 完成"]
    
    %% 統一後續流程
    L0 --> V["繼續 Merge 階段"]
    L1 --> V
    L2 --> V
    V --> W["run_merge(config, locus, locus_index)"]
    W --> X["所有 loci 處理完成"]

若使用預設錯誤學習路徑(使用者未提供 dada2LearnErrorFile)，程式會以 PowerBarcoderResultPathManager.get_default_error_learning_dir()(等同 get_demultiplex_filtered_path())作為 error_learning_dir。 > - run_denoise_and_merge 在呼叫 Rscript 時會先由 PowerBarcoderResultPathManager.get_error_rate_rds_paths(do_error_learning) 取得 (errF_rds, errR_rds)，並把 do_error_learning 以 str(do_error_learning).upper() 的形式傳遞給 R(TRUE/FALSE)。因此錯誤率路徑的決策在 Python 層完成，Rscript 接收實際檔案路徑或空字串。

二階段錯誤學習(Mode 2)在第一階段完成後會呼叫 src/denoise/error_learning_2nd_selector.py 的 run_selector(resultDataPath, locus)，選出的檔案複製到 PowerBarcoderResultPathManager.get_demultiplex_error_learning_2nd_path()({locus}_result/demultiplexResult/error_learning_2nd/)，第二階段以該目錄為 error learning 資料來源。

2. Denoise模式設計

2.1 三種處理模式

Mode 0 - 預設模式 (DEFAULT)

功能：使用標準錯誤學習流程進行降噪
適用情境：一般序列資料，品質正常
錯誤學習來源：系統預設或使用者指定路徑

Mode 1 - 無錯誤學習模式 (NO_ERROR_LEARNING)

功能：跳過多樣本錯誤率學，使用 err = NULL, selfConsist = TRUE 參數配置，直接進行降噪
適用情境：高品質資料或需快速處理的場景
處理特點：DADA2 演算法從資料中即時估計錯誤率

Mode 2 - 二階段錯誤學習模式 (SECOND_ERROR_LEARNING)

功能：先進行標準降噪，再選取代表性序列進行第二次錯誤學習
適用情境：高雜訊資料或需精細化處理的複雜樣本
處理特點：透過樣本多樣性評估篩選出適合用於錯誤模型訓練的高品質序列作為第二階段學習材料

2.2 模式選擇建議

一般使用者：建議使用 Mode 0，系統會自動處理大部分情況
品質確定良好：可選擇 Mode 1 加速處理
複雜樣本或高雜訊：建議使用 Mode 2 獲得更佳結果

3. 核心處理步驟

3.1 品質過濾 (filter_and_trim)

功能說明：移除低品質序列片段和過短的讀段，確保後續分析的序列品質。
輸入資料
- 來源：demultiplex 階段的 trimmed 目錄
- 格式：配對的 R1/R2 FASTQ 檔案 (如：{locus}_{primerF}_{primerR}_r1.fq)
處理邏輯
- 使用 DADA2 的 filterAndTrim 函數進行平行處理
- 根據品質分數和序列長度進行過濾
- 確保 R1/R2 配對關係維持完整
輸出結果
- 位置：demultiplexResult/filtered/ 目錄
- 內容：品質過濾後的 FASTQ 檔案，格式與輸入相同

3.2 錯誤率學習 (learn_error_rates)

功能說明
- 建立序列錯誤機率模型，用於區分真實生物變異與定序技術錯誤。
輸入資料
- 使用者可於前端欄位 Dada2 Learn Error Files Folder Path 中指定 error learning data path。
- 若未指定，系統預設第一次 error learning 使用每個 locus 對應的 resultDataPath/{locus}_result/demultiplexResult/filtered/ 目錄下所有序列。路徑決策現由 Dada2DenoisePipeline.run_denoise() 完成，下游 Python/R 僅執行。
- 二階段 error learning 時，第二階段會以 error_learning_2nd_selector.py 選取代表性序列，並以新目錄 error_learning_2nd 作為 error learning 資料。
- 例如：trnLF 會拿 trnLF_result/demultiplexResult/error_learning_2nd/ 內所有 .fq 檔案。
處理邏輯
- src/denoise/steps/02_learn_error_rates.R 的實作細節：
  - 此 Rscript 會以三個參數被呼叫：<output_dir> <locus_name> <error_learning_dir>(由 Python 的 Dada2DenoisePipeline.run_learn_error_rates 傳入)。
  - 腳本步驟：
    1. 列出 error_learning_dir 下的 R1 / R2 .fq/.fastq 檔(Python 層在選擇 error learning 目錄後，不在 R 腳本內做路徑選擇邏輯)。
    2. 對每一方向(F/R)分別呼叫 dada2_core.R 中的 learn_error_rates_single，並輸出 .rds 與 .txt 的錯誤率矩陣與 PNG 圖表。
    3. 每次學習完成後，將 errF / errR 模型以 {locus}_error_rate_F.rds / {locus}_error_rate_R.rds 命名放置於 denoiseResult 對應目錄。
  - 請確保 learn_error_rates_single 的輸入與輸出是：輸入為一組 fastq 檔路徑清單，輸出為可序列化的 error-model 物件(可寫成 RDS)，並產生一張錯誤分布 PNG 與文字矩陣備份。
- src/denoise/dada2_core.R 的責任界定：提供核心的 DADA2 wrapper(例如 learn_error_rates_single, dada_wrapper, merge_pairs_wrapper)，不應該自行決定檔案系統路徑；路徑與檔案清單由上層腳本負責提供。
輸出結果
- 錯誤率矩陣：.txt 和 .rds 格式
- 視覺化圖表：錯誤率分布圖 (.png)
- (降噪 fasta 於下一步 03_denoise_and_merge.R 產生)

3.3 ASV 降噪與序列合併 (denoise_and_merge)

功能說明
- 使用錯誤率模型進行 ASV 推斷，去除技術雜訊，並將 R1/R2 配對序列合併。
輸入資料
- 過濾後的 FASTQ 檔案 (來自 filtered 目錄)
- 錯誤率模型檔案 (若啟用錯誤學習)
- Barcode mapping 檔案
處理邏輯
- 03_denoise_and_merge.R 主要函式包含：
  - dada() 函數：對 R1/R2 分別進行降噪處理
  - mergePairs() 函數：合併配對序列
  - 平行處理：支援多樣本同時處理
  - 容錯機制：單一樣本失敗不影響其他樣本

二階段輸出結果

降噪序列：denoiseResult/r1/ 與 denoiseResult/r2/ 目錄的 FASTA 檔案(失敗樣本建立空 placeholder .fas 以維持配對紀錄)
合併序列：mergeResult/dada2/merged/ 目錄
10N 拼接：mergeResult/merger/nCatR1R2/ 目錄
配對資訊：denoise_pairs.txt 檔案

3.4 二階段錯誤學習

功能說明
- 在二階段模式中，先以全體學習錯誤率，再根據第一階段結果，透過 error_learning_2nd_selector.py 選取代表性序列進行第二次錯誤學習與降噪(包含從 denoise_pairs.txt 反向映射到原始 filtered fastq 檔名再複製)。
  
  補充：DADA2 論文中的「污染物 (Contaminants)」是指透過生物學比對(BLAST nt 資料庫)確認為真實存在但不受歡迎的生物變異，而 PowerBarcoder Denoise 模組 (Mode 2) 採用的標準是序列豐度與多樣性比例，這兩者的定義存在差異。PowerBarcoder 的分類主要服務於優化錯誤率學習的目標，而非最終的生物學污染物鑑定。因此，重點放在「樣本多樣性是否適合用於錯誤模型訓練」。
輸入資料
- 第一階段的降噪結果 (denoiseResult/r1/ 和 denoiseResult/r2/)
- 對應的 FASTQ 檔案
處理邏輯
- 關鍵函式：
  - apply_selection_criteria() 樣本多樣性評估標準
    - 針對共同存在於 R1/R2 的樣本，呼叫 process_dada2_abundance_data 取得 [ASV_count, best_ASV_proportion, best_ASV_number, hash]，若兩方向 ASV 數皆 > 0 且任一方向 best_ASV_proportion > 0.95 則標為 dominant_asv，否則列入 diverse_asv。
    - check_fastq_nbase_and_nread() 資料量驗證：
      - 讀取 validate_list 中所有 fastq，對每 4 行取序列行累計總 base pair 與總 reads；若 total_base_pair < 10000 或 total_reads < 30，寫入 warning 並建議回退至預設 error learning。
    - copy_files() 複製選中的檔案：
      - 將經過映射後的 diverse ASV fastq 路徑(一組 R1/R2)以 shutil.copy2 複製到 error_learning_2nd 目錄，若複製失敗以 warning 記錄；目錄不存在時先建立目錄以確保第二階段可讀取檔案。

ASV 分類標準

ASV 數量檢查：R1 和 R2 都必須有 ASV (>0)
優勢度檢查：若任一方向最佳 ASV 比例 > 0.95 視為主導性 ASV
分類結果：多樣性 ASV 樣本 (diverse_asv_samples.txt)、主導性 ASV 樣本 (dominant_asv_samples.txt)、單獨去噪樣本 (single_r1_denoised_samples.txt, single_r2_denoised_samples.txt)

輸出結果

選擇記錄：selection_results/ 目錄的分類檔案
第二階段資料：error_learning_2nd/ 目錄的 FASTQ 檔案(若 total_base_pair < 10000 或 total_reads < 30 會警告建議改用預設 filtered)

3.5 嵌合體移除 (Chimera Removal)

功能說明
- 在 DADA2 denoise and merge 流程中集成嵌合體移除步驟，去除 PCR 擴增過程中產生的假序列。
- 嵌合體(Chimera)是由多個親本序列片段結合而成的混合序列，會導致多樣性高估。
處理邏輯
- 核心函數：removeBimeraDenovo(unqs, method="per-sample", ...)
- 參數設定：
  - method="per-sample"：針對每個樣本獨立分析(推薦用於 single-specimen barcode)
  - minFoldParentOverAbundance=2：親本豐度需為嵌合體的 2 倍以上
  - multithread=FALSE：在 foreach 迴圈內避免嵌套平行
- 實作位置：src/denoise/steps/03_denoise_and_merge.R
  1. 建立序列特徵表 (makeSequenceTable)
  2. 執行嵌合體移除 (removeBimeraDenovo)
  3. 篩選非嵌合體序列：僅保留確認為真實生物序列的 ASVs
執行效果
- 移除：將嵌合體序列從 mergers 中過濾出去
- 日誌：記錄每個樣本移除前後的 ASV 數量
- 下游影響：合併序列僅包含非嵌合體，提高 QC 指標與最終輸出精確度

4. 系統架構實作

4.1 主控流程設計

Python 主控

檔案：src/denoise/dada2_denoise.py
功能：協調各步驟執行，處理參數傳遞與錯誤處理
主要類別：Dada2DenoisePipeline

R 腳本執行

實際的生物資訊處理由 R 腳本完成
Python 負責參數準備與流程控制
支援即時輸出串流至前端

4.2 關鍵腳本架構

Python 腳本
- src/powerBarcode.py：流程啟動與模式判斷
- src/denoise/dada2_denoise.py：主控流程
  1. run_filter_and_trim：呼叫 01_filter_and_trim.R，進行序列品質過濾與修剪。
  2. run_learn_error_rates：呼叫 02_learn_error_rates.R，根據 error learning 路徑進行錯誤率學習。
  3. run_denoise_and_merge：呼叫 03_denoise_and_merge.R，依據錯誤率模型進行 ASV 降噪並直接合併。
- src/denoise/error_learning_2nd_selector.py：二階段錯誤學習選取器
  - 依據 denoise 結果，篩選適合用於錯誤模型訓練的樣本，並將其對應的 fastq 複製到新目錄，供第二階段 error learning 使用。
  - 具體步驟：
    1. 讀取 denoiseResult/r1, r2 目錄下的降噪結果。
    2. 依 abundance 與比例等條件篩選代表性樣本。
    3. 輸出篩選結果到專用 selection_results 資料夾，包含四個分類檔案：
      - diverse_asv_samples.txt：多樣性樣本檔案清單
      - dominant_asv_samples.txt：優勢序列樣本檔案清單
      - single_r1_denoised_samples.txt：僅 R1 有降噪結果的樣本清單
      - single_r2_denoised_samples.txt：僅 R2 有降噪結果的樣本清單
      四類檔案的篩選方案與意涵說明：
      - diverse_asv_samples.txt：基於 DADA2 核心原理(參數化錯誤模型，記錄每種核苷酸轉換在不同品質分數下的發生率)，PowerBarcoder Mode 2，透過比較兩種極端特性樣本(高多樣性 diverse_asv vs. 高主導性 dominant_asv)的錯誤模型和降噪結果，可以驗證 DADA2 對輸入數據多樣性/純度的敏感度。
        
        篩選方案：從同時存在 R1/R2 降噪結果的樣本中，篩選出 R1 和 R2 方向皆有 ASV 序列，且兩方向的最佳 ASV 比例都 ≤ 0.95 的樣本
        
        背後意涵：這些樣本被認為是「正常的多樣性樣本」，適合用於第二階段錯誤學習。因為它們的序列多樣性適中，不會被單一優勢序列主導，有助於學習更準確的錯誤模式
        
        舉例說明：假設一個樣本在 R1 方向有 10 個不同 ASV，其中最大的 ASV 佔比 60%；R2 方向有 8 個不同 ASV，其中最大的 ASV 佔比 55%。這種樣本就會被歸類為 diverse_asv_samples
        
        理論優勢：提供廣泛的錯誤模型覆蓋度，能學習多種序列背景下的錯誤類型，提升模型穩定性；有助於提高對稀有變異的檢測能力。
        
        潛在限制：可能受生物學變異干擾，導致錯誤率估計輕微扭曲；計算成本隨樣本數線性增長。
        
        實驗結果：Diverse ASV 樣本在多數情況下能提供較全面的錯誤模型，對於複雜樣本的降噪效果優於單一樣本。
      - dominant_asv_samples.txt：
        
        篩選方案：從同時存在 R1/R2 降噪結果的樣本中，篩選出任一方向的最佳 ASV 比例 > 0.95 的樣本
        
        背後意涵：這些樣本來自單一來源，因為序列多樣性過低(單一序列佔比過高)，可能導致錯誤學習偏差。因此在第二階段錯誤學習中並非預設選擇對象
        
        舉例說明：假設一個樣本在 R1 方向有 2 個 ASV，其中一個 ASV 佔比高達 98%；R2 方向有 3 個 ASV，其中最大的 ASV 佔比 45%。由於 R1 方向超過 95% 閾值，這個樣本就被歸類為 dominant_asv_samples
        
        理論優勢：提供極純淨的錯誤信號，能精確估計錯誤率；有助於消除假陽性序列。
        
        潛在限制：錯誤模型可能偏差或不完整，缺乏多樣性觀察；可能低估真實的生物學變異。
        
        實驗結果：Dominant ASV 樣本在 trnLF 基因座表現優於 Diverse ASV，但其他基因座都不如 Diverse ASV，顯示其適用性有限。
      - single_r1_denoised_samples.txt：
        
        篩選方案：僅存在 R1 降噪結果檔案，但沒有對應 R2 降噪結果檔案的樣本
        
        背後意涵：表示 R2 方向的序列在降噪過程中完全被過濾掉或丟失，可能由於品質過差、定序失敗或資料處理問題。這些樣本無法提供完整的配對資訊，不適合用於錯誤學習
        
        舉例說明：原始資料中有樣本 A 的 R1 和 R2 FASTQ 檔案，但在降噪後只找到 sample_A_r1.fas，沒有 sample_A_r2.fas。這種情況通常表示 R2 reads 的品質太差，在前期過濾中被完全移除
      - single_r2_denoised_samples.txt：
        
        篩選方案：僅存在 R2 降噪結果檔案，但沒有對應 R1 降噪結果檔案的樣本
        
        背後意涵：與 single_r1_denoised_samples 類似，表示 R1 方向的序列有問題。這種不對稱性可能影響配對合併的準確性，因此不納入錯誤學習材料
        
        舉例說明：樣本 B 的 R1 reads 在品質過濾階段因長度不足被丟棄，但 R2 reads 通過了過濾，導致降噪結果中只有 sample_B_r2.fas 存在
    4. 複製對應 fastq 檔案到 error_learning_2nd 目錄。
    5. 檢查資料量是否足夠，若不足會警告並建議回退預設 error learning。
R 腳本
- 01_filter_and_trim.R：品質過濾
  - 列出 barcode mapping 中同時有 primerF/primerR 的樣本，為每個樣本產生預期的 R1/R2 輸入路徑，並呼叫 filter_reads_parallel(內部使用 DADA2::fastqPairedFilter，matchIDs=TRUE、compress=FALSE)以平行處理過濾；若找不到配對 fastq，會記錄 warning 並建立 placeholder 以維持後續流程一致性。
- 02_learn_error_rates.R：錯誤率學習
  - 以三個參數被呼叫(output_dir, locus_name, error_learning_dir)，列出 error_learning_dir 底下的 .fq/.fastq 檔並以檔名模式分出 R1/R2，分別呼叫 learn_error_rates_single(errF_files, ...) / learn_error_rates_single(errR_files, ...)，並輸出 {locus}_error_rate_{F|R}.rds、.txt 與 PNG 圖表；若資料不足或缺方向檔案則以非 0 退出。
- 03_denoise_and_merge.R：降噪與合併
  - 對每個 mapping 的樣本構造 filtered R1/R2 路徑，若提供且可讀取 err RDS 則把 err 傳入 dada(err=errF/errR, multithread=TRUE)，否則以 err=NULL, selfConsist=TRUE 執行即時錯誤估計；對 dada() 與 mergePairs() 的錯誤以 tryCatch 捕捉，失敗時建立空或 placeholder 輸出並在 denoise_pairs.txt 中仍記錄該 sample，合併成功輸出至 mergeResult/dada2/merged/，無論標準合併結果如何都會嘗試 10N 拼接(justConcatenate=TRUE)並輸出至 mergeResult/merger/nCatR1R2/，供其他模組 (如 src\merge 模組) 使用。
- dada2_core.R：核心函式庫
  - 提供 learn_error_rates_single(read_files, path_regional, locus_name, direction)(內部呼叫 learnErrors(..., multithread=TRUE) 並回傳可 saveRDS 的 model)與 filter_reads_parallel(R1,R2,filtFs,filtRs)(以 %dopar% 平行執行 fastqPairedFilter)等 wrapper，規範核心計算不負責路徑決策，路徑與檔案清單由上層 script 傳入。

4.3 參數傳遞策略

統一布林值控制
- 使用前端 Denoise Mode 決定的 do_error_learning 參數，控制是否進行錯誤學習
- Python 使用 do_error_learning 參數控制是否進行錯誤學習(由 Dada2DenoisePipeline.run_denoise_and_merge 傳入)。
- Python 層會把布林值轉為字串並以大寫傳入 R(例如 str(do_error_learning).upper()，會傳入 TRUE/FALSE)，因此 R 腳本應以字串或等價布林邏輯接收該參數。
- 當 do_error_learning=FALSE 時，errF_rds / errR_rds 參數仍會被 Python 傳入(可能為空字串)；R 腳本應接受空值情形並改為在 R 端執行 dada(..., err=NULL, selfConsist=TRUE) 的流程。
- Dada2DenoisePipeline 會使用 PowerBarcoderResultPathManager.get_error_rate_rds_paths(do_error_learning) 來取得 errF_rds / errR_rds，所以任何與錯誤率模型路徑相關的決策應在 Python 層完成，R 腳本不應重複路徑判斷。
- Python -> R 的命令列參數(以 run_denoise_and_merge 為例)：
  - arg0: <filtered_dir>
  - arg1: <output_dir>
  - arg2: <do_error_learning> (TRUE/FALSE)
  - arg3: <errF_rds>
  - arg4: <errR_rds>
  - arg5: <barcode_file>
  - arg6: locus
  - arg7: primerFName
  - arg8: primerRName
  - arg9: min_overlap
  - arg10: max_mismatch
- 例外處理：Python 的 run_subprocess_with_logging 會捕捉 subprocess 的 stdout/stderr，並在 exit code != 0 時返回 False；因此 R 腳本應在錯誤情況以非 0 退出來通知 Python 層。
路徑管理
- 使用 PowerBarcoderResultPathManager 統一管理路徑
- 自動處理不同模式的路徑需求
- 支援自訂錯誤學習路徑

5. 檔案組織與資料流

5.1 目錄結構設計

resultDataPath/
└── {locus}_result/
    ├── demultiplexResult/
    │   ├── trimmed/          # 修剪後原始檔案
    │   ├── filtered/         # 品質過濾後檔案
    │   └── error_learning_2nd/  # 二階段錯誤學習選取檔案
    ├── denoiseResult/
    │   ├── r1/               # R1 降噪結果
    │   ├── r2/               # R2 降噪結果
    │   ├── selection_results/    # 二階段篩選結果
    │   ├── denoise_pairs.txt     # 樣本配對資訊
    │   ├── {locus}_error_rate_F.*  # F 方向錯誤率檔案
    │   └── {locus}_error_rate_R.*  # R 方向錯誤率檔案
    └── mergeResult/
        ├── dada2/merged/     # DADA2 合併結果
        └── merger/nCatR1R2/  # 10N 拼接結果

5.2 檔案格式規範

序列檔案
- FASTQ：原始與過濾後序列
- FASTA：降噪與合併後序列
模型檔案
- RDS：錯誤率模型 (R 格式)
- TXT：錯誤率矩陣 (純文字)
- PNG：錯誤率視覺化圖表

5.3 Sample Name 生成邏輯

生成規則
- 系統使用 barcode mapping file 的欄位組合生成樣本名稱： 欄位3_欄位4_欄位2_欄位1
欄位說明
- 欄位1：specimen ID 或 lab code
- 欄位2：collection ID 或 field number
- 欄位3：species name (屬名)
- 欄位4：species name (種小名) 或 specimen info
輸出格式
- denoise_pairs.txt 格式：barcode_name,sample_name
- 範例：trnLF_L5675_br01_F4121_br16,Bolbitis_nodiflora_Wade1560_KTHU2166

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

降噪 (Denoising)

1. 模組概述

1.1 模組功能

1.2 術語說明

1.3 技術特色簡述

1.4 輸入資料

1.5 預期輸出

1.6 處理流程

2. Denoise模式設計

2.1 三種處理模式

Mode 0 - 預設模式 (DEFAULT)

Mode 1 - 無錯誤學習模式 (NO_ERROR_LEARNING)

Mode 2 - 二階段錯誤學習模式 (SECOND_ERROR_LEARNING)

2.2 模式選擇建議

3. 核心處理步驟

3.1 品質過濾 (filter_and_trim)

3.2 錯誤率學習 (learn_error_rates)

3.3 ASV 降噪與序列合併 (denoise_and_merge)

二階段輸出結果

3.4 二階段錯誤學習

ASV 分類標準

輸出結果

3.5 嵌合體移除 (Chimera Removal)

4. 系統架構實作

4.1 主控流程設計

Python 主控

R 腳本執行

4.2 關鍵腳本架構

4.3 參數傳遞策略

5. 檔案組織與資料流

5.1 目錄結構設計

5.2 檔案格式規範

5.3 Sample Name 生成邏輯

FilesExpand file tree

denoise.md

Latest commit

History

denoise.md

File metadata and controls

降噪 (Denoising)

1. 模組概述

1.1 模組功能

1.2 術語說明

1.3 技術特色簡述

1.4 輸入資料

1.5 預期輸出

1.6 處理流程

2. Denoise模式設計

2.1 三種處理模式

Mode 0 - 預設模式 (DEFAULT)

Mode 1 - 無錯誤學習模式 (NO_ERROR_LEARNING)

Mode 2 - 二階段錯誤學習模式 (SECOND_ERROR_LEARNING)

2.2 模式選擇建議

3. 核心處理步驟

3.1 品質過濾 (filter_and_trim)

3.2 錯誤率學習 (learn_error_rates)

3.3 ASV 降噪與序列合併 (denoise_and_merge)

二階段輸出結果

3.4 二階段錯誤學習

ASV 分類標準

輸出結果

3.5 嵌合體移除 (Chimera Removal)

4. 系統架構實作

4.1 主控流程設計

Python 主控

R 腳本執行

4.2 關鍵腳本架構

4.3 參數傳遞策略

5. 檔案組織與資料流

5.1 目錄結構設計

5.2 檔案格式規範

5.3 Sample Name 生成邏輯