chromap

<a name="started"></a>快速开始

git clone https://github.com/haowenz/chromap.git
cd chromap && make
# 先创建索引然后再进行比对
./chromap -i -r test/ref.fa -o ref.index
./chromap -x ref.index -r test/ref.fa -1 test/read1.fq -2 test/read2.fq -o test.bed
# 使用预设参数（无测试数据）
./chromap --preset atac -x index -r ref.fa -1 read1.fq -2 read2.fq -o aln.bed       # ATAC-seq测序数据
./chromap --preset atac -x index -r ref.fa -1 read1.fq -2 read2.fq -o aln.bed \
 -b barcode.fq.gz --barcode-whitelist whitelist.txt                                 # scATAC-seq测序数据
./chromap --preset chip -x index -r ref.fa -1 read1.fq -2 read2.fq -o aln.bed       # ChIP-seq测序数据
./chromap --preset hic -x index -r ref.fa -1 read1.fq -2 read2.fq -o aln.pairs      # Hi-C测序数据，输出pairs格式
./chromap --preset hic -x index -r ref.fa -1 read1.fq -2 read2.fq --SAM -o aln.sam  # Hi-C测序数据，输出SAM格式

<a name="uguide"></a>用户指南

Chromap是一种用于比对和预处理高通量染色质测序数据的超快速方法。典型用例包括：(1) 修剪测序接头、将批量ATAC-seq或ChIP-seq基因组读段比对到人类基因组并去除重复序列；(2) 修剪测序接头、将单细胞ATAC-seq基因组读段比对到人类基因组、校正条形码、去除重复序列并进行Tn5位移；(3) 对Hi-C读段进行分割比对。在这三种情况下，Chromap的速度都是其他方法的10-20倍，同时保持准确性。

<a name="install"></a>安装

要从源代码编译，你需要安装GCC编译器（版本>=7.3.0）、GNU make和zlib开发文件。然后在源代码目录中输入make进行编译。

Chromap也可以在[bioconda][bioconda]上获得。因此你可以使用Conda轻松安装Chromap：

conda install -c bioconda -c conda-forge chromap

<a name="general"></a>基本用法

在进行比对之前，需要先创建参考基因组的索引并保存在磁盘上：

chromap -i -r ref.fa -o index

用户可以通过**--min-frag-length**输入测序实验中预期的最小片段长度，例如读长。然后Chromap会选择合适的k-mer长度和窗口大小来构建索引。对于人类基因组，构建索引只需几分钟。在没有任何预设参数的情况下，Chromap以参考数据库和查询序列文件作为输入，生成近似比对结果，不进行碱基级别的比对，输出[BED格式][bed]：

chromap -x index -r ref.fa -1 query.fq -o approx-mapping.bed

你可以要求Chromap以[SAM格式][sam]输出比对结果：

chromap -x index -r ref.fa -1 query.fq --SAM -o alignment.sam

但请注意，SAM文件的处理尚未完全优化，可能会比较慢。因此，不建议生成SAM格式的输出，应尽可能避免。Chromap可以处理多个输入读段文件：

chromap -x index -r ref.fa -1 query1.fq,query2.fq,query3.fq --SAM -o alignment.sam

Chromap还支持读段文件名中的通配符，并会查找所有匹配的读段文件。要使用此功能，读段文件名必须用引号括起来：

chromap -x index -r ref.fa -1 "query*.fq" --SAM -o alignment.sam

Chromap可以处理gzip压缩的FASTA和FASTQ格式的输入文件。你不需要在FASTA和FASTQ之间转换或先解压gzip文件。

重要提示，应该注意的是，一旦构建了索引，比对时就不能更改索引参数，如**-k**、-w和**--min-frag-length**。如果你要为不同类型的数据运行Chromap，可能需要保留使用不同参数生成的多个索引。这使得Chromap与BWA不同，BWA总是使用相同的索引，而不考虑查询数据类型。Chromap可以在几分钟内构建人类基因组的索引文件。

选项的详细说明可以在[手册页][manpage]中找到。

<a name="cases"></a>使用案例

为了支持不同的数据类型（如ChIP-seq、Hi-C、ATAC-seq），需要调整Chromap以获得最佳性能和准确性。通常建议使用**--preset**选项选择预设，这会同时设置多个参数。

<a name="map-chip"></a>比对ChIP-seq短读序列

chromap --preset chip -x index -r ref.fa -1 read1.fq.gz -2 read2.fq.gz -o aln.bed      # ChIP-seq读段

这组参数是为比对ChIP-seq读段而调整的。Chromap将以最大插入大小2000（-l 2000）比对双端读段，然后使用低内存模式（--low-mem）去除PCR重复（--remove-pcr-duplicates）。输出采用BED格式（--BED）。在输出的BED文件中，每行代表一个片段（即一对读段）的比对，列的含义如下：

染色体 染色体起始位置 染色体结束位置 N 比对质量值 链方向

这里的链方向是读段对中第一个读段（由**-1指定）的链方向。如果需要读段对中每个读段的比对起始和结束位置，应该使用--TagAlign来覆盖预设参数中的--BED**，如下所示：

chromap --preset chip -x index -r ref.fa -1 read1.fq.gz -2 read2.fq.gz --TagAlign -o aln.tagAlign      # ChIP-seq读段

对于每个读段对，输出文件中会有两行，分别对应读段对中的每个读段。列的含义保持不变。

<a name="map-atac"></a>比对ATAC-seq/scATAC-seq短读序列

chromap --preset atac -x index -r ref.fa -1 read1.fq.gz -2 read2.fq.gz -o aln.bed      # ATAC-seq读段
chromap --preset atac -x index -r ref.fa -1 read1.fq.gz -2 read2.fq.gz -o aln.bed\
 -b barcode.fq.gz --barcode-whitelist whitelist.txt                                    # scATAC-seq读段

这组参数是为比对ATAC-seq/scATAC-seq读段而调整的。Chromap将修剪3'端的接头（--trim-adapters），以最大插入大小2000（-l 2000）比对双端读段，然后在细胞水平去除PCR重复（--remove-pcr-duplicates-at-cell-level）。还会对片段应用Tn5位移（--Tn5-shift）。正向比对起始位置增加4bp，反向比对结束位置减少5bp。处理过程在低内存模式下运行（--low-mem）。

如果没有提供条形码白名单文件，Chromap将跳过条形码校正。当提供了条形码和白名单作为输入时，默认情况下Chromap会估计条形码丰度，并使用这些信息来校正与白名单条形码相差不超过1个汉明距离的条形码。通过将**--bc-error-threshold设置为2，Chromap能够校正与白名单条形码相差不超过2个汉明距离的条形码。用户还可以通过设置--bc-probability-threshold**（默认为0.9）来增加进行校正的概率阈值，将其设置为更大的值（如0.975）以仅进行可靠的校正。对于具有多个读段和条形码文件的scATAC-seq数据，你可以使用","连接多个输入文件，如上文所示的例子。 Chromap还支持用户自定义条形码格式，包括混合条形码和基因组数据的情况。用户可以通过**--read-format**选项指定序列结构。该值是一个以逗号分隔的字符串，字符串中的每个字段也是一个以分号分隔的字符串

[r1|r2|bc]:起始:结束:链

起始和结束是包含的，-1表示读取的末尾。用户可以使用多个字段来指定不连续的片段，例如bc:0:15,bc:32:-1。链由'+'和'-'符号表示，如果是'-'，条形码在提取后将被反向互补。如果是'+'，可以省略链符号，对r1和r2会被忽略。例如，当条形码在read1的前16bp时，可以使用选项-1 read1.fq.gz -2 read2.fq.gz --barcode read1.fq.gz --read-format bc:0:15,r1:16:-1。

批量数据和单细胞数据的输出文件格式不同，除了前三列。对于批量数据，列为

染色体 染色体起始 染色体结束 N 映射质量 链 重复计数

对于单细胞数据，列为

染色体 染色体起始 染色体结束 条形码 重复计数

与[CellRanger][cellranger]中片段文件的定义相同。注意染色体结束是开放式的。这个输出片段文件可以用作下游分析工具的输入，如[MAESTRO][MAESTRO]、[ArchR][ArchR]、[signac][signac]等。

此外，Chromap可以将输入的细胞条形码转换为另一组条形码。用户可以通过**--barcode-translate**选项指定转换文件。转换文件是一个双列的tsv/csv文件，第一列是转换后的条形码，第二列是原始条形码。这对10x Multiome数据很有用，其中scATAC-seq和scRNA-seq数据使用不同的条形码集。此选项还支持组合条形码，如SHARE-seq。Chromap可以将第二列中提供的每个条形码段转换为第一列中的ID，并在输出中添加"-"来连接这些ID。

<a name="map-hic"></a>映射Hi-C短读取

chromap --preset hic -x index -r ref.fa -1 read1.fa -2 read2.fa -o aln.pairs           # Hi-C读取和对输出

Chromap将对Hi-C读取执行分段比对(--split-alignment)，并以[pairs][pairs]格式输出映射(--pairs)，这在[4DN Hi-C数据处理管道][4DN]中使用。一些Hi-C数据分析管道可能要求读取按特定的染色体顺序排序，而不是索引中的顺序。因此，Chromap提供了**--chr-order选项来指定比对顺序，以及--pairs-natural-chr-order**用于在pairs格式中翻转对。

<a name="help"></a>获取帮助

运行带有**-h**的Chromap可以显示Chromap命令行选项和可选标签的详细描述，也可以在[手册页][manpage]找到。如果您遇到错误或有进一步的问题或请求，可以在[问题页面][issue]提出问题。

<a name="cite"></a>引用Chromap

如果您使用Chromap，请引用：

Zhang, H., Song, L., Wang, X., Cheng, H., Wang, C., Meyer, C. A., ... & Li, H. (2021). Fast alignment and preprocessing of chromatin profiles with Chromap. Nature communications, 12(1), 1-6. https://doi.org/10.1038/s41467-021-26865-w