更新日志

作者: SeekGene

时长: 11 分钟

字数: 2.8k 字

更新: 2026-10-13

阅读: 0 次

甲基化 + RNA 双组学 更新日志

本项目的所有重要更改都将记录在此文件中。

[2.2.0] 2026-06-18

变更

• 所有工作流（Nextflow 和 Shell）的默认 chemistry 从 DD-MET3 变更为 DD-MET5，与 SeekOne DD 试剂盒默认设置保持一致。
• 新增对表达/甲基化 FASTQ R1/R2 配对数量的快速失败校验，避免样本输入不匹配时静默重复使用最后一个配对文件。
• sc_methy_workflow.sh：正向和反向 barcode 的 fastp QC 现在并行运行（轻量任务，对大数据集安全）。
• sc_methy_workflow.sh：多批次 FASTQ 合并现在直接拼接 gzip 成员，而非解压后重新压缩。
• step3_split_bams.py：BAM 拆分从多进程重复全文件遍历改为单次 barcode 分组遍历，减少冗余 I/O。
• barcode_cs_multi.py：为 distance > 1 的 barcode 校正新增基于 trie 的 Hamming 搜索，并修复了 QcStat.update() 嵌套计数器合并问题。
• step3_bam_to_allc.py：将 shell 字符串子进程调用替换为参数列表调用，并确保清理中间排序 BAM 文件。
• step4_wgs_summary.py：将重复的全报告正则扫描替换为逐行解析 Bismark 报告。
• 将 rna_met、met_only 和 forcecell 中通用的参数初始化代码（约 70 行）提取到共享模块 nf/modules/params_init.nf，减少代码重复。
• 为所有 force_cell process 和 MERGE_BISMARK_BAM 新增了 withName 资源配置。
• 将默认 METHYLATION_BARCODE_EXTRACTION 内存从 120 GB 降至 48 GB，并基于重试进行扩展。
• 使 Docker profile 容器镜像与 README 文档保持一致。
• nf/nextflow.config：动态内存 process 现在仅在前一次尝试因 OOM 类退出码（134、137–140）失败时，才在重试时将请求内存加倍；其他失败（如节点抢占导致的 143 SIGTERM）按原内存级别重试。已合并到共享的 oomAwareMemory 闭包，供全部 16 个动态内存 process 使用。需要 Nextflow >= 24.10.0（task.previousTrace）。
• nf/nextflow.config：将 manifest nextflowVersion 从 >=21.04.0 提升到 >=24.10.0，以匹配 oomAwareMemory 闭包（task.previousTrace）的实际运行要求。否则 Nextflow 21.04–24.09 能通过 manifest 检查，但在首次动态内存重试时会崩溃。

修复

• barcode_cs_multi.py：multi read 的链方向在 multi rescue 第二次遍历时从 adapter 剪切后的 R1 序列重新判定，可能相对第一次遍历使用的剪切前方向翻转 forward/reverse，或在剪切后 R1 过短无法覆盖方向判定位点时返回 unknown。 在 v2.1.2 及更早版本中，unknown 的 multi read 被计为 valid，但不计入 forward/reverse，也不包含在 forward_chimeric/reverse_chimeric 中，且不会写入 Bismark 输入 FASTQ 文件。这导致被 rescue 的 multi read 被静默丢弃，并使 Dropped_Chimeric 人为偏低——因为 unknown read 增大了分母却没有贡献到 chimeric 分子。已通过将剪切前 chain_direction 携带在 multi 临时 FASTQ read 名称中（barcode_old_candidate_list_umi_chain_direction_original_read_name）并在第二次遍历中复用来修复。
• barcode_cs_multi.py：get_new_bc() 对包含 N 的 barcode 进行单碱基错配校正时，mm_dict = {...} 会覆盖先前的候选；已改用 .update(...)，使 N 位置的替换与其余单碱基错配集合合并而非替换。
• barcode_cs_multi.py：当 line_A/line_B 为零（无合格 read）时，ct_mean/cc_mean 会出现除零。已新增 >0 保护，在 summary JSON 中输出 0.0 并附带 *_missing_evidence 标志，使下游报告可将该指标标记为缺失而非崩溃。
• barcode_cs_multi.py：CT/CC 窗口内平均质量低于 30 的 read 被静默地从转化率统计中丢弃；已新增 low_quality_skipped 计数器，使该损失现在在 summary 中可见。
• step3_split_bams.py / step3.nf：methy_only 工作流将甲基化 barcode 传给 --gexcb，但拆分器仍应用 gex_cb → m_cb 白名单映射，产生空细胞列表。已新增 --gexcb-is-methylation 并让 methy_only 使用它。
• step3_estimated_cells.py：filtered_barcode 以裸相对路径写入，落在 process 工作目录而非 outdir；已固定为 os.path.join(outdir, 'filtered_barcode')。
• step3_merge_sc_metrics.py：barcode 提取匹配 _all.gz.count.csv，但实际文件是 _allc.gz.count.csv；不匹配会落到一个回退分支，在 barcode 上留下 _allc.gz 后缀，破坏下游连接。已将正确的后缀作为首选匹配。
• step3_mcds_manager.py：新增防御性合并前检查 _validate_unique_obs_across_shards()。xarray.Dataset.to_zarr(append_dim=...) 不会拒绝重复的 cell 坐标，因此含重复细胞（分片内或跨分片）的分片合并会静默生成 cell 索引含重复条目的合并 MCDS 而非失败。新检查在检测到重复时会快速失败并给出明确错误。tiny-demo 数据未观察到重复细胞；此项加固了合并逻辑对理论情形的防御。
• step4_report_rna_met.py：在 RNA + 甲基化连接前，新增防御性的 deduplicate_cells_by_m_cb()，将分片级甲基化细胞指标聚合为每个 m_cb 一行（通过 sum 累加计数器，根据累加计数器重新计算 weighted_mc_rate/cell_saturation/*_mc_rate，并验证 reads_counts 存在且为数值）。否则重复的 m_cb 行会以重复/笛卡尔积形式进入连接结果。tiny-demo 数据未观察到重复 m_cb 行；此项保护了连接逻辑对理论情形的防御。
• step4_wgs_summary.py：parse_cell_info 未去重即将 dataframe 索引设为 barcode，当 reads 计数 CSV 有重复时产生非唯一索引；现改为先按 barcode 分组并对 reads_counts 求和再设索引。
• step4_wgs_summary.py：Fraction Reads in Cells 除以 summary["mapping"]["uniquereads"] 时没有键/零值保护；当缺失或为零时回退到 0.0。
• step4_wgs_summary.py：单细胞 summary CSV 表头将 Reads_of_Max/Median_Cell 重命名为 Read_Pairs_of_Max/Median_Cell，以匹配实际单位（双端 read）。
• nf/modules/step1.nf：CREATE_FORWARD_PAIRS/CREATE_REVERSE_PAIRS 现在将 FASTQ 配对输出为 Nextflow path 输出（链接到每个 process 的输出目录），而非依赖 publishDir 副作用；先前设计存在下游任务与发布步骤竞争的风险。
• nf/modules/step1.nf：当某条链没有产生 read 时，METHYLATION_BARCODE_EXTRACTION 现在写入空的 gzip 占位文件，使下游 outer-join 逻辑能显式处理缺失方向，而非命中零匹配的 glob。
• nf/modules/step3.nf：MERGE_BISMARK_BAM 对空 forward/reverse 数组增加保护（set -u 下 for f in "${arr[@]}" 在数组为空时会报错），并在两侧均为空时发出警告。
• nf/modules/step3.nf：ALLCOOLS_MERGE 在追加前清空 merge_list_real.txt（: > merge_list_real.txt），使恢复的运行不会看到上次尝试的过期条目。
• nf/modules/force_cell_custom.nf：分析前的 pre_outdir 和 addtag_dir 现在声明为 path 输入（而非 val），使 Nextflow 真正将目录暂存到每个消费者的工作目录。先前的 val 形式导致下游 process 从不存在的路径读取。
• nf/modules/force_cell_custom.nf：FORCE_CELL_APPLY_ALLOCOOLS_CHANGES 从 find -maxdepth 1 改为递归 find（每个细胞的 ALLC 文件位于嵌套目录中），并新增删除后验证，若被丢弃 barcode 的文件仍存在则使 process 失败。
• nf/modules/force_cell_custom.nf：将 ossutil 调用中硬编码的 oss-cn-beijing-internal.aliyuncs.com 替换为 ${params.oss_endpoint}。
• nf/modules/force_cell_custom.nf：将 allcools.tar.gz/allcools_generate_datasets.tar.gz 的 oss_cp ... || true 静默回退替换为显式回退（下载底层目录并发出警告），使 tar 未命中时不再静默导致消费者无数据。
• nf/modules/step4.nf：METHYLATION_SUMMARY 将独立的 forward/reverse Bismark 报告输入整合为单个 bismark_reports 集合，并将 *_bismark_bt2_PE_report.txt 符号链接到 step2/bismark/，使摘要步骤在某一链缺失时不再中断。
• nf/modules/utils.nf：ESTIMATED_CELLS 输入元组移除了过时的 pair_id 元素，使正向和反向比对 read 计数 CSV 都能被接收用于细胞估计。
• docs/How_to_build_reference_genome.md：修正示例配置路径 nextflow.new.config → nextflow.config。
• 修复 methy_only barcode 提取后 FASTQ 路径重建，使其包含样本级发布目录。
• 修复 methy_only 细胞估计输入结构，使正向和反向比对 read 计数 CSV 都被暂存供 ESTIMATED_CELLS 使用。
• 修复 rna_met 下游分组，改用 MERGE_BISMARK_BAM 实际合并后的 forward/reverse 配对数量，而非 Math.max(forward_count, reverse_count)。
• 修复 barcode 提取后 FASTQ 数据流，使 rna_met 和 methy_only 消费 Nextflow path 输出，而非从异步的 publishDir 位置重建文件。
• 当 barcode 提取对某条链没有 read 时，新增空的 gzip forward/reverse 占位文件，使下游 outer-join 逻辑能显式处理缺失方向。
• 修复 OSS force_cell 暂存逻辑，使其直接写入下游 process 引用的稳定分析前暂存目录，避免 publishDir 符号链接竞争。

新增

• nf/modules/params_init.nf：共享参数初始化模块，包含 initCommonParams() 和 sanitizeSpaces() 函数。
• nf/bin/stage_file.sh：用于本地和 OSS 输入的共享文件暂存辅助脚本。
• nf/bin/lint_config_schema.py：轻量级 config/schema/version 一致性检查脚本。
• 新增 local_test profile，用于轻量级本地语法/配置检查。
• 在 nextflow_schema.json 中注册 params.oss_endpoint（默认 oss-cn-beijing-internal.aliyuncs.com），使 OSS 端点可配置。

[2.1.2] 2026-04-30

修复

• 删除了 Fastp 参数 --max-len1 60 --max-len2 0。
• 修复了几个配置问题。

[2.1.1] 2026-03-24

修复

• 解决了 sc_methy_workflow.sh 中的输入错误 "* Chromosome chrM doesn't present in the .genome file. *"。

[2.1.0] 2026-03-13

修复

• 修复了当正向和反向 fastq 数量不相等时批量 FASTQ 结果丢失的问题。

[2.0.0] 2026-02-26

新增

• 增加了构建参考基因组数据库目录 (--database_dir) 的指南。
• 增加了 force_cell 工作流，用于根据以前的输出更新结果。
• 增加了对 sample_id 和 outdir 的验证；现在不允许使用空格并将其规范化为下划线。

变更

• 通过拆分为较小的任务并合并结果优化了 MCDS 生成。
• 更新了代码仓库结构文档，以匹配当前的 DSL2 结构。

[1.0.7] 2026-01-23

修复

• 修复了 step3 模块中 allc_file_path.txt 文件无法正确生成的错误。
• 更新了 sc_methy_workflow.sh 以支持每个样本包含多个数据集。

[1.0.6] 2025-12-30

变更

• 更新了 nextflow.config。
• 更新了 methy_only.nf。
• 更新了 main.nf。

[1.0.5] 2025-12-22

变更

• 更新了 Barcode 白名单。

[1.0.4] 2025-12-18

变更

• 更新了 C-T 转化率算法。

[1.0.3] 2025-12-09

修复

• 修复了 rna_methyl_report.html 和 rna_methy_summary.csv 中的指标显示问题。错误地将 Read Pair 数显示为 Read 数（该问题存在于 v1.0.1 和 v1.0.2）。

[1.0.2] 2025-12-02

新增

• 新增 project 参数，用于为每个流程标记项目特定信息。

修复

• 修复了仅包含反向 Reads 或仅包含正向 Reads 的细胞被错误过滤的问题。

[1.0.1] 2025-11-21

变更

• 在 nextflow.config 中将工作流版本从 1.0.0 更新为 1.0.1。
• 更新了 HTML 报告中的 MET 部分，将数值标记并报告为“Read Pairs”而非“Reads”。

新增

• 新增汇总 CSV 文件 (rna_methy_summary.csv)，包含与 HTML 报告相同的指标，并保存在同一输出目录中。

[1.0.0] 2025-10-31

新增

• SeekSoul Methyl Tools 流程的初始版本发布，用于单细胞转录组和甲基化双组学分析。