Signac/R创建ChromatinAssay报Fragment file is not indexed如何解决

报错触发场景 #

执行Signac包CreateChromatinAssay函数创建染色质分析对象时代码如下：

chrom_assay <- CreateChromatinAssay(
   counts = counts,
   sep = c(":", "-"),
   genome = 'mm10', 
   fragments = '../vignette_data/atac_v1_pbmc_10k_fragments.tsv', 
   min.cells = 10,
   min.features = 200
)

运行后抛出报错：

Error in CreateFragmentObject(path = fragments, cells = cells,
validate.fragments = validate.fragments, 
:Fragment file is not indexed.

报错核心原因：Signac要求输入的fragments片段文件必须配套bgzip压缩格式的文件本体+对应tabix索引（.tbi文件），否则无法支持快速随机读取片段信息，未满足要求就会触发该报错。

可用解决方案 #

方案1：R环境内直接用Signac内置函数建索引（最简便） #

依赖Rsamtools包提供的tabix能力，操作步骤：

1. 先安装依赖包（已安装可跳过）：

if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("Rsamtools")

2. 运行索引构建命令：

library(Signac)
# 替换为实际的fragments文件路径
frag_file <- '../vignette_data/atac_v1_pbmc_10k_fragments.tsv'
# 函数会自动完成文件bgzip压缩、tbi索引生成
IndexFragments(fragments = frag_file)

3. 命令执行完成后，同目录下会生成atac_v1_pbmc_10k_fragments.tsv.bgz压缩文件和atac_v1_pbmc_10k_fragments.tsv.bgz.tbi索引文件，将原CreateChromatinAssay中fragments参数替换为.bgz文件的路径即可正常运行。

方案2：命令行工具建索引（适合大文件场景，速度更快） #

如果fragments文件大小超过10G，R中构建索引速度较慢，可使用命令行的htslib工具集处理：

1. 先确保服务器/本地环境已安装htslib（包含bgzip、tabix命令），未安装可通过conda或源码编译安装。
2. 对原始tsv格式fragments文件做bgzip压缩：

bgzip ../vignette_data/atac_v1_pbmc_10k_fragments.tsv

3. 为压缩后的文件构建tabix索引：

# fragments文件为bed格式排序，指定-p bed参数
tabix -p bed ../vignette_data/atac_v1_pbmc_10k_fragments.tsv.gz

4. 执行完成后同目录生成.gz压缩文件和.gz.tbi索引文件，R代码中fragments参数传入.gz文件路径即可。

方案3：临时跳过索引校验（仅适合小样本测试，不推荐正式分析使用） #

如果只是做流程调试、小样本快速测试，可通过添加validate.fragments = FALSE参数跳过索引校验，修改后代码如下：

chrom_assay <- CreateChromatinAssay(
   counts = counts,
   sep = c(":", "-"),
   genome = 'mm10', 
   fragments = '../vignette_data/atac_v1_pbmc_10k_fragments.tsv', 
   min.cells = 10,
   min.features = 200,
   validate.fragments = FALSE
)

注意：未建立索引的fragments文件在后续执行片段读取、peak注释、足迹分析、共开放性计算等操作时，会消耗极长时间读取全文件，大样本下基本无法正常运行，正式分析必须提前构建索引。

内容的提问来源于stack exchange，提问作者dallas_engineer