Brieflow：光池筛选高通量分析一体化计算流程¶

1. 概述¶

光池筛选（Optical Pooled Screening, OPS） 是一种将高通量成像与集合遗传扰动相结合的功能基因组学方法。它通过在单次实验中引入数以万计的条形码化扰动，并利用显微镜自动采集海量细胞图像，让研究人员能够在全基因组或靶向基因集的规模上，系统分析基因功能如何影响细胞形态、亚细胞结构及时空动态。

然而，OPS 实验的原始数据体量庞大、模态复杂且缺乏统一的分析标准，给数据分析带来了巨大挑战：

图像与测序数据需要精确对齐，以将每个细胞的形态特征与其遗传扰动标签关联起来；
数据预处理、特征提取、校正和质量控制步骤繁多且相互依赖；
生物学家通常缺乏能够端到端（end-to-end）完成分析的计算工具链。

Brieflow 正是为解决这些痛点而设计的一体化计算流程。它专门针对固定细胞（fixed-cell）光池筛选数据，提供了从原始数据处理到最终生物学洞察的完整分析框架。Brieflow 整合了图像分析、条形码测序数据解析、多模态对齐、单细胞特征提取、批次校正与下游统计分析等关键步骤，帮助研究者快速、可重复地将海量原始数据转化为可解释的功能基因组学结果。

2. 核心知识点¶

2.1 光池筛选（OPS）数据流的构成¶

典型的固定细胞 OPS 实验包含两个高度互补的数据模态：

图像数据
由高内涵显微镜（high-content microscope）采集的多通道荧光图像。常见通道包括：
细胞标记物（如 Hoechst 核染色、鬼笔环肽染 F-actin）
亚细胞结构标记（如线粒体、溶酶体探针）
扰动特异性条形码荧光原位杂交（barcode FISH）或原位测序 信号
图像数据提供每个细胞的精确空间位置、形态轮廓及多通道强度分布。
测序数据
通过原位测序或原位杂交信号解析出每个细胞对应的sgRNA 条形码（barcode），从而建立细胞身份与遗传扰动之间的映射。这一环节通常生成高维条形码强度矩阵，需要从图像中提取并转换为可匹配的序列信息。

2.2 Brieflow 流水线架构¶

Brieflow 将上述两种数据模态的整合分析划分为几个逻辑模块，以模块化（modular）和可扩展的方式串联：

原始图像 → 细胞分割/特征提取 → 条形码解码与映射 → 
单细胞表型特征矩阵 → 质量控制 & 标准化 → 
扰动-表型关联分析 → 报告与可视化

模块功能概览：

模块	输入	输出	核心任务
Preprocessing	原始显微镜图像	校正后的图像堆栈	光照校正、背景扣除、通道对齐
Segmentation	校正后图像	单细胞掩膜	核分割、细胞体分割、边界优化
Feature Extraction	图像 + 掩膜	单细胞特征表	形态特征（面积、形状、纹理）、荧光强度特征
Barcode Decoding	条形码通道图像	单细胞条形码序列	原位条形码位点检测、信号去噪、序列比对与纠错
Data Alignment	特征表 + 条形码表	带扰动标签的特征矩阵	空间匹配、条形码匹配、质量过滤
Normalization & QC	带标签的特征矩阵	清洗后的标准化矩阵	批次效应校正、异常细胞移除、缺失值处理
Downstream Analysis	标准化矩阵	扰动-表型关联结果	差异分析、聚类、降维、基因签名发现

2.3 Brieflow 的关键设计原则¶

端到端集成：从原始显微镜图像到最终统计显著的结果列表，所有步骤均可在一个框架内完成，减少中间格式转换带来的信息丢失和人为错误。
可扩展的容器化部署：支持 Docker/Singularity 容器及工作流管理器（如 Snakemake、Nextflow），能够无缝迁移至云端或高性能计算集群（HPC）。
细胞身份保留：通过空间坐标和条形码的双重匹配，确保每个细胞的特征与其遗传扰动关联是唯一且可追溯的。
适应性分割与解码：内置多种预训练模型及参数模板，可适配不同的细胞类型（贴壁细胞、悬浮细胞、类器官）和条形码方案。
统计稳健性：提供针对高维稀疏数据的标准化方法（如 SCTransform 风格校正、回归批次变量），并支持混合线性模型进行扰动效应的差异检验。

3. 代码实操¶

以下是使用 Brieflow 命令行接口和 Python API 进行典型 OPS 数据分析的代码示例。假设数据组织如下：

project/
├── raw_images/       # .tif 原始图像
├── metadata.csv      # 孔板布局、通道映射、实验批次
├── barcode_ref.fasta # 条形码参考序列
└── config.yaml       # Brieflow 主配置文件

3.1 环境准备与初始化¶

# 拉取 Brieflow Docker 镜像
docker pull brieflow/brieflow:latest

# 交互式进入容器（挂载数据目录）
docker run -it --gpus all -v /path/to/project:/data brieflow/brieflow:latest

在容器内部激活 Brieflow 环境后，可以通过命令行构建索引：

# 初始化项目目录并生成数据分析DAG
brieflow init --project_path /data \
              --segmentation_method cellpose \
              --barcode_type MERFISH

3.2 细胞分割与特征提取¶

使用 Python API 调用分割和特征提取模块：

import brieflow as bf

# 加载实验配置
exp = bf.Experiment(config_path="/data/config.yaml")

# 对所有视场（field of view）进行分割
exp.run_segmentation(
    nuclei_channel="DAPI",
    cell_channel="Phalloidin",
    model="cyto3",
    min_cell_size=200,
    batch_size=64
)

# 提取单细胞多通道形态特征
feature_table = exp.extract_features(
    channels=["DAPI", "Alexa488", "Cy5", "TexasRed"],
    feature_set="DeepProfiler",  # 使用预训练特征提取器
    save_hdf5=True
)
print(f"提取到 {feature_table.shape[0]} 个单细胞特征")

3.3 条形码解码与多模态对齐¶

# 从条形码通道中解码每个细胞的 barcode 序列
barcode_table = exp.decode_barcodes(
    barcode_channels=["Cy5", "TexasRed"],
    reference_fasta="/data/barcode_ref.fasta",
    max_hamming_distance=2,      # 允许最多 2 个碱基错配
    min_signal_to_noise=3.0      # 信噪比阈值
)

# 将特征表与条形码表基于空间坐标进行匹配
aligned_data = bf.align_features_barcodes(
    features=feature_table,
    barcodes=barcode_table,
    spatial_radius=15,           # 细胞中心到条形码位点的最大距离（像素）
    method="nearest_neighbor"
)

# 新增 sgRNA 和 gene 注释列
aligned_data = bf.annotate_perturbation(
    aligned_data,
    library_file="/data/guide_library.csv"
)

3.4 质量控制与标准化¶

# 数据清洗与过滤
cleaned = bf.quality_control(
    aligned_data,
    min_features_per_cell=100,
    max_mitochondrial_intensity=0.2,
    outlier_sigma=3.5,
    remove_empty_barcodes=True
)

# 批次效应校正（以“板号”和“成像批次”为协变量）
normalized = bf.normalize(
    cleaned,
    method="combat_seq",
    batch_columns=["plate_id", "batch_id"],
    normalize_per_plate=True
)

3.5 下游分析示例¶

# 差异表型分析：比较特定基因敲除与阴性对照（Non-targeting Control）的形态距离
diff_results = bf.phenotype_differential(
    normalized,
    group_col="gene",
    baseline="NTC",
    metric="mahalanobis",        # 马氏距离
    n_permutations=10000,
    p_adjust_method="fdr_bh"
)

# 显著表型基因筛选
sig_hits = diff_results.query("p_adj < 0.01")
print(f"发现 {sig_hits.shape[0]} 个显著形态改变基因")

# 将结果导出为 CSV 和交互式 HTML 报告
diff_results.to_csv("/data/results/phenotype_hits.csv")
bf.generate_report(
    analysis_output=diff_results,
    output_dir="/data/reports/",
    report_type="html"
)

3.6 使用工作流引擎（Snakemake）自动化全流程¶

Brieflow 提供了预编制好的 Snakemake 工作流文件，可一键启动端到端计算：

# 编辑 config.yaml 中的路径与参数，然后执行
snakemake --cores 96 \
          --use-singularity \
          --snakefile /opt/brieflow/workflow/Snakefile \
          --directory /data

4. 常见问题¶

4.1 细胞分割不准确，尤其是高密度区域出现合并或过度分裂¶

解决方案
- 调整分割模块的直径范围参数（min_cell_size、max_cell_size），使模型适应实际细胞大小。
- 在 config.yaml 中启用边界增强预处理（edge_enhance: True），帮助分割算法在高密度区更好地界定边界。
- 如果有手动标注的 Ground-Truth 数据，可使用 Brieflow 提供的微调模式重新训练分割模型。
- 对于贴壁形态极度不规则的细胞（如成纤维细胞），建议切换至基于深度学习的实例分割模块（如 Cellpose 的 cyto3 模型）并适当降低 flow_threshold。

4.2 条形码匹配率低，大量细胞无法分配到有效 sgRNA¶

解决方案
- 检查条形码通道信噪比，确保 min_signal_to_noise 参数设置合理，并开启 local_background_subtraction=True。
- 适当放宽 max_hamming_distance（例如从1调至2），但需权衡假阳性增加的风险，可后续通过一致性过滤减少错配。
- 验证参考文件 barcode_ref.fasta 是否与实验设计完全一致，注意条形码的方向和碱基偏移。
- 对于原位测序质量较低的批次，可以启用 Brieflow 的概率性匹配模式，该模式会为每个条形码分配置信度分数，后续可依此过滤低可信度分配。

4.3 批次效应校正后仍然存在明显的实验批次分离¶

解决方案
- 增加批次协变量的组合（如 plate_id + well_row + imaging_date）进行联合校正。
- 尝试不同的标准化方法：若 combat_seq 效果不佳，可改用 harmony 或 scanorama（在特征空间中进行批次整合）。
- 检查是否存在隐藏的技术变量，例如成像时的激光强度波动，可在特征提取阶段引入成像顺序作为潜在变量进行回归。
- 对每个批次单独计算阳性对照和阴性对照的一致形态签名，评估校正效率：如果对照样本在校正后仍按批次聚集，说明需要更复杂的非线性校正策略。

4.4 大规模数据运算时内存溢出或速度过慢¶

解决方案
- 启用 Brieflow 的分块处理模式（chunk_size 参数），将全数据集拆分为可管理的块，逐块载入内存。
- 使用 GPU 加速特征提取和分割阶段，确认容器启动时已分配 --gpus all。
- 在 Snakemake 工作流中设置合理的 --cores 和内存资源限制（--resources mem_mb=XXX），利用其并行调度能力同时处理不同视场。
- 针对超大规模实验（>1亿单细胞），可先将原始图像转换为高效的中间格式（如 Zarr/OME-NGFF），并利用 Brieflow 的延迟加载机制（lazy loading）减少物理内存占用。

5. 速查表¶

5.1 主要命令行工具¶

命令	作用
`brieflow init`	初始化项目目录结构，生成配置文件骨架
`brieflow run seg`	仅运行分割步骤（可指定视场范围）
`brieflow run decode`	执行条形码解码与参考序列比对
`brieflow run align`	执行单细胞特征与条形码空间对齐
`brieflow run all`	端到端执行全流程（从图像到报告）
`brieflow subset`	基于元数据条件创建数据子集
`brieflow export`	将标准化后的特征矩阵导出为 AnnData/H5AD 格式

5.2 关键配置参数（config.yaml 片段）¶

segmentation:
  method: "cellpose"            # 可选: cellpose, stardist, deepcell
  model: "cyto3"
  nuclei_channel: "DAPI"
  cell_channel: "Phalloidin"
  min_cell_size: 200
  max_cell_size: 2000
  edge_enhance: True
  use_gpu: True

barcode_decoding:
  method: "MERFISH"             # 可选: MERFISH, seqFISH, in_situ_seq
  channels: ["Cy5", "TexasRed"]
  reference: "/data/barcode_ref.fasta"
  max_hamming_distance: 2
  min_signal_to_noise: 3.0
  local_bg_subtraction: True

alignment:
  spatial_radius: 15
  method: "nearest_neighbor"
  require_unique_mapping: True

normalization:
  method: "combat_seq"          # 可选: combat_seq, scran, sctransform, harmony
  batch_columns: ["plate_id", "imaging_date"]
  regress_out: ["nucleus_area"]

output:
  format: "h5ad"
  export_embeddings: True
  generate_report: True

5.3 核心 Python API 速查¶

函数 / 类	功能
`bf.Experiment(config_path)`	加载实验对象，管理全局参数
`exp.run_segmentation(...)`	执行图像分割
`exp.extract_features(...)`	提取单细胞多通道特征
`exp.decode_barcodes(...)`	从图像中解析条形码序列
`bf.align_features_barcodes(...)`	空间对齐特征与条形码
`bf.quality_control(...)`	过滤低质量细胞与异常值
`bf.normalize(...)`	批次校正与标准化
`bf.phenotype_differential(...)`	扰动-表型差异显著性检验
`bf.generate_report(...)`	生成 HTML/PDF 分析报告

5.4 依赖与兼容性速查¶

组件	推荐版本	备注
Python	3.10+	需安装 brieflow 及对应 PyTorch
CUDA	11.8+	GPU 加速分割与特征提取
Docker / Singularity	20.10+	容器化运行，保证环境一致性
工作流引擎	Snakemake ≥7.0 或 Nextflow ≥22.0	可选，用于大规模并行化
输入图像格式	TIFF, OME-TIFF, Zarr	支持多通道、多视场单文件或分文件格式
单细胞数据格式	AnnData (h5ad), DataFrame (parquet/csv)	与 Scanpy、Seurat 等下游工具互联

通过模块化的设计、丰富的 API 与自动化工作流，Brieflow 显著降低了光池筛选数据分析的技术门槛，让研究者能够专注于生物学问题本身，快速从海量多模态数据中挖掘功能性基因-表型关联。