数据准备与输入要求
在开始分析之前，请根据您当前持有的数据类型，选择对应的处理流程。
场景一：已有 CopyKit 结果文件 (RDS)
如果您已经拥有经 CopyKit runVarbin 处理生成的 .rds 文件（如下所示），可直接跳过本章节，进入后续分析环节。
./
├── copykit_MDA_cs_1Mb.rds # 1Mb 分辨率结果
├── copykit_MDA_cs_500kb.rds # 500kb 分辨率结果
└── copykit_MDA_cs_200kb.rds # 220kb 分辨率结果场景二：已有单细胞 BAM 文件
如果您持有由 SeekSoulMethyl 流程生成的单细胞 BAM 文件（通常位于 xxx/xxx_methy/step3/split_bams/merged 目录），文件结构如下：
./merged/
├── AAAGAAGAAGAGTTTAG.bam
├── AAAGAAGAAGGAGTGGT.bam
├── ...
└── TTTGGATATTTGTGAGG.bam后续步骤：您需要执行 阶段二：BAM 文件预处理，进行 Flag 矫正和去重。
场景三：仅有 Bulk 水平 BAM 文件
如果您仅有未拆分的“Bulk”水平 BAM 文件（即包含所有细胞 reads 的合并文件），文件结构如下：
./bismark/
├── MDA_cs_forward_AAAG_1_bismark_bt2_pe.bam
├── MDA_cs_forward_AAAT_1_bismark_bt2_pe.bam
├── ...
└── MDA_cs_reverse_TTTG_1_bismark_bt2_pe.bam后续步骤：您需要先执行 阶段一：单细胞 BAM 拆分，再进行 阶段二：BAM 文件预处理。
3. 数据处理流程
阶段一：单细胞 BAM 拆分 (仅适用于场景三)
我们需要将 Bulk BAM 文件按细胞 Barcode 拆分为独立的单细胞 BAM 文件。
拆分步骤包含三步：
- 1）将每个 BAM 按照 read 名称进行排序（name-sort）
- 2）从每个排序后的 BAM 文件中拆分出单细胞 BAM 文件
- 3）合并单个细胞的 forward 和 reverse BAM 文件
工具准备：
操作步骤： 使用 batch_single_cell_bam.py 脚本进行批量拆分。
# 示例命令
python batch_single_cell_bam.py \
--assay_type DD-MET5 \
--bam_dir /path/to/bismark/ \
--outdir /path/to/output/ \
--gex_barcodes /path/to/filtered_feature_bc_matrix/barcodes.tsv.gz \
--threads 4 \
--parallel_jobs 8
# 参数说明：
# --assay_type : 测序类型 (DD-MET5 或 DD-MET3)
# --bam_dir : 输入的 Bulk BAM 文件目录
# --outdir : 输出目录
# --gex_barcodes : 对应的 RNA Barcode 文件
# --parallel_jobs : 并行任务数 (建议设为 8-16，视服务器配置而定)
# --cbcsv : (仅 DD-MET3) 指定白名单文件路径执行完成后，单细胞 BAM 文件将生成于 /path/to/output/split_bam 目录下。
阶段二：BAM 文件预处理 (Flag 调整与去重)
CNV 分析对 Read 计数非常敏感，因此必须确保输入数据的准确性。本阶段包含两个关键步骤：Flag 矫正和UMI 去重。
工具准备：
步骤 1：调整 Reads 的 Flag 值 (Flag Correction)
背景： Bismark 比对工具在处理 OT/OB（原始链）和 CTOT/CTOB（互补链）时，会自动调换 CTOT/CTOB reads 的 Flag 值。具体表现为 R1 被标记为 "second in pair"，而 R2 被标记为 "first in pair"。 为了确保后续去重工具（如 umi_tools）能正确识别 R1 和 R2，我们需要将这些 Flag 恢复正常。
操作命令：
# 配置参数
outdir="./"
input_dir="/path/to/step3/split_bams/merged/" # 单细胞 BAM 所在目录
workers=16 # 并行数
# 1. 生成文件列表
find -L "$input_dir" -name "*.bam" | sort > "$outdir/bam_list.txt"
# 2. 创建输出目录
mkdir -p $outdir/flag_reverse/
# 3. 执行 Flag 矫正
python step1_swap_flags_on_reverse.py \
--bam_list $outdir/bam_list.txt \
--out_dir $outdir/flag_reverse \
--max_workers $workers耗时参考 基于 24 核心服务器测试：处理 3,641 个单细胞 BAM 文件约需 30~40 分钟。
步骤 2：UMI 去重 (UMI Deduplication)
背景： 单细胞甲基化文库构建过程中引入了随机打断和 PCR 扩增。为了消除 PCR 偏好性对 CNV 估计的影响，我们需要进行去重。 由于同一个文库片段末端是随机打断的，我们采用 R1 比对位置 + UMI 序列 作为去重的唯一标识（Unique Identifier）。
操作命令： 使用 umi_tools 进行去重，关键参数为 --extract-umi-method tag --umi-tag UR --paired --ignore-tlen。
安装 umi_tools： 如果您的环境中尚未安装 umi_tools，可以使用pip/conda/micromamba进行安装：
shell# micromamba 安装 micromamba install -c bioconda umi_tools # conda 安装 # conda install -c bioconda umi_tools # pip 安装 # pip install umi_tools
# 1. 生成矫正后的 BAM 列表
find "$outdir/flag_reverse" -name "*.bam" | sort > "$outdir/swapflags_bam_list.txt"
# 2. 创建输出目录
mkdir -p $outdir/umi_tools_swapflags_dedup_bam/
# 3. 执行去重
python step2_umi_tools_dedup.py \
--bam_list $outdir/swapflags_bam_list.txt \
--out_dir $outdir/umi_tools_swapflags_dedup_bam/ \
--max_workers $workers \
--skip_existing耗时参考 基于 24 核心服务器测试：处理 3,641 个单细胞 BAM 文件约需 4 小时。
最终结果： 去重后的 BAM 文件将存储在 $outdir/umi_tools_swapflags_dedup_bam/ 目录下。这些文件即为 CopyKit 分析的最终输入文件。