跳转至
返回 Liquid Agent 首页 使用文档

血液信号预处理（中文）

预处理层位于原始或近原始血液活检输入与下游编码/分析之间。

主要模块：

  • src/liquidbiopsy_agent/preprocessing/

主要入口脚本：

  • scripts/preprocess_epigenomic_signal.py
  • scripts/preprocess_lpwgs_signal.py
  • scripts/preprocess_variant_signal.py

普通引导式使用从 liquid-agent 或 liquid-agent web 开始，以自然语言请求预处理。直接脚本仍是可复现的底层路径。

功能

当前可执行的子集：

  • BED 类输入的区间/峰清洗
  • 从 BAM / CRAM 提取生成片段数据
  • 可选重点区域选择
  • 可选黑名单过滤
  • 可选片段长度过滤
  • 表观基因组区域 panel 聚合
  • 提供背景 BED 时的 cfChIP 背景感知汇总
  • cfMeDIP / MeDIP 缩放因子标准化
  • LPWGS 分箱计数导出、轻量校正、分段和染色体臂负荷汇总
  • 变异表格标准化，可选 QUAL / VAF / CHIP 过滤
  • 变异表格的配对正常样本 / PBMC 重叠过滤

仍面向未来的部分：

  • 真正的 UMI 共识生成
  • 更丰富的 CNV 模型
  • 超出已实现的用户提供背景路径的检测专用 cfChIP 背景模型

已实现的配置方案

cfchip_seq

  • cfchip_interval_cleanup
  • cfchip_panel_summary
  • cfchip_background_aware

cfmedip_seq / medip_seq

  • 仅清洗方案
  • panel 汇总方案
  • 缩放标准化 panel 方案

lpwgs / ulpwgs

  • lpwgs_interval_cleanup / ulpwgs_interval_cleanup
  • lpwgs_cleanup_only / ulpwgs_cleanup_only
  • lpwgs_gc_corrected / ulpwgs_gc_corrected

ctdna_variant / variant

  • variant_table_qc
  • variant_strict_somatic
  • variant_matched_normal

自然语言引导

当下游任务自动插入预处理时，助手现在会将下游目标传入配置选择。因此以下线索仍会影响所选的已实现预处理路径：

  • promoter panel
  • background-aware
  • GC-corrected
  • strict somatic
  • matched normal

助手行为

助手可以：

  • 复用兼容的预处理输出
  • 使用更匹配的已实现配置重新运行预处理
  • 仅在下游任务已经可直接运行时跳过预处理

这是一个 LLM 输入参与决策、但仍受显式工作流合法性检查约束的环节。

方法来源

预处理层以文献为依据，但部分实现有意比标准检测流水线更轻量：

  • LPWGS 校正与分段受 HMMcopy / ichorCNA 类工作流启发，但当前是实用的轻量变体，而非完整复现。
  • cfChIP 预处理支持实用的用户提供背景标准化，不是完整的检测原生背景模型。
  • cfMeDIP 预处理包含有用的标准化接入点，但不是完整的以 spike-in 为核心的定量工作流。
  • 变异预处理涵盖表格级 QC、体细胞式过滤和配对正常样本重叠，但不包含真正的 UMI 家族共识。

参考文献与理由见组件与方法。

关键参考：

CLI 示例

表观基因组：

python scripts/preprocess_epigenomic_signal.py \
  --signal cfchip_seq \
  --input_format bed.gz \
  --input_dir <raw_interval_dir> \
  --region_set_bed <region_panel_bed>

LPWGS：

python scripts/preprocess_lpwgs_signal.py \
  --signal lpwgs \
  --input_format bed.gz \
  --input_dir <lpwgs_interval_dir> \
  --bin_annotation_table <bin_annotation_table> \
  --arm_annotation_table <arm_annotation_table>

变异：

python scripts/preprocess_variant_signal.py \
  --signal ctdna_variant \
  --input_format csv \
  --input_dir <variant_table_dir> \
  --exclude_chip_genes \
  --matched_normal_dir <matched_normal_variant_dir>

输出约定

默认根目录：

  • <dataset>/preprocessed/...

常见输出：

  • intervals/
  • regions/
  • bins/
  • corrected_bins/
  • segments/
  • arm_burden/
  • variants/
  • preprocessing_summary.csv
  • preprocessing_summary.json