CRISPR - Correct 技术文档

概述

CRISPR - Correct 是由 Pinello Lab 开发的 Python 工具包，主要用于从原始 FASTQ 文件和向导 RNA（guide RNA）库数据框中进行向导 RNA 映射。其核心功能是通过计算汉明距离将观测到的原型间隔区（protospacer）序列映射到最接近的向导 RNA，特别适用于处理因 SpRY 碱基编辑器自编辑或测序错误导致的非完美映射。此外，该工具支持向导 RNA 传感器构建体和 UMI（唯一分子标识符）的解析，可通过正则表达式从测序读段中提取原型间隔区、替代序列（surrogate）、条形码（barcode）等序列。需注意的是，CRISPR - Correct 无法处理原型间隔区中的插入缺失（indel），此类情况建议使用 Pinello Lab 的另一工具 CRISPR BEAN；若未预期自编辑或测序错误，可选择更简单快速的 CRISPR SURF 工具。

核心功能与特性

非完美映射处理

• 基于汉明距离将观测序列映射到最接近的向导 RNA，有效应对自编辑或测序错误导致的序列不匹配。
• 设定汉明距离阈值，过滤超出阈值的低置信度映射结果。

传感器构建体与 UMI 支持

• 支持解析包含原型间隔区、替代序列、条形码和 UMI 的复杂测序数据。
• 通过正则表达式或位置索引从 FASTQ 读段序列或头部提取目标序列。

高性能与兼容性

• 支持多 CPU 并行计算，提升大规模样本的处理速度。
• 可在 Broad Institute 的 Terra 平台运行，适用于超大规模样本分析（工作流文件位于 Terra Firecloud 仓库）。

使用场景与适用范围

适用场景

• 预期存在 SpRY 碱基编辑器自编辑或显著测序错误，需要进行非完美映射。
• 实验设计包含向导 RNA 传感器构建体，需同时分析原型间隔区和替代序列的编辑结果。
• 需要解析 UMI 或条形码以区分相似序列。

非适用场景

• 无自编辑或测序错误预期：建议使用 CRISPR SURF，操作更简单快速。
• 存在插入缺失（indel）：需使用 CRISPR BEAN。

安装与系统要求

安装

通过 PyPI 安装，命令如下：

bash
pip install crispr - ambiguous - mapping == 0.0.177

系统要求

• Python 版本：≥3.8 且 <3.12。
• 操作系统：支持 Python 3.8 - 3.11 的所有操作系统（如 Windows、macOS、Linux）。
• 硬件建议：
  • 多 CPU 处理器以启用并行计算。
  • 足够的内存以支持映射结果的内存存储（样本越大，需求越高）。
  • 高速磁盘 I/O（如 SSD）可显著提升映射性能。

输入准备

R1 和 R2 解复用 FASTQ 文件

需提供解复用后的 R1（单端或双端）和 R2（双端时）FASTQ 文件。若需处理读段内索引（in - read index），建议先用 UMITools 解析目标序列和索引，再用 BBMap 的 demuxbyname.sh 工具根据头部信息解复用。大规模样本可参考 Terra Firecloud 的预处理流程（pinellolab/CrisprMillipedeGuideDemultiplex）。

条形码与 UMI 正则表达式

若从 FASTQ 头部解析条形码或 UMI，需提供正则表达式。示例如下：

• 读段头部示例：@lh00134:140:225VLGLT3:7:1101:1028:1080_ANGC_GGCA 1:N:0:GAAATAAG+ACGTCCTG
• 条形码正则表达式（提取 "GGCA"）：BARCODE_REGEX = r"_([^_ ]+)[\s+]"
• UMI 正则表达式（提取 "GAAATAAG"）：UMI_REGEX = r":([^+:]{6})(.{2})\+"

向导 RNA 库表格

需提供 TSV 格式的向导 RNA 库文件，包含以下列：

• protospacer（必需）：原型间隔区序列。
• surrogate（可选）：替代序列。
• barcode（可选）：条形码序列。

要求：同一列的所有序列长度必须一致。示例表格：

tsv
protospacer	surrogate	barcode
TGTCGTGAGGTAGCTACGAC	CAGCAATGTCGTGAGGTAGCTACGACTTGTCA	GCTC
AGTCGTAGCTACCTCACGAC	ATGACAAGTCGTAGCTACCTCACGACATTGCT	GTTG
CCTAGTGGTTATTCGATGTC	AGGTTACCTAGTGGTTATTCGATGTCTCAGAA	CGAA

汉明距离阈值

建议根据序列长度设定阈值，例如：

• 原型间隔区长度 20：阈值 7
• 替代序列长度 32：阈值 10
• 条形码长度 4：阈值 2

使用方法

核心函数

主要映射函数为 crispr_ambiguous_mapping.mapping.get_whitelist_reporter_counts_from_fastq，参数说明如下（关键参数）：

使用示例

python
import crispr_ambiguous_mapping
import pandas as pd

# 加载向导 RNA 库
whitelist_guide_reporter_df = pd.read_table("guide_library.tsv")

# 定义条形码和 UMI 正则表达式
barcode_pattern = r"_([^_ ]+)[\s+]"  # 提取条形码
umi_pattern = r":([^+:]{6})(.{2})\+"  # 提取 UMI

# 执行映射
result = crispr_ambiguous_mapping.mapping.get_whitelist_reporter_counts_from_fastq(
    whitelist_guide_reporter_df=whitelist_guide_reporter_df,
    fastq_r1_fn="read1.fastq.gz",
    fastq_r2_fn="read2.fastq.gz",
    # 条形码和 UMI 解析
    barcode_pattern_regex=barcode_pattern,
    umi_pattern_regex=umi_pattern,
    # 原型间隔区解析（R1 读段前 20 个碱基）
    protospacer_start_position=0,
    protospacer_length=20,
    is_protospacer_r1=True,
    revcomp_protospacer=False,
    # 替代序列解析（R2 读段前 32 个碱基，反向互补）
    surrogate_start_position=0,
    surrogate_length=32,
    is_surrogate_r1=False,
    revcomp_surrogate=True,
    # 汉明距离阈值
    protospacer_hamming_threshold_strict=7,
    surrogate_hamming_threshold_strict=10,
    barcode_hamming_threshold_strict=2,
    # 并行核心数
    cores=8
)

结果输出与可视化

映射结果可通过以下方式处理和可视化：

python
# 提取突变谱
mutations_results = crispr_ambiguous_mapping.processing.get_mutation_profile(
    match_set_whitelist_reporter_observed_sequence_counter_series_results,
    whitelist_reporter_df=whitelist_guide_reporter_df
)

# 绘制突变计数直方图
crispr_ambiguous_mapping.visualization.plot_mutation_count_histogram(
    linked_mutation_counters.protospacer_total_mutation_counter,
    filename="protospacer_mutation_histogram.png"
)

# 绘制三核苷酸突变特征
crispr_ambiguous_mapping.visualization.plot_trinucleotide_mutational_signature(
    mutations_results=mutations_results,
    count_attribute_name="ambiguous_accepted_umi_noncollapsed_mutations",
    filename="trinucleotide_signature.png"
)

# 保存结果（pickle 格式）
crispr_ambiguous_mapping.utility.save_or_load_pickle(
    "./", "mapping_result", py_object=result, date_string=""
)

注意事项

• 确保向导 RNA 库中各列（原型间隔区、替代序列、条形码）的序列长度一致。
• 解析序列时，正则表达式与位置索引二选一，无需同时设置。
• 大规模样本建议使用 Terra 平台或高性能服务器，并启用多 CPU 加速。