CRAM format specification (version 3.1)
CRAM 格式规范（版本 3.1）

samtools-devel@lists.sourceforge.net

4 Sep 2024 2024 年 9 月 4 日

Abstract 摘要

The master version of this document can be found at https://github.com/samtools/hts-specs. This printing is version 4127441 from that repository, last modified on the date shown above.
该文档的主版本可以在 https://github.com/samtools/hts-specs 找到。此打印版本为该存储库中的 4127441，最后修改日期如上所示。

license: Apache 2.0 许可证：Apache 2.0

1 Overview 1 概述

This specification describes the CRAM 3.0 and 3.1 formats.
该规范描述了 CRAM 3.0 和 3.1 格式。
CRAM has the following major objectives:
CRAM 具有以下主要目标：

Significantly better lossless compression than BAM
比 BAM 显著更好的无损压缩
Full compatibility with BAM
与 BAM 完全兼容
Effortless transition to CRAM from using BAM files
轻松从使用 BAM 文件过渡到 CRAM
Support for controlled loss of BAM data
对 BAM 数据的受控丢失支持

The first three objectives allow users to take immediate advantage of the CRAM format while offering a smooth transition path from using BAM files. The fourth objective supports the exploration of different lossy compression strategies and provides a framework in which to effect these choices. Please note that the CRAM format does not impose any rules about what data should or should not be preserved. Instead, CRAM supports a wide range of lossless and lossy data preservation strategies enabling users to choose which data should be preserved.
前三个目标使用户能够立即利用 CRAM 格式，同时提供从使用 BAM 文件平滑过渡的路径。第四个目标支持探索不同的有损压缩策略，并提供一个框架以实施这些选择。请注意，CRAM 格式并不对应该保留或不应保留的数据施加任何规则。相反，CRAM 支持广泛的无损和有损数据保留策略，使用户能够选择应保留哪些数据。
Data in CRAM is stored either as CRAM records or using one of the general purpose compressors (gzip, bzip2). CRAM records are compressed using a number of different encoding strategies. For example, bases are reference compressed by encoding base differences rather than storing the bases themselves.

^{1}

CRAM 中的数据存储为 CRAM 记录或使用通用压缩器（gzip，bzip2）。CRAM 记录使用多种不同的编码策略进行压缩。例如，碱基通过编码碱基差异进行参考压缩，而不是存储碱基本身。

^{1}

2 Data types 2 数据类型

CRAM specification uses logical data types and storage data types; logical data types are written as words (e.g. int) while physical data types are written using single letters (e.g. i). The difference between the two is that storage data types define how logical data types are stored in CRAM. Data in CRAM is stored either as bits or bytes. Writing values as bits and bytes is described in detail below.
CRAM 规范使用逻辑数据类型和存储数据类型；逻辑数据类型用单词表示（例如 int），而物理数据类型用单个字母表示（例如 i）。两者之间的区别在于存储数据类型定义了逻辑数据类型在 CRAM 中的存储方式。CRAM 中的数据以位或字节的形式存储。以下将详细描述以位和字节写入值的方式。

2.1 Logical data types
2.1 逻辑数据类型

Byte 字节

Signed byte ( 8 bits).
有符号字节（8 位）。

Integer 整数

Signed 32-bit integer. 签名的 32 位整数。

Long 长

Signed 64 -bit integer.
签名的 64 位整数。

Array 数组

An array of any logical data type: array<type>
任何逻辑数据类型的数组：array

2.2 Writing bits to a bit stream
2.2 将位写入位流

A bit stream consists of a sequence of 1 s and 0 s . The bits are written most significant bit first where new bits are stacked to the right and full bytes on the left are written out. In a bit stream the last byte will be incomplete if less than 8 bits have been written to it. In this case the bits in the last byte are shifted to the left.
位流由一系列的 1 和 0 组成。位是从最重要的位开始书写，新位堆叠在右侧，左侧的完整字节被写出。在位流中，如果最后一个字节写入的位少于 8 位，则该字节将不完整。在这种情况下，最后一个字节中的位将向左移动。

Example of writing to bit stream
写入位流的示例

Let’s consider the following example. The table below shows a sequence of write operations:
让我们考虑以下示例。下表显示了一系列写操作：

Operation order 操作顺序	Buffer state before 缓冲区状态之前	Written bits 书写的位元	Buffer state after 缓冲区状态之后	Issued bytes 发出字节
1	$0 \times 0$	1	$0 \times 1$	-
2	$0 \times 1$	0	$0 \times 2$	-
3	$0 \times 2$	11	$0 \times B$	-
4	$0 \times B$	00000111	$0 \times 7$	$0 \times B 0$

After flushing the above bit stream the following bytes are written:

0 x B 0

0x70. Please note that the last byte was

0 \times 7

before shifting to the left and became

0 x 70

after that:
在刷新上述比特流后，写入以下字节：

0 x B 0

0x70。请注意，最后一个字节在左移之前是

0 \times 7

，左移后变为

0 x 70

：

> echo "obase=16; ibase=2; 00000111" | bc
7
> echo "obase=16; ibase=2; 01110000" | bc
7 0

And the whole bit sequence:
整个比特序列：

echo “obase=2; ibase=16; B070” | bc
1011000001110000
When reading the bits from the bit sequence it must be known that only 12 bits are meaningful and the bit stream should not be read after that.
在读取位序列中的位时，必须知道只有 12 位是有意义的，位流在此之后不应再读取。

Note on writing to bit stream
写入比特流的注意事项

When writing to a bit stream both the value and the number of bits in the value must be known. This is because programming languages normally operate with bytes ( 8 bits ) and to specify which bits are to be written requires a bit-holder, for example an integer, and the number of bits in it. Equally, when reading a value from a bit stream the number of bits must be known in advance. In case of prefix codes (e.g. Huffman) all possible bit combinations are either known in advance or it is possible to calculate how many bits will follow based on the first few bits. Alternatively, two codes can be combined, where the first contains the number of bits to read.
在写入比特流时，必须知道值和该值中的比特数。这是因为编程语言通常以字节（8 位）为单位操作，而要指定要写入哪些比特需要一个比特持有者，例如一个整数，以及其中的比特数。同样，在从比特流中读取值时，必须提前知道比特数。在前缀编码（例如霍夫曼编码）的情况下，所有可能的比特组合要么是提前已知的，要么可以根据前几个比特计算出后面将跟随多少比特。或者，可以组合两个编码，第一个编码包含要读取的比特数。

2.3 Writing bytes to a byte stream
2.3 将字节写入字节流

The interpretation of byte stream is straightforward. CRAM uses little endianness for bytes when applicable and defines the following storage data types:
字节流的解释很简单。CRAM 在适用时使用小端字节序，并定义以下存储数据类型：

Boolean (bool) 布尔值 (bool)

Boolean is written as 1 -byte with

0 x 0

being ‘false’ and 0 x 1 being ‘true’.
布尔值以 1 字节表示，其中

0 x 0

为‘假’，0x1 为‘真’。

Integer (int32) 整数 (int32)

Signed 32-bit integer, written as 4 bytes in little-endian byte order.
签名的 32 位整数，以小端字节顺序写为 4 个字节。

Long (int64) 长整型 (int64)

Signed 64-bit integer, written as 8 bytes in little-endian byte order.
签名的 64 位整数，以小端字节顺序写为 8 个字节。

ITF-8 integer (itf8) ITF-8 整数 (itf8)

This is an alternative way to write an integer value. The idea is similar to UTF-8 encoding and therefore this encoding is called ITF-8 (Integer Transformation Format - 8 bit).
这是一种写整数值的替代方法。这个想法类似于 UTF-8 编码，因此这种编码被称为 ITF-8（整数转换格式 - 8 位）。
The most significant bits of the first byte have special meaning and are called ‘prefix’. These are 0 to 4 true bits followed by a 0 . The number of 1 's denote the number of bytes to follow. To accommodate 32 bits such representation requires 5 bytes with only 4 lower bits used in the last byte 5 .
第一个字节的最高有效位具有特殊含义，称为“前缀”。这些是 0 到 4 个真实位，后面跟着一个 0。1 的数量表示后续字节的数量。为了适应 32 位，这种表示需要 5 个字节，最后一个字节仅使用 4 个低位。

LTF-8 long (ltf8) LTF-8 长 (ltf8)

See ITF-8 for more details. The only difference between ITF-8 and LTF-8 is the number of bytes used to encode a single value. To do so 64 bits are required and this can be done with 9 byte at most with the first byte consisting of just 1 s or 0 xFF value.
请参阅 ITF-8 以获取更多详细信息。ITF-8 和 LTF-8 之间的唯一区别是用于编码单个值的字节数。为此需要 64 位，最多可以使用 9 个字节，第一个字节仅由 1 或 0xFF 值组成。

Array (array<type>) 数组 (array<类型>)

A variable sized array with an explicitly written dimension. Array length is written first as integer (itf8), followed by the elements of the array.
一个具有显式维度的可变大小数组。数组长度首先以整数（itf8）形式写出，随后是数组的元素。
Implicit or fixed-size arrays are also used, written as type [ ] or type [4] (for example). These have no explicit dimension included in the file format and instead rely on the specification itself to document the array size.
隐式或固定大小的数组也被使用，写作类型 [ ] 或类型 [4]（例如）。这些在文件格式中没有包含显式维度，而是依赖于规范本身来记录数组大小。

Encoding 编码

Encoding is a data type that specifies how data series have been compressed. Encodings are defined as encoding<type> where the type is a logical data type as opposed to a storage data type.
编码是一种数据类型，指定数据系列是如何被压缩的。编码被定义为 encoding，其中类型是逻辑数据类型，而不是存储数据类型。
An encoding is written as follows. The first integer (itf8) denotes the codec id and the second integer (itf8) the number of bytes in the following encoding-specific values.
编码如下所示。第一个整数（itf8）表示编解码器 ID，第二个整数（itf8）表示后续编码特定值的字节数。
Subexponential encoding example:
亚指数编码示例：

Value 值	Type 类型	Name 名称
0x7	itf8	codec id 编解码器 ID
0x2	itf8	number of bytes to follow 后续字节数
0x0	itf8	offset 偏移量
0x1	itf8	K parameter K 参数

The first byte "

0 \times 7

" is the codec id.
第一个字节 "

0 \times 7

" 是编解码器 ID。
The next byte " 0 x 2 " denotes the length of the bytes to follow (2).
下一个字节 "0 x 2" 表示后续字节的长度 (2)。
The subexponential encoding has 2 parameters: integer (itf8) offset and integer (itf8) K.
子指数编码有两个参数：整数（itf8）偏移量和整数（itf8）K。
offset

= 0 x 0 = 0

偏移

= 0 x 0 = 0

K = 0 x 1 = 1

Map 地图
A map is a collection of keys and associated values. A map with

N

keys is written as follows:
映射是键及其关联值的集合。具有

N

个键的映射写作如下：

size in bytes 字节大小

key 1 键 1

value 1 值 1

key... 键...

value ... 值 ...

key N 键 N

value N 值 N

Both the size in bytes and the number of keys are written as integer (itf8). Keys and values are written according to their data types and are specific to each map.
字节大小和键的数量都以整数（itf8）形式写入。键和值根据其数据类型进行书写，并且对每个映射都是特定的。

String 字符串

A string is represented as byte arrays using UTF-8 format. Read names, reference sequence names and tag values with type ’

Z

’ are stored as UTF-8.
字符串使用 UTF-8 格式表示为字节数组。读取名称、参考序列名称和类型为 '

Z

' 的标签值存储为 UTF-8。

3 Encodings 3 编码

Encoding is a data structure that captures information about compression details of a data series that are required to uncompress it. This could be a set of constants required to initialize a specific decompression algorithm or statistical properties of a data series or, in case of data series being stored in an external block, the block content id.
编码是一种数据结构，用于捕获关于数据系列压缩细节的信息，这些信息是解压缩所必需的。这可能是一组常量，用于初始化特定的解压缩算法，或者是数据系列的统计属性，或者在数据系列存储在外部块的情况下，块内容的 ID。

Encoding notation is defined as the keyword ‘encoding’ followed by its data type in angular brackets, for example ‘encoding<byte>’ stands for an encoding that operates on a data series of data type ‘byte’.
编码标记被定义为关键字“encoding”后跟其数据类型的尖括号，例如“encoding”表示对数据类型为“byte”的数据系列进行操作的编码。
Encodings may have parameters of different data types, for example the EXTERNAL encoding has only one parameter, integer id of the external block. The following encodings are defined:
编码可能具有不同数据类型的参数，例如 EXTERNAL 编码只有一个参数，即外部块的整数 ID。定义了以下编码：

Codec 编解码器

Parameters 参数

Comment 评论

NULL

none 无

series not preserved 系列未被保留

EXTERNAL

int block content id
int 块内容 id

用于将外部数据块与数据系列关联的块内容标识符

the block content identifier used to

associate external data blocks with

data series

Deprecated (GOLOMB) 已弃用 (GOLOMB)

int offset, int M

Golomb coding 戈隆布编码

HUFFMAN

array<int>, array<int>

coding with int/byte values
使用 int/byte 值进行编码

BYTE_ARRAY_LEN

编码数组长度，编码字节

encoding<int> array length,

encoding<byte> bytes

字节数组的编码与数组长度

coding of byte arrays with array

length

BYTE_ARRAY_STOP

字节停止，整数外部块内容 ID

byte stop, int external block

content id

字节数组的编码与停止值

coding of byte arrays with a stop

value

BETA

int offset, int number of bits
int 偏移量, int 位数

binary coding 二进制编码

SUBEXP

int offset, int K

subexponential coding 亚指数编码

Deprecated (GOLOMB_RICE)
已弃用 (GOLOMB_RICE)

int offset, int

\log_{2} m

Golomb-Rice coding 戈隆布-赖斯编码

GAMMA

int offset

Elias gamma coding 埃利亚斯伽马编码

See section 13 for more detailed descriptions of all the above coding algorithms and their parameters.
请参阅第 13 节以获取上述所有编码算法及其参数的更详细描述。

4 Checksums 4 个校验和

The checksumming is used to ensure data integrity. The following checksumming algorithms are used in CRAM.
校验和用于确保数据完整性。CRAM 中使用了以下校验和算法。

4.1 CRC32

This is a cyclic redundancy checksum 32-bit long with the polynomial 0x04C11DB7. Please refer to ITU-T V. 42 for more details. The value of the CRC32 hash function is written as an integer.
这是一个 32 位长的循环冗余校验，使用多项式 0x04C11DB7。有关更多详细信息，请参阅 ITU-T V. 42。CRC32 哈希函数的值以整数形式表示。

4.2 CRC32 sum 4.2 CRC32 校验和

CRC32 sum is a combination of CRC32 values by summing up all individual CRC32 values modulo

2^{32}

.
CRC32 和是通过对所有单个 CRC32 值进行求和并对

2^{32}

取模得到的 CRC32 值的组合。

5 File structure 5 文件结构

The overall CRAM file structure is described in this section. Please refer to other sections of this document for more detailed information.
本节描述了整体的 CRAM 文件结构。有关更详细的信息，请参阅本文档的其他部分。
A CRAM file consists of a fixed length file definition, followed by a CRAM header container, then zero or more data containers, and finally a special end-of-file container.
CRAM 文件由一个固定长度的文件定义组成，后面是一个 CRAM 头容器，然后是零个或多个数据容器，最后是一个特殊的文件结束容器。

文件定义

File

definition

CRAM 头部容器

CRAM Header

Container

数据容器

Data

Container

\dots

数据容器

Data

Container

CRAM EOF 容器

CRAM EOF

Container

Figure 1: A CRAM file consists of a file definition, followed by a header container, then other containers.
图 1：CRAM 文件由文件定义组成，后面是头部容器，然后是其他容器。
Containers consist of one or more blocks. The first container, called the CRAM header container, is used to store a textual header as described in the SAM specification (see the section 7.1). This container may have additional padding bytes present for purposes of permitting inline rewriting of the SAM header with small changes in size. These padding bytes are undefined, but we recommend filling with nuls. The padding bytes can either be in explicit uncompressed Block structures, or as unallocated extra space where the size of the container is larger than the combined size of blocks held within it.
容器由一个或多个块组成。第一个容器称为 CRAM 头容器，用于存储如 SAM 规范中所述的文本头（参见第 7.1 节）。此容器可能会有额外的填充字节，以便允许对 SAM 头进行小规模的内联重写。这些填充字节是未定义的，但我们建议用零填充。填充字节可以是显式未压缩的块结构，或者是未分配的额外空间，其中容器的大小大于其内部块的总大小。

Figure 2: The the first container holds the CRAM header text.
图 2：第一个容器包含 CRAM 头文本。
Each container starts with a container header structure followed by one or more blocks. The first block in each container is the compression header block giving details of how to decode data in subsequent blocks. Each block starts with a block header structure followed by the block data.
每个容器以一个容器头结构开始，后面跟着一个或多个块。每个容器中的第一个块是压缩头块，提供有关如何解码后续块中数据的详细信息。每个块以一个块头结构开始，后面跟着块数据。

Figure 3: Containers as a series of blocks
图 3：容器作为一系列块
The blocks after the compression header are organised logically into slices. One slice may contain, for example, a contiguous region of alignment data. Slices begin with a slice header block and are followed by one or more data blocks. It is these data blocks which hold the primary bulk of CRAM data. The data blocks are further subdivided into a core data block and one or more external data blocks.
压缩头后的块在逻辑上组织成切片。一个切片可能包含例如一段连续的对齐数据。切片以切片头块开始，后面跟着一个或多个数据块。正是这些数据块保存了 CRAM 数据的主要部分。数据块进一步细分为核心数据块和一个或多个外部数据块。

Figure 4: Slices formed from a series of concatenated blocks
图 4：由一系列连接块形成的切片

6 File definition 6 文件定义

Each CRAM file starts with a fixed length (26 bytes) definition with the following fields:
每个 CRAM 文件以固定长度（26 字节）的定义开始，包含以下字段：

Data type 数据类型	Name 名称	Value 值
byte[4] 字节[4]	format magic number 格式魔数	CRAM (0x43 0x52 0x41 0x4d)
unsigned byte 无符号字节	major format number 主要格式编号	$3 (0 x 3)$
unsigned byte 无符号字节	minor format number 小格式编号	1 (0x1)
byte[20] 字节[20]	file id 文件 ID	CRAM file identifier (e.g. file name or SHA1 checksum) CRAM 文件标识符（例如文件名或 SHA1 校验和）

Valid CRAM major.minor version numbers are as follows:
有效的 CRAM 主版本.次版本号如下：
1.0 The original public CRAM release.
1.0 原始公共 CRAM 版本。
2.0 The first CRAM release implemented in both Java and C; tidied up implementation vs specification differences in 1.0 .
2.0 第一个 CRAM 版本在 Java 和 C 中实现；整理了 1.0 中的实现与规范差异。
2.1 Gained end of file markers; compatible with 2.0.
2.1 获得文件结束标记；与 2.0 兼容。
3.0 Additional compression methods; header and data checksums; improvements for unsorted data.
3.0 额外的压缩方法；头部和数据校验和；对无序数据的改进。
3.1 Additional EXTERNAL compression codecs only.
3.1 仅限额外的外部压缩编解码器。

CRAM 3.0 and 3.1 differ only in the list of compression methods available, so tools that output CRAM 3 without using any 3.1 codecs should write the header to indicate 3.0 in order to permit maximum compatibility.
CRAM 3.0 和 3.1 仅在可用的压缩方法列表上有所不同，因此输出 CRAM 3 而不使用任何 3.1 编解码器的工具应写入头部以指示 3.0，以便允许最大兼容性。

7 Container header structure
7 容器头结构

The file definition is followed by one or more containers with the following header structure where the container content is stored in the ‘blocks’ field:
文件定义后面跟着一个或多个容器，具有以下头部结构，其中容器内容存储在“blocks”字段中：

Data type 数据类型

Name 名称

Value 值

int32

length 长度

该容器中所有块的长度总和（头部和数据）以及任何填充字节（仅限 CRAM 头部容器）；等于容器的总字节长度减去该头部结构的字节长度

the sum of the lengths of all blocks in this container

(headers and data) and any padding bytes (CRAM header

container only); equal to the total byte length of the

container minus the byte length of this header structure

itf8

reference sequence id 参考序列 ID

参考序列标识符或 -1 表示未映射的读取 -2 表示多个参考序列。此容器中的所有切片必须具有与此值匹配的参考序列 ID。

reference sequence identifier or

-1 for unmapped reads

-2 for multiple reference sequences.

All slices in this container must have a reference sequence

id matching this value.

itf8

参考上的起始位置

starting position on the

reference

the alignment start position
对齐起始位置

itf8

alignment span 对齐跨度

the length of the alignment
对齐的长度

itf8

number of records 记录数

number of records in the container
容器中的记录数

ltf8

record counter 记录计数器

1-based sequential index of records in the file/stream.
文件/流中记录的基于 1 的顺序索引。

ltf8

bases 基础

number of read bases
读取碱基数

itf8

number of blocks 块的数量

the total number of blocks in this container
此容器中的块总数

array<itf8>

landmarks 地标

该容器中切片的位置作为从该容器头部末尾的字节偏移量，用于随机访问索引。对于序列数据容器，地标计数必须等于切片计数。由于第一个切片之前的块是压缩头，因此 landmarks[0] 等于压缩头的字节长度。

the locations of slices in this container as byte offsets from

the end of this container header, used for random access

indexing. For sequence data containers, the landmark

count must equal the slice count.

Since the block before the first slice is the compression

header, landmarks[0] is equal to the byte length of the

compression header.

int 整数

crc32

CRC32 hash of the all the preceding bytes in the container.
容器中所有前面字节的 CRC32 哈希。

byte[ 字节[

blocks 区块

The blocks contained within the container.
容器内包含的块。

In the initial CRAM header container, the reference sequence id, starting position on the reference, and alignment span fields must be ignored when reading. The landmarks array is optional for the CRAM header, but if it exists it should point to block offsets instead of slices, with the first block containing the textual header.
在初始的 CRAM 头容器中，读取时必须忽略参考序列 ID、参考上的起始位置和比对跨度字段。地标数组对于 CRAM 头是可选的，但如果存在，它应该指向块偏移而不是切片，第一个块包含文本头。

In data containers specifying unmapped reads or multiple reference sequences (i.e. reference sequence id

< 0

), the starting position on the reference and alignment span fields must be ignored when reading. When writing, it is recommended to set each of these ignored fields to the value 0 .
在数据容器中指定未映射的读取或多个参考序列（即参考序列 ID

< 0

）时，读取时必须忽略参考上的起始位置和比对跨度字段。在写入时，建议将每个被忽略的字段设置为值 0。

The first container in a CRAM file contains a textual header in one or more blocks. See section 8.3 for more details on the layout of data within these blocks and constraints applied to the contents of the SAM header.
CRAM 文件中的第一个容器包含一个或多个块中的文本头。有关这些块内数据布局和对 SAM 头内容施加的约束的更多详细信息，请参见第 8.3 节。

The landmarks field of the container header structure may be used to indicate the offsets of the blocks used in the header container. These may optionally be omitted by specifying an array size of zero.
容器头结构的地标字段可用于指示在头容器中使用的块的偏移量。通过指定数组大小为零，这些可以选择性地省略。

8 Block structure 8 块结构

Containers consist of one or more blocks. Block compression is applied independently and in addition to any encodings used to compress data within the block. The block have the following header structure with the data stored in the ‘block data’ field:
容器由一个或多个块组成。块压缩是独立应用的，并且是对块内数据进行压缩时使用的任何编码的补充。块具有以下头部结构，数据存储在“块数据”字段中：

Data type 数据类型	Name 名称	Value 值
byte 字节	method 方法	the block compression method (and first CRAM version): 块压缩方法（以及第一个 CRAM 版本）：
		0: raw (none)* 0: 原始 (无)*
		1: gzip
		2: bzip2 (v2.0)
		3: lzma (v3.0)
		4: rans4x8 (v3.0)
		5: rans4x16 (v3.1)
		6: adaptive arithmetic coder (v3.1) 6: 自适应算术编码器 (v3.1)
		7: fqzcomp (v3.1)
		8: name tokeniser (v3.1) 8: 名称分词器 (v3.1)
byte 字节	block content type id 区块内容类型 ID	the block content type identifier 块内容类型标识符
itf8	size in bytes* 字节大小*	the block content identifier used to associate external data 用于关联外部数据的块内容标识符
	raw size in bytes* 原始大小（字节）*	blocks with data series 数据系列的块
itf8	block data 块数据	size of the block data after applying block compression 应用块压缩后块数据的大小
itf8		the data stored in the before applying block compression 在应用块压缩之前存储的数据
byte[] 字节[]	・ bit stream of CRAM records (core data block) ・ CRAM 记录的位流（核心数据块）
		$∙$ byte stream (external data block) $∙$ 字节流（外部数据块）
	CRC32	additional fields ( header blocks) 附加字段（头部块）
byte[4] 字节[4]	CRC32 hash value for all preceding bytes in the block 区块中所有前导字节的 CRC32 哈希值

Note on raw method: both compressed and raw sizes must be set to the same value.
关于原始方法的说明：压缩大小和原始大小必须设置为相同的值。

Empty blocks may occur in the files. Blocks with a raw (uncompressed) size of zero are treated as empty, irrespective of their “method” byte. This is equivalent to interpreting them as having method zero (raw) and compressed size of zero.
文件中可能会出现空块。原始（未压缩）大小为零的块被视为空块，无论其“方法”字节是什么。这相当于将它们解释为具有方法零（原始）和压缩大小为零。

8.1 Block content types
8.1 块内容类型

CRAM has the following block content types:
CRAM 具有以下块内容类型：

Block content type 块内容类型

块内容类型 ID

Block

content

type id

Name 名称

Contents 内容

FILE_HEADER

CRAM header block CRAM 头块

CRAM header CRAM 头部

COMPRESSION_HEADER

Compression header block
压缩头块

See specific section 查看特定部分

SLICE_HEADER

^{a}

Slice header block 切片头块

See specific section 查看特定部分

reserved 保留

EXTERNAL_DATA

external data block 外部数据块

由外部编码生成的数据

data produced by

external encodings

CORE_DATA

core data block 核心数据块

所有编码的比特流，除了外部编码

bit stream of all

encodings except for

external encodings

8.2 Block content id
8.2 块内容 ID

Block content id is used to distinguish between external blocks in the same slice. Each external encoding has an id parameter which must be one of the external block content ids. For external blocks the content id is a positive integer. For all other blocks content id should be 0 . Consequently, all external encodings must not use content id less than 1 .
块内容 ID 用于区分同一切片中的外部块。每个外部编码都有一个 id 参数，该参数必须是外部块内容 ID 之一。对于外部块，内容 ID 是一个正整数。对于所有其他块，内容 ID 应为 0。因此，所有外部编码不得使用小于 1 的内容 ID。

Data blocks 数据块

Data is stored in data blocks. There are two types of data blocks: core data blocks and external data blocks. The difference between core and external data blocks is that core data blocks consist of data series that are compressed using bit encodings while the external data blocks are byte compressed. One core data block and any number of external data blocks are associated with each slice.
数据存储在数据块中。数据块有两种类型：核心数据块和外部数据块。核心数据块和外部数据块的区别在于，核心数据块由使用位编码压缩的数据序列组成，而外部数据块则是字节压缩的。每个切片关联一个核心数据块和任意数量的外部数据块。
Writing to and reading from core and external data blocks is organised through CRAM records. Each data series is associated with an encoding. In case of external encodings the block content id is used to identify the block where the data series is stored. Please note that external blocks can have multiple data series associated with them; in this case the values from these data series will be interleaved.
通过 CRAM 记录组织对核心和外部数据块的读写。每个数据系列都与一种编码相关联。在外部编码的情况下，使用块内容 ID 来识别存储数据系列的块。请注意，外部块可以与多个数据系列相关联；在这种情况下，这些数据系列的值将交错。

8.3 CRAM header block(s)
8.3 CRAM 头块

The SAM header is stored in the first block of the CRAM header container (see section 7.1). This block may be uncompressed or gzip compressed only. This block is followed by zero or more uncompressed expansion blocks. If present, these permit in-place editing of the CRAM header, allowing it to grow or shrink with a compensatory size change applied to the subsequence expansion block, avoiding the need to rewrite the remainder of the file. The contents of any expansion blocks should be zero bytes (nul characters).
SAM 头信息存储在 CRAM 头容器的第一个块中（见第 7.1 节）。该块可以是未压缩的或仅 gzip 压缩的。该块后面可以跟零个或多个未压缩的扩展块。如果存在，这些块允许对 CRAM 头进行就地编辑，使其能够随着补偿性大小变化而增长或缩小，避免了重写文件其余部分的需要。任何扩展块的内容应为零字节（空字符）。
The format of the initial SAM header block is a 32-bit little-endian integer holding the length of the text of the SAM header, minus nul-termination bytes, followed by the text itself. Although 32-bit, the maximum permitted value is

2^{31}

, and all lengths must be positive.
初始 SAM 头块的格式是一个 32 位小端整数，表示 SAM 头文本的长度，减去空终止字节，后面是文本本身。尽管是 32 位，允许的最大值是

2^{31}

，所有长度必须为正。
The following constraints apply to the SAM header text:
以下约束适用于 SAM 头文本：

The SQ:MD5 checksum is required unless the reference sequence has been embedded into the file.
SQ:MD5 校验和是必需的，除非参考序列已嵌入文件中。

8.4 Compression header block
8.4 压缩头块

The compression header block consists of 3 parts: preservation map, data series encoding map and tag encoding map.
压缩头块由三个部分组成：保留映射、数据系列编码映射和标签编码映射。

Preservation map 保护地图

The preservation map contains information about which data was preserved in the CRAM file. It is stored as a map with byte[2] keys:
保留映射包含有关在 CRAM 文件中保留了哪些数据的信息。它作为一个具有 byte[2]键的映射存储：

Key 关键

Value data type 值数据类型

Name 名称

Value 值

bool 布尔值

read names included 读取包含的名称

true if read names are preserved for all reads
如果所有读取的名称都被保留，则为真

bool 布尔值

AP data series delta
AP 数据系列增量

true if AP data series is delta, false otherwise
如果 AP 数据系列是增量，则为 true，否则为 false

bool 布尔值

reference required 参考要求

如果需要参考序列以完全恢复数据，则为真

true if reference sequence is required to restore

the data completely

byte[5] 字节[5]

substitution matrix 替代矩阵

array<byte> 字节数组

tag ids dictionary 标签 ID 字典

a list of lists of tag ids, see tag encoding section
标签 ID 的列表列表，请参见标签编码部分

The boolean values are optional, defaulting to true when absent, although it is recommended to explicitly set them. SM and TD are mandatory.
布尔值是可选的，缺省为 true，尽管建议明确设置它们。SM 和 TD 是必需的。

Data series encodings 数据系列编码

Each data series has an encoding. These encoding are stored in a map with byte[2] keys and are decoded in approximately this order

^{2}

:
每个数据系列都有一个编码。这些编码存储在一个以 byte[2] 为键的映射中，并大致按照以下顺序解码

^{2}

：

Key 关键

Value data type 值数据类型

Name 名称

Value 值

encoding<int> 编码

BAM bit flags BAM 位标志

see separate section 请参见单独部分

encoding<int> 编码

CRAM bit flags CRAM 位标志

see specific section 查看特定部分

encoding<int> 编码

reference id 参考 ID

record reference id from the SAM file header
从 SAM 文件头中记录参考 ID

encoding<int> 编码

read lengths 读取长度

encoding<int> 编码

in-seq positions 序列中的位置

如果 AP-Delta = true：基于 0 的对齐开始增量来自于前一记录中的 AP 值。请注意，这个增量可能是负数，例如在多参考切片中切换参考时。当记录是切片中的第一个时，使用的前一个位置是切片对齐开始字段（因此对于单参考切片，第一个增量应该为零，对于多参考切片，应该是 AP 值本身）。如果 AP-Delta = false：直接编码对齐开始位置。

if AP-Delta = true: 0-based alignment start

delta from the AP value in the previous record.

Note this delta may be negative, for example

when switching references in a multi-reference

slice. When the record is the first in the slice, the

previous position used is the slice alignment-start

field (hence the first delta should be zero for

single-reference slices, or the AP value itself for

multi-reference slices).

if AP-Delta = false: encodes the alignment start

position directly

encoding<int> 编码

read groups 阅读组

读取组。特殊值 '-1' 表示没有组。

read groups. Special value ' -1 ' stands for no

group.

{RN}^{a}

encoding<byte[ ]> 编码

read names 读取名称

encoding<int> 编码

next mate bit flags
下一个伙伴位标志

see specific section 查看特定部分

encoding<int> 编码

下一个片段参考序列 ID

next fragment

reference sequence id

reference sequence ids for the next fragment
下一个片段的参考序列 ID

encoding<int> 编码

下一个配对对齐开始

next mate alignment

start

alignment positions for the next fragment
下一个片段的对齐位置

encoding<int> 编码

template size 模板大小

template sizes 模板大小

encoding<int> 编码

到下一个片段的距离

distance to next

fragment

number of records to skip to the next fragment

^{b}

跳过到下一个片段的记录数

^{b}

{TL}^{C}

encoding<int> 编码

tag ids 标签 ID

list of tag ids, see tag encoding section
标签 ID 列表，请参见标签编码部分

encoding<int> 编码

读取特征的数量

number of read

features

number of read features in each record
每条记录中读取特征的数量

encoding<byte> 编码

read features codes 阅读功能代码

see separate section 请参见单独部分

encoding<int> 编码

in-read positions 阅读中的位置

读取特征的位置；相对于最后一个位置的正增量（从零开始）

positions of the read features; a positive delta to

the last position (starting with zero)

encoding<int> 编码

deletion lengths 删除长度

base-pair deletion lengths
碱基对缺失长度

encoding<byte[]> 编码

stretches of bases 基础的延伸

bases 基础

encoding<byte[ ]> 编码

质量分数的区间

stretches of quality

scores

quality scores 质量分数

encoding<byte> 编码

碱基替代编码

base substitution

codes

base substitution codes 碱基替代编码

encoding<byte[]> 编码

insertion 插入

inserted bases 插入的碱基

encoding<int> 编码

reference skip length 参考跳过长度

number of skipped bases for the ' N ' read feature
'N'读取特征的跳过碱基数量

encoding<int> 编码

padding 填充

number of padded bases
填充碱基的数量

encoding<int> 编码

hard clip 硬剪辑

number of hard clipped bases
硬剪切碱基的数量

encoding<byte[ ]> 编码

soft clip 软剪辑

soft clipped bases 软剪切碱基

encoding<int> 编码

mapping qualities 映射质量

mapping quality scores 映射质量分数

encoding<byte> 编码

bases 基础

encoding<byte> 编码

quality scores 质量分数

{TC}^{d}

N/A 不适用

legacy field 遗留字段

to be ignored 被忽略

{TN}^{d}

N/A 不适用

legacy field 遗留字段

to be ignored 被忽略

Key Value data type Name Value BF encoding<int> BAM bit flags see separate section CF encoding<int> CRAM bit flags see specific section RI encoding<int> reference id record reference id from the SAM file header RL encoding<int> read lengths read lengths AP encoding<int> in-seq positions "if AP-Delta = true: 0-based alignment start delta from the AP value in the previous record. Note this delta may be negative, for example when switching references in a multi-reference slice. When the record is the first in the slice, the previous position used is the slice alignment-start field (hence the first delta should be zero for single-reference slices, or the AP value itself for multi-reference slices). if AP-Delta = false: encodes the alignment start position directly" RG encoding<int> read groups "read groups. Special value ' -1 ' stands for no group." RN^(a) encoding<byte[ ]> read names read names MF encoding<int> next mate bit flags see specific section NS encoding<int> "next fragment reference sequence id" reference sequence ids for the next fragment NP encoding<int> "next mate alignment start" alignment positions for the next fragment TS encoding<int> template size template sizes NF encoding<int> "distance to next fragment" number of records to skip to the next fragment ^(b) TL^(C) encoding<int> tag ids list of tag ids, see tag encoding section FN encoding<int> "number of read features" number of read features in each record FC encoding<byte> read features codes see separate section FP encoding<int> in-read positions "positions of the read features; a positive delta to the last position (starting with zero)" DL encoding<int> deletion lengths base-pair deletion lengths BB encoding<byte[]> stretches of bases bases QQ encoding<byte[ ]> "stretches of quality scores" quality scores BS encoding<byte> "base substitution codes" base substitution codes IN encoding<byte[]> insertion inserted bases RS encoding<int> reference skip length number of skipped bases for the ' N ' read feature PD encoding<int> padding number of padded bases HC encoding<int> hard clip number of hard clipped bases SC encoding<byte[ ]> soft clip soft clipped bases MQ encoding<int> mapping qualities mapping quality scores BA encoding<byte> bases bases QS encoding<byte> quality scores quality scores TC^(d) N/A legacy field to be ignored TN^(d) N/A legacy field to be ignored

| Key | Value data type | Name | Value | | :---: | :---: | :---: | :---: | | BF | encoding<int> | BAM bit flags | see separate section | | CF | encoding<int> | CRAM bit flags | see specific section | | RI | encoding<int> | reference id | record reference id from the SAM file header | | RL | encoding<int> | read lengths | read lengths | | AP | encoding<int> | in-seq positions | if AP-Delta = true: 0-based alignment start delta from the AP value in the previous record. Note this delta may be negative, for example when switching references in a multi-reference slice. When the record is the first in the slice, the previous position used is the slice alignment-start field (hence the first delta should be zero for single-reference slices, or the AP value itself for multi-reference slices). if AP-Delta = false: encodes the alignment start position directly | | RG | encoding<int> | read groups | read groups. Special value ' -1 ' stands for no group. | | $\mathrm{RN}^{\mathrm{a}}$ | encoding<byte[ ]> | read names | read names | | MF | encoding<int> | next mate bit flags | see specific section | | NS | encoding<int> | next fragment reference sequence id | reference sequence ids for the next fragment | | NP | encoding<int> | next mate alignment start | alignment positions for the next fragment | | TS | encoding<int> | template size | template sizes | | NF | encoding<int> | distance to next fragment | number of records to skip to the next fragment ${ }^{b}$ | | $\mathrm{TL}^{\mathrm{C}}$ | encoding<int> | tag ids | list of tag ids, see tag encoding section | | FN | encoding<int> | number of read features | number of read features in each record | | FC | encoding<byte> | read features codes | see separate section | | FP | encoding<int> | in-read positions | positions of the read features; a positive delta to the last position (starting with zero) | | DL | encoding<int> | deletion lengths | base-pair deletion lengths | | BB | encoding<byte[]> | stretches of bases | bases | | QQ | encoding<byte[ ]> | stretches of quality scores | quality scores | | BS | encoding<byte> | base substitution codes | base substitution codes | | IN | encoding<byte[]> | insertion | inserted bases | | RS | encoding<int> | reference skip length | number of skipped bases for the ' N ' read feature | | PD | encoding<int> | padding | number of padded bases | | HC | encoding<int> | hard clip | number of hard clipped bases | | SC | encoding<byte[ ]> | soft clip | soft clipped bases | | MQ | encoding<int> | mapping qualities | mapping quality scores | | BA | encoding<byte> | bases | bases | | QS | encoding<byte> | quality scores | quality scores | | $\mathrm{TC}^{\mathrm{d}}$ | N/A | legacy field | to be ignored | | $\mathrm{TN}^{\mathrm{d}}$ | N/A | legacy field | to be ignored |

^{a}

Note RN this is decoded after MF if the record is detached from the mate and we are attempting to auto-generate read names.

^{a}

注意 RN 这是在 MF 之后解码的，如果记录与配对分离，并且我们正在尝试自动生成读取名称。

^{b}

The count is reset for each slice so NF can only refer to a record later within this slice.

^{b}

计数在每个切片中重置，因此 NF 只能在该切片内引用后面的记录。

^{c}

TL is followed by decoding the tag values themselves, in order of appearance in the tag dictionary.

^{c}

TL 后面是按标签字典中出现的顺序解码标签值。

^{d} TC

and TN are legacy data series from CRAM 1.0. They have no function in CRAM 3.0 and should not be present. However some implementations do output them and decoders must silently skip these fields. It is illegal for TC and TN to contain any data values, although there may be empty blocks associated with them.

^{d} TC

和 TN 是来自 CRAM 1.0 的遗留数据系列。它们在 CRAM 3.0 中没有功能，不应存在。然而，一些实现确实输出它们，解码器必须默默跳过这些字段。TC 和 TN 包含任何数据值是非法的，尽管可能与它们相关联的块是空的。

Tag encodings 标签编码

The tag dictionary (TD) describes the unique combinations of tag id / type that occur on each alignment record. For example if we search the id / types present in each record and find only two combinations - X1:i BC:Z SA:Z: and X1:i: BC:Z - then we have two dictionary entries in the TD map.
标签字典（TD）描述了每个比对记录中出现的标签 ID / 类型的唯一组合。例如，如果我们搜索每个记录中存在的 ID / 类型，并且只找到两个组合 - X1:i BC:Z SA:Z: 和 X1:i: BC:Z - 那么我们在 TD 映射中就有两个字典条目。
Let

L_{i} = {T_{i 0}, T_{i 1}, \dots, T_{i x}}

be a list of all tag ids for a record

R_{i}

, where

i

is the sequential record index and

T_{i j}

denotes

j

-th tag id in the record. The list of unique

L_{i}

is stored as the TD value in the preservation map. Maintaining the order is not a requirement for encoders (hence “combinations”), but it is permissible and thus different permutations, each encoded with their own elements in TD, should be supported by the decoder. Each

L_{i}

element in TD is assigned a sequential integer number starting with 0 . These integer numbers are referred to by the TL data series. Using TD, an integer from the TL data series can be mapped back into a list of tag ids. Thus per alignment record we only need to store tag values and not their ids and types.
让

L_{i} = {T_{i 0}, T_{i 1}, \dots, T_{i x}}

成为记录

R_{i}

的所有标签 ID 的列表，其中

i

是顺序记录索引，

T_{i j}

表示记录中的第

j

个标签 ID。唯一的

L_{i}

列表作为保留映射中的 TD 值存储。保持顺序对编码器不是必需的（因此称为“组合”），但这是允许的，因此应该支持不同的排列，每个排列在 TD 中用其自己的元素进行编码。TD 中的每个

L_{i}

元素都分配一个从 0 开始的顺序整数。这些整数通过 TL 数据系列进行引用。使用 TD，可以将 TL 数据系列中的一个整数映射回标签 ID 列表。因此，对于每个对齐记录，我们只需要存储标签值，而不需要存储它们的 ID 和类型。
The TD is written as a byte array consisting of

L_{i}

values separated with

∖ 0

. Each

L_{i}

value is written as a concatenation of 3 byte

T_{i j}

elements: tag id followed by BAM tag type code (one of A, c, C, s, S, i, I, f, Z, H or B , as described in the SAM specification). For example the TD for tag lists X1:i BC:Z SA:Z and X1:i BC:Z may be encoded as X1CBCZSAZ

∖ 0 X 1 CBCZ ∖ 0

, with X 1 C indicating a 1 byte unsigned value for tag X 1 .
TD 被写成一个字节数组，由

L_{i}

值用

∖ 0

分隔。每个

L_{i}

值被写成 3 个字节

T_{i j}

元素的连接：标签 ID 后跟 BAM 标签类型代码（在 SAM 规范中描述的 A、c、C、s、S、i、I、f、Z、H 或 B 之一）。例如，标签列表 X1:i BC:Z SA:Z 和 X1:i BC:Z 的 TD 可以编码为 X1CBCZSAZ

∖ 0 X 1 CBCZ ∖ 0

，其中 X1C 表示标签 X1 的 1 字节无符号值。

Tag values 标签值

The encodings used for different tags are stored in a map. The key is 3 bytes formed from the BAM tag id and type code, matching the TD dictionary described above. Unlike the Data Series Encoding Map, the key is stored in the map as an ITF8 encoded integer, constructed using (char

1 << 16) + (

char

2 << 8) +

type. For example, the 3 -byte representation of OQ:Z is

{0 x 4 F, 0 x 51, 0 \times 5 A}

and these bytes are interpreted as the integer key 0 x 004 F 515 A , leading to an ITF8 byte stream

{0 xE 0, 0 x 4 F, 0 x 51, 0 x 5 A}

.
不同标签使用的编码存储在一个映射中。键是由 BAM 标签 ID 和类型代码形成的 3 个字节，与上述描述的 TD 字典匹配。与数据系列编码映射不同，键以 ITF8 编码的整数形式存储在映射中，构造方式为（char

1 << 16) + (

char

2 << 8) +

type。例如，OQ:Z 的 3 字节表示为

{0 x 4 F, 0 x 51, 0 \times 5 A}

，这些字节被解释为整数键 0 x 004 F 515 A，导致 ITF8 字节流

{0 xE 0, 0 x 4 F, 0 x 51, 0 x 5 A}

。

Key 关键

Value data type 值数据类型

Name 名称

Value 值

TAG ID 1:TAG TYPE 1
标签 ID 1：标签类型 1

encoding<byte[ ]> 编码

read tag 1 读取标签 1

标签值（名称和类型在数据系列代码中可用）

tag values (names and types are

available in the data series code)

\dots

\dots

\dots

TAG ID N:TAG TYPE N
标签 ID N:标签类型 N

encoding<byte[]> 编码

read tag N 读取标签 N

\dots

Note that tag values are encoded as array of bytes. The routines to convert tag values into byte array and back are the same as in BAM with the exception of value type being captured in the tag key rather in the value. Hence consuming 1 byte for types ’ C ’ and ’ c ', 2 bytes for types ’ S ’ and ’ s ', 4 bytes for types ’ I ', ’ i ’ and ’ f ', and a variable number of bytes for types ’

H

', ’

Z

’ and ’

B

'.
请注意，标签值被编码为字节数组。将标签值转换为字节数组及其反向转换的例程与 BAM 中的相同，唯一的区别是值类型被捕获在标签键中而不是值中。因此，类型 'C' 和 'c' 消耗 1 个字节，类型 'S' 和 's' 消耗 2 个字节，类型 'I'、'i' 和 'f' 消耗 4 个字节，而类型 '

H

'、'

Z

' 和 '

B

' 消耗可变数量的字节。

8.5 Slice header block
8.5 切片头块

The slice header block is never compressed (block method=raw). For reference mapped reads the slice header also defines the reference sequence context of the data blocks associated with the slice. Mapped reads can be stored along with placed unmapped

^{3}

reads on the same reference within the same slice.
切片头块从不压缩（块方法=原始）。对于参考映射读取，切片头还定义了与切片相关的数据块的参考序列上下文。映射读取可以与放置的未映射

^{3}

读取存储在同一切片中的同一参考上。
Slices with the Multiple Reference flag ( -2 ) set as the sequence ID in the header may contain reads mapped to multiple external references, including unmapped

^{3}

reads (placed on these references or unplaced), but multiple embedded references cannot be combined in this way. When multiple references are used, the RI data series will be used to determine the reference sequence ID for each record. This data series is not present when only a single reference is used within a slice.
带有多个参考标志（-2）设置为头部中的序列 ID 的切片可能包含映射到多个外部参考的读取，包括未映射的

^{3}

读取（放置在这些参考上或未放置），但无法以这种方式组合多个嵌入的参考。当使用多个参考时，将使用 RI 数据系列来确定每个记录的参考序列 ID。当切片中仅使用单个参考时，此数据系列不存在。

The Unmapped (-1) sequence ID in the header is for slices containing only unplaced unmapped

^{3}

reads.
头部中的未映射 (-1) 序列 ID 用于仅包含未放置的未映射

^{3}

读取的切片。
A slice containing data that does not use the external reference in any sequence may set the reference MD5 sum to zero. This can happen because the data is unmapped or the sequence has been stored verbatim instead of via reference-differencing. This latter scenario is recommended for unsorted or non-coordinate-sorted data.
一个包含不在任何序列中使用外部引用的数据切片可以将引用的 MD5 和设置为零。这可能是因为数据未映射或序列已逐字存储，而不是通过引用差异化。对于未排序或非坐标排序的数据，推荐使用后一种情况。

The slice header block contains the following fields.
切片头块包含以下字段。

Data type 数据类型

Name 名称

Value 值

itf8

reference sequence id 参考序列 ID

参考序列标识符或 -1 表示未映射的读取 -2 表示多个参考序列。此值必须与其封闭容器的值匹配。

reference sequence identifier or

-1 for unmapped reads

-2 for multiple reference sequences.

This value must match that of its enclosing

container.

itf8

alignment start 对齐开始

the alignment start position
对齐起始位置

itf8

alignment span 对齐跨度

the length of the alignment
对齐的长度

itf8

number of records 记录数

the number of records in the slice
切片中的记录数

ltf8

record counter 记录计数器

文件/流中记录的基于 1 的顺序索引

1-based sequential index of records in the

file/stream

itf8

number of blocks 块的数量

the number of blocks in the slice
切片中的块数

itf8[]

embedded reference bases block content id
嵌入式参考基块内容 ID

块内容的 ID，切片中块的内容 ID，用于嵌入引用序列的碱基，或 -1 表示无

block content ids of the blocks in the slice

block content id for the embedded reference

sequence bases or -1 for none

itf8

reference md5 参考 md5

切片边界内参考基因组的 MD5 校验和。如果该切片的参考序列 ID 为-1（未映射）或-2（多参考），则 MD5 应为 16 个字节的

∖ 0

。对于嵌入的参考，MD5 可以是全零或嵌入序列的 MD5。

MD5 checksum of the reference bases within

the slice boundaries. If this slice has

reference sequence id of -1 (unmapped) or -2

(multi-ref) the MD5 should be 16 bytes of

∖ 0

For embedded references, the MD5 can either

be all-zeros or the MD5 of the embedded

sequence.

byte[16] 字节[16]

一系列根据 BAM 辅助字段编码的标签、类型、值元组。

a series of tag,type,value tuples encoded as

per BAM auxiliary fields.

byte[] 字节[]

optional tags 可选标签

The alignment start and alignment span values should only be utilised during decoding if the slice has mapped data aligned to a single reference (reference sequence id

>= 0

). For multi-reference slices or those with unmapped data, it is recommended to fill these fields with value 0.
对齐开始和对齐跨度值仅在解码时使用，如果切片已映射数据对齐到单个参考（参考序列 ID

>= 0

）。对于多参考切片或那些具有未映射数据的切片，建议将这些字段填充为值 0。

MD5sums should not be validated if the stored checksum is all-zero. Embedded references should follow the same capitalisation and alphabetical rules as applied to external references prior to MD5sum calculations. If an embedded reference is used, it is not a requirement that it exactly matches the reference used for sequence alignments. For example, it may contain “N” bases where coverage is absent or it could have different base calls for SNP variants. Hence when embedded sequences are used, the MD5sum refers to the checksum of the embedded sequence and should not be validated against any external reference files.
MD5 校验和不应在存储的校验和全为零时进行验证。嵌入的引用应遵循与 MD5 校验和计算之前对外部引用应用的相同大小写和字母顺序规则。如果使用了嵌入引用，并不要求它与用于序列比对的引用完全匹配。例如，它可能包含在覆盖缺失时的“N”碱基，或者对于 SNP 变异可能有不同的碱基调用。因此，当使用嵌入序列时，MD5 校验和指的是嵌入序列的校验和，不应与任何外部参考文件进行验证。
Note where an embedded reference differs to the original reference used for alignment, the MD and NM tags may need to be stored verbatim for records where the respective embedded and external reference substrings differ.
注意嵌入引用与用于对齐的原始引用之间的差异，MD 和 NM 标签可能需要逐字存储，以便在嵌入和外部引用子字符串不同的记录中使用。

The optional tags are encoded in the same manner as BAM tags. I.e. a series of binary encoded tags concatenated together where each tag consists of a 2 byte key (matching [A-Za-z][A-Za-z0-9]) followed by a 1 byte type ([AfZHcCsSiIB]) followed by a string of bytes in a format defined by the type.
可选标签的编码方式与 BAM 标签相同。即一系列二进制编码的标签连接在一起，每个标签由一个 2 字节的键（匹配[A-Za-z][A-Za-z0-9]）后跟一个 1 字节的类型（[AfZHcCsSiIB]），然后是由类型定义格式的字节字符串。
Tags starting in a capital letter are reserved while lowercase ones or those starting with

X, Y

or Z are user definable. Any tag not understood by a decoder should be skipped over without producing an error.
以大写字母开头的标签是保留的，而小写字母开头的标签或以

X, Y

或 Z 开头的标签是用户可定义的。任何解码器无法理解的标签应被跳过，而不产生错误。
At present no tags are defined.
目前没有定义任何标签。

8.6 Core data block
8.6 核心数据块

A core data block is a bit stream (most significant bit first) consisting of data from one or more CRAM records. Please note that one byte could hold more then one CRAM record as a minimal CRAM record could be just a few bits long. The core data block has the following fields:
核心数据块是一个比特流（最高有效位优先），由一个或多个 CRAM 记录的数据组成。请注意，一个字节可以容纳多个 CRAM 记录，因为最小的 CRAM 记录可能只有几位长。核心数据块具有以下字段：

Data type 数据类型	Name 名称	Value 值
bit[ ] 位[ ]	CRAM record 1 CRAM 记录 1	The first CRAM record 第一个 CRAM 记录
$\dots$	$\dots$	$\dots$
bit[ ] 位[ ]	CRAM record N CRAM 记录 N	The Nth CRAM record 第 N 个 CRAM 记录

8.7 External data blocks
8.7 外部数据块

The relationship between the core data block and external data blocks is shown in the following picture:
核心数据块与外部数据块之间的关系如下面的图片所示：

Figure 5: The relationship between core and external encodings, and core and external data blocks.
图 5：核心编码与外部编码之间的关系，以及核心数据块与外部数据块之间的关系。
The picture shows how a CRAM record (on the left) is distributed between the core data block and one or more external data blocks, via core or external encodings. The specific encodings presented are only examples for purposes of illustration. The main point is to distinguish between core bit encodings whose output is always stored in a core data block, and external byte encodings whose output is always stored in external data blocks.
图片显示了一个 CRAM 记录（左侧）是如何通过核心或外部编码在核心数据块和一个或多个外部数据块之间分配的。所呈现的具体编码仅为示例，旨在说明。主要目的是区分核心位编码，其输出始终存储在核心数据块中，以及外部字节编码，其输出始终存储在外部数据块中。

9 End of file container
9 文件结束容器

A special container is used to mark the end of a file or stream. It is required in version 3 or later. The idea is to provide an easy and a quick way to detect that a CRAM file or stream is complete. The marker is basically an empty container with ref seq id set to -1 (unaligned) and alignment start set to 4542278.
一个特殊的容器用于标记文件或流的结束。它在版本 3 或更高版本中是必需的。这个想法是提供一种简单快捷的方法来检测 CRAM 文件或流是否完整。该标记基本上是一个空容器，参考序列 ID 设置为-1（未对齐），对齐起始位置设置为 4542278。
Here is a complete content of the EOF container explained in detail:
这里是 EOF 容器的完整内容，详细解释如下：

hex bytes 十六进制字节	data type 数据类型	decimal value 十进制值	field name 字段名称
Container header 容器头部
Of 000000 000000 的	integer 整数	15	size of blocks data 块数据的大小
ff ff ff ff of ff ff ff ff 的	itf8	-1	ref seq id 参考序列 ID
e0 45 4f 46	itf8	4542278	alignment start 对齐开始
00	itf8	0	alignment span 对齐跨度
00	itf8	0	number of records 记录数
00	itf8	0	global record counter 全局记录计数器
00	itf8	0	bases 基础
01	itf8	1	block count 块计数
00	array 数组	0	landmarks 地标
05 bd d 94 f	integer 整数	1339669765	container header CRC32 容器头 CRC32
Compression header block 压缩头块
00	byte 字节	0 (RAW) 0 (原始)	compression method 压缩方法
01	byte 字节	1 (COMPRESSION_HEADER) 1 (压缩头)	block content type 块内容类型
00	itf8	0	block content id 块内容 ID
06	itf8	6	compressed size 压缩大小
06	itf8	6	uncompressed size 未压缩大小
Compression header 压缩头部
01	itf8	1	preservation map byte size 保留映射字节大小
00	itf8	0	preservation map size 保留地图大小
01	itf8	1	encoding map byte size 编码映射字节大小
00	itf8	0	encoding map size 编码映射大小
01	itf8	1	tag encoding byte size 标签编码字节大小
00	itf8	0	tag encoding map size 标签编码映射大小
ee 63014 b	integer 整数	1258382318	block CRC32 块 CRC32

When compiled together the EOF marker is 38 bytes long and in hex representation is: Of 000000 ff ff ff ff of e0 454 f 4600000000010005 bd d9 4f 0001000606010001000100 ee 6301 4b
当编译在一起时，EOF 标记长度为 38 字节，十六进制表示为：Of 000000 ff ff ff ff of e0 454 f 4600000000010005 bd d9 4f 0001000606010001000100 ee 6301 4b

10 Record structure 10 记录结构

CRAM record is based on the SAM record but has additional features allowing for more efficient data storage. In contrast to BAM record CRAM record uses bits as well as bytes for data storage. This way, for example, various coding techniques which output variable length binary codes can be used directly in CRAM. On the other hand, data series that do not require binary coding can be stored separately in external blocks with some other compression applied to them independently.
CRAM 记录基于 SAM 记录，但具有额外的功能，允许更高效的数据存储。与 BAM 记录相比，CRAM 记录使用位和字节进行数据存储。这样，例如，可以直接在 CRAM 中使用输出可变长度二进制代码的各种编码技术。另一方面，不需要二进制编码的数据序列可以单独存储在外部块中，并对它们应用其他压缩。
As CRAM data series may be interleaved within the same blocks

^{4}

understanding the order in which CRAM data series must be decoded is vital.
由于 CRAM 数据系列可能在同一块内交错

^{4}

，理解 CRAM 数据系列必须解码的顺序至关重要。

The overall flowchart is below, with more detailed description in the subsequent sections.
整体流程图如下，后续部分有更详细的描述。

10.1 CRAM record 10.1 CRAM 记录

Both mapped and unmapped reads start with the following fields. Please note that the data series type refers to the logical data type and the data series name corresponds to the data series encoding map.
映射和未映射的读取都以以下字段开始。请注意，数据系列类型指的是逻辑数据类型，而数据系列名称对应于数据系列编码映射。

数据系列类型

Data series

type

数据系列名称

Data series

name

Field 字段

Description 描述

int 整数

BAM bit flags BAM 位标志

see BAM bit flags below
请参见下面的 BAM 位标志

int 整数

CRAM bit flags CRAM 位标志

see CRAM bit flags below
请参见下面的 CRAM 位标志

Positional data 位置信息

See section 10.2 请参见第 10.2 节

Read names 读取名称

See section 10.3 请参见第 10.3 节

Mate records 配对记录

See section 10.4 请参见第 10.4 节

Auxiliary tags 辅助标签

See section 10.5 请参见第 10.5 节

Sequences 序列

See sections 10.6 and 10.7
请参见第 10.6 节和第 10.7 节

BAM bit flags (BF data series)
BAM 位标志 (BF 数据系列)

The following flags are duplicated from the SAM and BAM specification, with identical meaning. Note however some of these flags can be derived during decode, so may be omitted in the CRAM file and the bits computed based on both reads of a pair-end library residing within the same slice.
以下标志是从 SAM 和 BAM 规范中复制的，具有相同的含义。然而，请注意，其中一些标志可以在解码过程中推导出来，因此可能在 CRAM 文件中被省略，并且基于同一切片内的成对文库的两个读取计算位。

Bit flag 位标志

Comment 评论

Description 描述

0x1

模板具有多个序列段

template having multiple

segments in sequencing

0x2

每个段落根据对齐器正确对齐

each segment properly aligned

according to the aligner

0x4

segment unmapped

^{a}

段未映射

^{a}

0x8

计算

^{b}

或存储在 themate 的信息中

calculated

^{b}

or stored in the

mate's info

下一个段落在模板中未映射

next segment in template

unmapped

0x10

SEQ 被反向互补

SEQ being reverse

complemented

0 \times 20

计算

^{b}

或存储在 themate 的信息中

calculated

^{b}

or stored in the

mate's info

模板中下一个片段的 SEQ 被反向互补

SEQ of the next segment in the

template being reverse

complemented

0x40

the first segment in the template

^{c}

模板中的第一个部分

^{c}

0x80

the last segment in the template

^{c}

模板中的最后一个段落

^{c}

0x100

secondary alignment 次级对齐

0x200

not passing quality controls
未通过质量控制

0x400

PCT or optical duplicate
PCT 或光学副本

0x800

Supplementary alignment 补充对齐

^{a}

Bit 0 x 4 is the only reliable place to tell whether the read is unmapped. If 0 x 4 is set, no assumptions may be made about bits

0 \times 2, 0 \times 100

and

0 x 800

^{a}

位 0 x 4 是判断读取是否未映射的唯一可靠位置。如果设置了 0 x 4，则不能对位

0 \times 2, 0 \times 100

和

0 x 800

做出任何假设。

^{b}

For segments within the same slice.

^{b}

对于同一切片内的段。

^{c}

Bits 0 x 40 and 0 x 80 reflect the read ordering within each template inherent in the sequencing technology used, which may be independent from the actual mapping orientation. If

0 \times 40

and

0 \times 80

are both set, the read is part of a linear template (one where the template sequence is expected to be in a linear order), but it is neither the first nor the last read. If both 0 x 40 and 0 x 80 are unset, the index of the read in the template is unknown. This may happen for a non-linear template (such as one constructed by stitching together other templates) or when this information is lost during data processing.

^{c}

位 0 x 40 和 0 x 80 反映了在所使用的测序技术中每个模板内的读取顺序，这可能与实际的映射方向无关。如果

0 \times 40

和

0 \times 80

都被设置，则该读取是线性模板的一部分（即模板序列预计是线性顺序），但它既不是第一个读取也不是最后一个读取。如果 0 x 40 和 0 x 80 都未设置，则模板中读取的索引是未知的。这可能发生在非线性模板（例如通过拼接其他模板构建的模板）中，或者在数据处理过程中丢失了此信息。

CRAM bit flags (CF data series)
CRAM 位标志 (CF 数据系列)

The CRAM bit flags (also known as compression bit flags) expressed as an integer represent the CF data series. The following compression flags are defined for each CRAM read record:
CRAM 位标志（也称为压缩位标志）以整数形式表示 CF 数据系列。为每个 CRAM 读取记录定义了以下压缩标志：

Bit flag 位标志

Name 名称

Description 描述

0x1

quality scores stored as array
质量分数存储为数组

质量分数可以作为读取特征存储，也可以作为类似于读取碱基的数组存储。

quality scores can be stored as read features or as an

array similar to read bases.

0x2

detached 分离的

配对信息被逐字存储（例如，因为该配对跨越多个切片或字段与 CRAM 计算方法不同）

mate information is stored verbatim (e.g. because the

pair spans multiple slices or the fields differ to the

CRAM computed method)

0 x 4

has mate downstream 有配偶下游

告诉是否应该在流中进一步期待下一个段落

tells if the next segment should be expected further in

the stream

0x8

decode sequence as "*"
解码序列为 "*"

告知解码器该序列未知，并且任何编码的参考差异仅存在于重建 CIGAR 字符串。

informs the decoder that the sequence is unknown and

that any encoded reference differences are present only

to recreate the CIGAR string.

The following pseudocode describes the general process of decoding an entire CRAM record. The sequence data itself is in one of two encoding formats depending on whether the record is aligned (mapped).
以下伪代码描述了解码整个 CRAM 记录的一般过程。序列数据本身根据记录是否对齐（映射）采用两种编码格式之一。

Decode pseudocode 解码伪代码

procedure DECODERECORD
        \(B A M \_\)flags \(\leftarrow\) READITEM(BF, Integer)
        \(C R A \bar{M} \_\)flags \(\leftarrow\) READITEM \((\mathrm{CF}\), Integer \()\)
        DECODEPoSITIONS \(\triangleright\) See section 10.2

        DECODENAMES \(\triangleright\) See section 10.3
        DECODEMateData \(\triangleright\) See section 10.4
        DecoDeTaGData \(\triangleright\) See section 10.5
        if \((B F\) AND 4\()=0\) then \(\triangleright\) Unmapped flag
            DECODEMAPPEDREAD \(\triangleright\) See section 10.6
        else

            DECODEUNMAPPEDREAD \(\triangleright\) See section 10.7
        end if

end procedure

This pseudocode is not meant to be a fully implementable programming language, but to act as an algorithmic guide to the order and structure of CRAM decoding.
此伪代码并不旨在成为一个完全可实现的编程语言，而是作为 CRAM 解码的顺序和结构的算法指导。
The Readitem function referred above takes two arguments; the data series name and the data type used by the Encoding. It will use the codec specified in the Container Compression Header to retrieve the next value from that data series. Note there is only one permitted data type per data series, so the second argument is redundant and is included only as an aide-mémoire.
上述提到的 Readitem 函数接受两个参数；数据系列名称和编码使用的数据类型。它将使用容器压缩头中指定的编解码器从该数据系列中检索下一个值。请注意，每个数据系列仅允许一种数据类型，因此第二个参数是多余的，仅作为备忘。

10.2 CRAM positional data
10.2 CRAM 位置数据

Following the bit-wise BAM and CRAM flags, CRAM encodes positional related data including reference, alignment positions and length, and read-group. Positional data is stored for both mapped and unmapped sequences, as unmapped data may still be “placed” at a specific location in the genome (without being aligned). Typically this is done to keep a sequence pair (paired-end or mate-pair sequencing libraries) together when one of the pair aligns and the other does not.
在位元组 BAM 和 CRAM 标志之后，CRAM 编码位置相关数据，包括参考、比对位置和长度，以及读取组。位置数据存储在已比对和未比对的序列中，因为未比对的数据仍然可以在基因组中的特定位置“放置”（而不进行比对）。通常，这样做是为了在一对序列（成对末端或配对序列库）中保持它们在一起，当其中一个序列比对而另一个不比对时。

For reads stored in a position-sorted slice, the AP-delta flag in the compression header preservation map should be set and the AP data series will be delta encoded, using the slice alignment-start value as the first position to delta against. Note for multi-reference slices this may mean that the AP series includes negative values, such as when moving from an alignment to the end of one reference sequence to the start of the next or to unmapped unplaced data. When the AP-delta flag is not set the AP data series is stored as a normal integer value.
对于存储在位置排序切片中的读取，压缩头部保留映射中的 AP-delta 标志应被设置，AP 数据系列将进行增量编码，使用切片对齐起始值作为增量的第一个位置。请注意，对于多参考切片，这可能意味着 AP 系列包含负值，例如在从一个参考序列的对齐末尾移动到下一个参考序列的起始位置或未映射未放置数据时。当 AP-delta 标志未设置时，AP 数据系列将作为普通整数值存储。

数据系列类型

Data series

type

数据系列名称

Data series

name

Field 字段

Description 描述

int 整数

ref id 引用 ID

参考序列 ID（仅在多参考切片中存在）

reference sequence id (only present in

multiref slices)

int 整数

read length 读取长度

the length of the read
读取的长度

int 整数

alignment start 对齐开始

the alignment start position
对齐起始位置

int 整数

read group 读取组

在头部中以 Nh 记录表示的读取组标识符，从 0 开始，-1 表示没有组

the read group identifier expressed as

the Nh record in the header, starting

from 0 with -1 for no group

procedure DECODEPOSITIONS
    if slice_header.reference_sequence_id \(=-2\) then
        reference \(\_i d \leftarrow\) READITEM(RI, Integer)
    else
        \(r e f e r e n c e \_i d \leftarrow\) slice_header.reference_sequence_id
    end if
    read_length \(\leftarrow\) READITEM(RL, Integer)
    if container_pmap.AP_delta \(\neq 0\) then
            if first_record_in_slice then
            last_position \(\leftarrow\) slice_header.alignment_start
            end if
            alignment_position \(\leftarrow\) READITEM(AP, Integer) + last_position
            last_position \(\leftarrow\) alignment_position
        else
            alignment_position \(\leftarrow\) READITEM(AP, Integer)
        end if
        read_group \(\leftarrow\) READITEM \((\) RG, Integer \()\)
    end procedure

10.3 Read names (RN data series)
10.3 读取名称（RN 数据系列）

Read names can be preserved in the CRAM format, but this is optional and is governed by the RN preservation map key in the container compression header. See section 8.4. When read names are not preserved the CRAM decoder should generate names, typically based on the file name and a numeric ID of the read using the record counter field of the slice header block. Note read names may still be preserved even when the RN compression header key indicates otherwise, such as where a read is part of a read-pair and the pair spans multiple slices. In this situation the record will be marked as detached (see the CF data series) and the mate data below (section 10.4) will contain the read name.
读取名称可以在 CRAM 格式中保留，但这是可选的，并由容器压缩头中的 RN 保留映射键控制。请参见第 8.4 节。当读取名称未被保留时，CRAM 解码器应生成名称，通常基于文件名和使用切片头块的记录计数器字段的读取的数字 ID。请注意，即使 RN 压缩头键指示相反，读取名称仍可能被保留，例如当读取是读取对的一部分，并且该对跨越多个切片。在这种情况下，记录将标记为分离（请参见 CF 数据系列），下面的配对数据（第 10.4 节）将包含读取名称。

数据系列类型

Data series

type

数据系列名称

Data series

name

Field 字段

Description 描述

byte[

]

字节[

]

]

read names 读取名称

procedure DECODENAMES
        if container_pmap.read_names_included \(=1\) then
            read_name \(\leftarrow\) REAd \(\overline{\operatorname{ITEM}}(\mathrm{RN}\), Byte[])
        else
            read_name \(\leftarrow\) GENERATENAME
        end if
end procedure

10.4 Mate records
10.4 Mate 记录

There are two ways in which mate information can be preserved in CRAM. If the next fragment is not in the same slice we store verbatim copies of the insert size, mate reference chromosome and positions, and mate flags
在 CRAM 中，有两种方式可以保留配对信息。如果下一个片段不在同一切片中，我们会逐字存储插入大小、配对参考染色体和位置以及配对标志的副本。
(mapped status, orientation) for both records. In this case both records are labelled as “detached” in the CF data series using bit 2 .
（映射状态，方向）对于两个记录。在这种情况下，两个记录在 CF 数据系列中都标记为“分离”，使用位 2。
If this and the next fragment are within the same slice, we can derive much of this information by comparing the two records. The upstream record has CF bit 4 (mate downstream) flag set and stores the number of records to skip (in the NF data series) between this record and the record for the next fragment on this template, with zero meaning the next fragment is also the next record. The downstream record has neither CF bits 2 (detached) or 4 (mate downstream) set nor does it use the NF data series (unless it also has an additional “next fragment” to refer to).
如果这个片段和下一个片段在同一个切片内，我们可以通过比较这两个记录来推导出很多信息。上游记录的 CF 位 4（配对下游）标志被设置，并存储了在这个记录和该模板上下一个片段的记录之间要跳过的记录数（在 NF 数据系列中），零表示下一个片段也是下一个记录。下游记录既没有设置 CF 位 2（分离）也没有设置 CF 位 4（配对下游），也不使用 NF 数据系列（除非它还有一个额外的“下一个片段”可供参考）。

It is not mandatory to use this deduplication approach and optionally CRAM write implementations may wish to label data as detached even when all records for the template reside in the same slice. One reason to do this may be to preserve inconsistent data so that it round-trips through the CRAM format with full fidelity
不强制使用这种去重方法，选择性地，CRAM 写入实现可能希望将数据标记为分离，即使模板的所有记录都位于同一切片中。这样做的一个原因可能是为了保留不一致的数据，以便它能够以完整的保真度在 CRAM 格式中往返传输。

数据系列类型

Data series

type

Data series name 数据系列名称

Description 描述

int 整数

the number of records to skip to the next fragment
跳过到下一个片段的记录数

In the above case, the NS (mate reference name), NP (mate position) and TS (template size) fields for both records should be derived once the mate has also been decoded. Mate reference name and position are obvious and simply copied from the mate. The template size is computed using the method described in the SAM specification; the inclusive distance from the leftmost to rightmost mapped bases with the sign being positive for the leftmost record and negative for the rightmost record.
在上述情况下，两个记录的 NS（配对参考名称）、NP（配对位置）和 TS（模板大小）字段应在配对也被解码后得出。配对参考名称和位置显而易见，直接从配对中复制。模板大小是使用 SAM 规范中描述的方法计算的；从最左侧到最右侧映射碱基的包含距离，最左侧记录的符号为正，最右侧记录的符号为负。
If the next fragment is not found within this slice then the following structure is included into the CRAM record. Note there are cases where read-pairs within the same slice may be marked as detached and use this structure, such as to store mate-pair information that does not match the algorithm used by CRAM for computing the mate data on-the-fly.
如果在此切片中未找到下一个片段，则以下结构将包含在 CRAM 记录中。请注意，在某些情况下，同一切片中的读对可能被标记为分离，并使用此结构，例如存储与 CRAM 用于动态计算配对数据的算法不匹配的配对信息。

数据系列类型

Data series

type

Data series name 数据系列名称

Description 描述

int 整数

next mate bit flags, see table below
下一个伙伴位标志，请参见下表

byte[] 字节[]

the read name (if and only if not known already)
读取名称（仅在尚不知晓时）

int 整数

mate reference sequence identifier
配对参考序列标识符

int 整数

mate alignment start position
配对对齐起始位置

int 整数

the size of the template (insert size)
模板的大小（插入大小）

Next mate bit flags (MF data series)
下一个配对位标志（MF 数据系列）

The next mate bit flags expressed as an integer represent the MF data series. These represent the missing bits we excluded from the BF data series (when compared to the full SAM/BAM flags). The following bit flags are defined:
下一个 mate 位标志以整数形式表示 MF 数据系列。这些表示我们从 BF 数据系列中排除的缺失位（与完整的 SAM/BAM 标志相比）。以下位标志被定义：

Bit flag 位标志	Name 名称	Description 描述
0x1	mate negative strand bit 配对负链位	the bit is set if the mate is on the negative strand 如果配对在负链上，则位被设置
$0 \times 2$	mate unmapped bit 配对未映射位	the bit is set if the mate is unmapped 如果配对未映射，则位被设置

Decode mate pseudocode 解码配对伪代码

In the following pseudocode we are assuming the current record is this and its mate is next_frag.
在以下伪代码中，我们假设当前记录是这个，它的配对是 next_frag。
procedure DECODEMATEDATA
过程 DECODEMATEDATA
if

C F

AND 2 then

▹

Detached from mate
如果

C F

和 2 那么

▹

已与配偶断开连接
mate_flags

\leftarrow

READITEM(MF,Integer)
mate_flags

\leftarrow

读取项(MF, 整数)
if mate_flags AND 1 then
如果 mate_flags 和 1 那么
bam_flags

\leftarrow

bam_flags OR

0 \times 20 ▹

Mate is reverse-complemented
bam_flags

\leftarrow

bam_flags 或

0 \times 20 ▹

配对是反向互补的
end if 结束如果
if mate_flags AND 2 then
如果 mate_flags 和 2 那么
bam_flags

\leftarrow

bam_flags OR 0x08

▹

Mate is unmapped
bam_flags

\leftarrow

bam_flags OR 0x08

▹

配对未映射
end if 结束如果
if container_pmap.read_names_included

\neq 1

then
如果 container_pmap.read_names_included

\neq 1

那么

r e a d_n a \overset{―}{m e} \leftarrow\leftarrow READITEM (RN, \overset{―}{B y t e} [])

    end if
    mate_ref_id \leftarrow READITEM(NS, Integer)
    mate_position \leftarrow READITEM(NP, Integer)
    template_size \leftarrow READITEM(TS, Integer)
    else if CF ANND 4 then }\quad\triangleright\mathrm{ Mate is downstream
    if next_frag.bam_flags AND 0x10 then
        this.bam_flags \leftarrowthis.bam_flags OR 0x20 \triangleright next segment reverse complemented
    end if
    if next_frag.bam_flags AND 0x04 then
        this.bam_flags \leftarrowthis.bam_flags OR 0x08 \triangleright next segment unmapped
    end if
    next_frag \leftarrow READITEM(NF,Integer)
    next_record \leftarrowthis_record + next_frag + 1
    Resolve mate_ref_-id for this_record and next_record once both have been decoded
    Resolve mate_position for this_record and next_record once both have been decoded
    Find leftmost and rightmost mapped coordinate in records this_record and next_record.
    For leftmost of this_record and next_record: template_size \leftarrow rightmost - leftmost + 1
    For rightmost of this_record and next_record: template_size }\leftarrow-(\mathrm{ rightmost - leftmost + 1)
        end if
end procedure

Note as with the SAM specification a template may be permitted to have more than two alignment records. In this case the “mate” for each record is considered to be the next record, with the mate for the last record being the first to form a circular list. The above algorithm is a simplification that does not deal with this scenario. The full method needs to observe when record this

+ N F

is also labelled as having an additional mate downstream. One recommended approach is to resolve the mate information in a second pass, once the entire slice has been decoded. The final segment in the mate chain needs to set bam_flags fields 0 x 20 and 0x08 accordingly based on the first segment. This is also not listed in the above algorithm, for brevity.
注意，与 SAM 规范一样，模板可能允许有超过两个的比对记录。在这种情况下，每个记录的“配对”被视为下一个记录，最后一个记录的配对是第一个记录，从而形成一个循环列表。上述算法是一个简化版本，没有处理这种情况。完整的方法需要观察当记录

+ N F

也被标记为在下游有额外的配对时。一种推荐的方法是在第二次遍历中解析配对信息，一旦整个切片被解码。配对链中的最后一个段需要根据第一个段相应地设置 bam_flags 字段 0x20 和 0x08。这在上述算法中也没有列出，以简洁为主。

10.5 Auxiliary tags 10.5 辅助标签

Tags are encoded using a tag line (TL data series) integer into the tag dictionary (TD field in the compression header preservation map, see section 8.4). See section 8.4 for a more detailed description of this process.
标签使用标签行（TL 数据系列）整数编码到标签字典中（压缩头保留映射中的 TD 字段，参见第 8.4 节）。有关此过程的更详细描述，请参见第 8.4 节。

数据系列类型

Data series

type

数据系列名称

Data series

name

Field 字段

Description 描述

int 整数

tag line 标签行

an index into the tag dictionary (TD)
一个索引到标签字典（TD）

*

? ? ?

tag name/type 标签名称/类型

3 个字符的键

(2

标签标识符和 1 个标签类型

),

，如标签字典所指定

3 character key

(2

tag identifier and 1 tag

type

),

as specified by the tag dictionary

procedure DECODETAGDATA
        tag_line \(\leftarrow\) READITEM(TL,Integer)
        for all ele \(\in\) container_pmap.tag_dict(tag_line) do
            name \(\leftarrow\) first two characters of ele
            tag \((\) type \() \leftarrow\) last character of ele
            \(\operatorname{tag}(\) name \() \leftarrow\) READITEM \((\) ele, Byte[])
        end for
end procedure

In the above procedure, name is a two letter tag name and type is one of the permitted types documented in the SAM/BAM specification. Type is A (a single character), c (signed 8-bit integer), C (unsigned 8-bit integer), s (signed 16-bit integer), S (unsigned 16-bit integer), i (signed 32-bit integer), I (unsigned 32-bit integer), f (32-bit float), Z (nul-terminated string), H (nul-terminated string of hex digits) and B (binary data in array format with the first byte being one of c,C,s,S,i,I,f using the meaning above, a 32 -bit integer for the number of array elements, followed by array data encoded using the specified format). All integers are little endian encoded.
在上述过程中，name 是一个两个字母的标签名，type 是 SAM/BAM 规范中记录的允许类型之一。类型包括 A（单个字符）、c（有符号 8 位整数）、C（无符号 8 位整数）、s（有符号 16 位整数）、S（无符号 16 位整数）、i（有符号 32 位整数）、I（无符号 32 位整数）、f（32 位浮点数）、Z（以 null 结尾的字符串）、H（以 null 结尾的十六进制数字字符串）和 B（以数组格式的二进制数据，第一字节为 c、C、s、S、i、I、f 中的一个，后跟一个 32 位整数表示数组元素的数量，随后是使用指定格式编码的数组数据）。所有整数均为小端编码。
For example a SAM tag MQ: i has name MQ and type i and will be decoded using one of MQc, MQC, MQs, MQS, MQi and MQI data series depending on size and sign of the integer value.
例如，一个 SAM 标签 MQ: i 具有名称 MQ 和类型 i，并将根据整数值的大小和符号使用 MQc、MQC、MQs、MQS、MQi 和 MQI 数据系列之一进行解码。

Note some auxiliary tags can be created automatically during decode so can optionally be removed by the encoder. However if the decoder finds a tag stored verbatim it should use this in preference to automatically computing the value.
注意，在解码过程中可以自动创建一些辅助标签，因此编码器可以选择性地将其删除。然而，如果解码器发现一个标签以逐字形式存储，它应该优先使用这个标签，而不是自动计算值。
The RG (read group) auxiliary tag should be created if the read group (RG data series) value is not -1 .
如果读取组（RG 数据系列）值不是 -1，则应创建 RG（读取组）辅助标签。
The MD and NM auxiliary tags store the differences (an edit string) between the sequence and the reference along with the number of mismatches. These may optionally be created on-the-fly during reference-based sequence reconstruction and should match the description provided in the SAMtags document. An encoder may decide to store these verbatim when no reference is used or where the automatically constructed values differ to the input data.
MD 和 NM 辅助标签存储序列与参考之间的差异（编辑字符串）以及不匹配的数量。这些标签可以在基于参考的序列重建过程中动态创建，并应与 SAMtags 文档中提供的描述相匹配。当未使用参考或自动构建的值与输入数据不同的情况下，编码器可以决定逐字存储这些标签。
Note there is no mechanism to describe which records have MD/NM present and which do not. If this is deemed important, the only recourse is to store all MD and NM verbatim and to request that the decoding software does not automatically generate its own for records that have no stored MD and NM tags.
请注意，没有机制来描述哪些记录具有 MD/NM，哪些没有。如果这被认为很重要，唯一的解决办法是逐字存储所有 MD 和 NM，并请求解码软件对于没有存储 MD 和 NM 标签的记录不要自动生成自己的标签。

10.6 Mapped reads 10.6 映射读取

Read feature records 读取特性记录

Read features are used to store read details that are expressed using read coordinates (e.g. base differences respective to the reference sequence). The read feature records start with the number of read features followed by the read features themselves. Each read feature has the position encoded as the distance since the last feature position, or the absolute position (i.e. delta vs zero) for the first feature. Finally the single mapping quality and per-base quality scores are stored.
读取特征用于存储使用读取坐标表示的读取细节（例如，相对于参考序列的碱基差异）。读取特征记录以读取特征的数量开始，后面是读取特征本身。每个读取特征的位置编码为自上一个特征位置以来的距离，或者对于第一个特征的绝对位置（即与零的差异）。最后，存储单一映射质量和每碱基质量分数。

Data series type 数据系列类型

数据系列名称

Data series

name

Field 字段

Description 描述

int 整数

读取特征的数量

number of read

features

the number of read features
读取特征的数量

int 整数

in-read-position

^{a}

在读取位置

^{a}

delta-position of the read feature
读取特征的增量位置

byte 字节

read feature code 读取功能代码

See feature codes below
请参见下面的功能代码

*

*

read feature data

^{a}

读取特征数据

^{a}

See feature codes below
请参见下面的功能代码

int 整数

mapping qualities 映射质量

mapping quality score 映射质量分数

byte[read length] 字节[读取长度]

quality scores 质量分数

the base qualities, if preserved
基础品质，如果保持

^{a}

Repeated FN times, once for each read feature.

^{a}

重复 FN 次，每次读取特征一次。

Read feature codes 读取功能代码

Each feature code has its own associated data series containing further information specific to that feature. The following codes are used to distinguish variations in read coordinates:
每个功能代码都有其相关的数据系列，其中包含特定于该功能的进一步信息。以下代码用于区分读取坐标的变体：

Feature code 功能代码

Id 标识符

数据系列类型

Data series

type

数据系列名称

Data series

name

Description 描述

Bases 基础

b (0x62)

byte[ 字节[

a stretch of bases
一段基础

Scores 分数

q (0x71)

byte[ 字节[

a stretch of scores
一段分数

Read base 读取基础

B (0x42)

byte,byte 字节,字节

BA,QS

一个基础及相关的质量分数

A base and associated quality

score

Substitution 替代

X (0x58)

byte 字节

基本替换代码，SAM 操作符

X, M

和

=

base substitution codes, SAM

operators

X, M

and

=

Insertion 插入

I (0x49) 我 (0x49)

byte[] 字节[]

插入的碱基，SAM 操作符 I

inserted bases, SAM operator

Deletion 删除

D (0x44)

int 整数

删除的碱基数量，SAM 操作符 D

number of deleted bases,

SAM operator D

Insert base 插入基础

i (0x69)

byte 字节

单插入基，SAM 操作符 I

single inserted base, SAM

operator I

Quality score 质量得分

Q (0x51)

byte 字节

single quality score 单一质量分数

Reference skip 参考跳过

N (0x4E)

int 整数

跳过的碱基数，SAM 操作符 N

number of skipped bases,

SAM operator N

Soft clip 软剪辑

S (0x53)

byte[] 字节[]

软剪切碱基，SAM 操作符 S

soft clipped bases, SAM

operator S

Padding 填充

P (0 \times 50)

int 整数

填充碱基的数量，SAM 操作符 P

number of padded bases,

SAM operator P

Hard clip 硬剪辑

H (0x48)

int 整数

硬剪切碱基的数量，SAM 操作符 H

number of hard clipped bases,

SAM operator H

Note for compatibility with BAM, all base comparisons should be done in a case-insensitive manner, and all bases written to SC, IN and BA data series should be in upper-case.
关于与 BAM 的兼容性，所有碱基比较应以不区分大小写的方式进行，所有写入 SC、IN 和 BA 数据系列的碱基应为大写。

Base substitution codes (BS data series)
基本替代代码（BS 数据系列）

A base substitution is defined as a change from one nucleotide base (reference base) to another (read base), including N as an unknown or missing base. There are 5 supported reference bases (ACGTN), with 4 possible substitutions for each base. Any other base type, such as an ambiguity code, must be written verbatim using the BA data series.
碱基替换被定义为从一个核苷酸碱基（参考碱基）更改为另一个（读取碱基），包括 N 作为未知或缺失的碱基。支持 5 种参考碱基（ACGTN），每种碱基有 4 种可能的替换。任何其他碱基类型，例如模糊代码，必须使用 BA 数据系列逐字书写。

The codes for all possible substitutions are stored in a two-dimensional substitution matrix, indexed by reference base

(A, C, G, T, N)

and BS code

(0 - 3)

, with each matrix element holding the modified base.
所有可能替代的代码存储在一个二维替代矩阵中，该矩阵由参考碱基

(A, C, G, T, N)

和 BS 代码

(0 - 3)

索引，每个矩阵元素保存修改后的碱基。

Substitution Matrix Format
替代矩阵格式

There are 5 possible base types supported by the BS data series, A, C, G, T and N. Hence for any reference base there are 4 possible substitutions. Each of these substitution possibilities are numbered 0 to 3 , in the order shown above (omitting the reference base type). Therefore the full list of substitution codes for a specific reference base is 42 -bit numbers

(0 - 3)

in the order shown above, minus the reference base itself. These are packed into a single byte with the high 2-bits first.
BS 数据系列支持 5 种可能的基本类型：A、C、G、T 和 N。因此，对于任何参考碱基，有 4 种可能的替代。每种替代可能性按上述顺序编号为 0 到 3（省略参考碱基类型）。因此，特定参考碱基的完整替代代码列表是 42 位数字

(0 - 3)

，按上述顺序排列，减去参考碱基本身。这些被打包成一个字节，前 2 位为高位。
For example for reference base C we would record the BS numerical values for substituting C with

A, G, T

and N respectively. If we wish

A = 1, G = 0, T = 2

and

N = 3

then we would store binary 01001011 , or hex 0 x 4 B .
例如，对于参考基准 C，我们将记录替换 C 为

A, G, T

和 N 的 BS 数值。如果我们希望

A = 1, G = 0, T = 2

和

N = 3

，那么我们将存储二进制 01001011，或十六进制 0 x 4 B。
The full substitution matrix is 5 bytes, each storing the 4 BS codes for reference base

A, C, G, T

and N respectively.
完整的替代矩阵为 5 个字节，每个字节存储参考基因

A, C, G, T

和 N 的 4 个 BS 代码。

A complete matrix that maps

C / G

together and

A / T

together may look like this:
一个完整的矩阵，将

C / G

组合在一起和

A / T

组合在一起，可能看起来像这样：

	Seq. base 序列基础
Ref. base 参考基础	$A$	$C$	$G$	$T$	$N$
A	-	1	2	0	3
C	1	-	0	2	3
G	2	0	-	1	3
T	0	2	1	-	3
N	0	1	2	3	-

This would be encoded as
这将被编码为
binary

01100011, 01001011, 10000111, 00100111, 00011011

二进制

01100011, 01001011, 10000111, 00100111, 00011011

or hex

0 x 63, 0 x 4 b, 0 x 87, 0 x 27 0 x 1 b

.
或十六进制

0 x 63, 0 x 4 b, 0 x 87, 0 x 27 0 x 1 b

To decode, we would use the following lookup table, showing the same data as above with codes sorted into 0 ,

1, 2, 3

order.
要解码，我们将使用以下查找表，显示与上面相同的数据，代码按 0 ,

1, 2, 3

顺序排序。

	BS Code BS 代码
Ref. base 参考基础	$0$	$1$	$2$	$3$
A	T	C	G	N
C	G	A	T	N
G	C	T	A	N
T	A	G	C	N
N	A	C	G	T

Substitution Code Assignment
替代代码分配

There is no strict requirement on using a specific substitution matrix, nor that it be optimal. However one strategy may be to ensure the most common substitution is always given code 0 , the next most common is code 1 , and so on. This means the distribution of BS values will be skewed towards lower values, which helps improve compression over more uniformly distributed frequencies.
没有严格要求使用特定的替代矩阵，也不要求其是最优的。然而，一种策略可能是确保最常见的替代始终分配代码 0，第二常见的分配代码 1，依此类推。这意味着 BS 值的分布将偏向于较低的值，这有助于在更均匀分布的频率上提高压缩效果。
For example, let us assume the following substitution frequencies for base A:
例如，假设碱基 A 的以下替代频率：
AC:

15 %

AG:

25 %

AT:

55 %

AN:

5 %

Then the substitution codes are

T = 0, G = 1, C = 2, N = 3

.
然后替换代码是

T = 0, G = 1, C = 2, N = 3

。

Decode mapped read pseudocode
解码映射读取伪代码

procedure DECODEMAPPEDREAD
    feature_number }\leftarrow\mathrm{ READITEM(FN, Integer)
    last_feature_position }\leftarrow
    for }i\leftarrow1\mathrm{ to feature_number do
        DECODEFEATURE
    end for
    mapping_quality \leftarrow READITEM(MQ, Integer)
    if CF AND 1 then \triangleright Quality stored as an array
            for }i\leftarrow1\mathrm{ to read_length do
                quality_score \leftarrow READITEM(QS, Integer)
            end for
        end if
end procedure
procedure DecodeFeature
    feature_code }\leftarrow\mathrm{ READITEM(FC, Integer)
    feature_position }\leftarrow\mathrm{ READITEM(FP, Integer) + last_feature_position
    last_feature_position }\leftarrow\mathrm{ feature_position
    if feature_code ='B' then
        base }\leftarrow\mathrm{ READITEM(BA, Byte)
        quality_score }\leftarrow\mathrm{ READITEM(QS, Byte)
    else if feature_code ='X' then
        substitution_code \leftarrow READItEM(BS, Byte)
    else if feature_code ='I' then
        inserted_bases }\leftarrow\mathrm{ READITEM(IN, Byte[])
        else if feature_code ='S' then
            softclip_bases }\leftarrow\mathrm{ READITEM(SC, Byte[])

    else if feature_code \(={ }^{\prime} H\) ' then
        hardclip_length \(\leftarrow\) ReAdItEm(HC, Integer)
    else if feature_code ='P' then
        pad_length \({ }^{-} \leftarrow\) READITEM(PD, Integer)
    else if feature_code \(=\) 'D' then
        deletion_length \(\leftarrow\) READITEM(DL, Integer)
    else if feature_code \(={ }^{\prime} \mathrm{N}\) ' then
        ref_skip_length \(\leftarrow\) READITEm(RS, Integer)
    else if feature_code \(=\) 'i' then
        base \(-\leftarrow\) ReAdItEm(BA, Byte)
    else if feature \(\quad\) code \(=' \mathrm{~b}\) ' then
        bases \(\leftarrow\) REadItEm(BB, Byte[])
    else if feature_code ='q' then
        quality_scores \(\leftarrow\) REAdITEM(QQ, Byte[])
    else if feature_code \(=\) ' Q ' then
        quality_score \(\leftarrow\) READITEM(QS, Byte)
    end if
end procedure

10.7 Unmapped reads
10.7 未映射的读数

The CRAM record structure for unmapped reads has the following additional fields:
未映射读取的 CRAM 记录结构具有以下附加字段：

Data series type 数据系列类型

数据系列名称

Data series

name

Field 字段

Description 描述

byte[read length] 字节[读取长度]

bases 基础

the read bases 读取的碱基

byte[read length] 字节[读取长度]

quality scores 质量分数

the base qualities, if preserved
基础品质，如果保持

procedure DeCoDeUnMAPpedREAD
        for \(i \leftarrow 1\) to read_length do
            base \(\leftarrow\) READITEM(BA, Byte)
        end for
        if \(C F\) AND 1 then \(\triangleright\) Quality stored as an array
            for \(i \leftarrow 1\) to read_length do
                quality_score \(\leftarrow\) READITEM(QS, Byte)
            end for
        end if
end procedure

11 Reference sequences
11 参考序列

CRAM format is natively based upon usage of reference sequences even though in some cases they are not required. In contrast to BAM format CRAM format has strict rules about reference sequences.
CRAM 格式本质上基于参考序列的使用，尽管在某些情况下它们并不是必需的。与 BAM 格式相比，CRAM 格式对参考序列有严格的规则。

M5 (sequence MD5 checksum) field of @SQ sequence record in the BAM header is required and UR (URI for the sequence fasta optionally gzipped file) field is strongly advised. The rule for calculating MD5 is to remove any non-base symbols (like $∖ n$ , sequence name or length and spaces) and upper case the rest. Here are some examples:
BAM 头中的@SQ 序列记录的 M5（序列 MD5 校验和）字段是必需的，UR（序列 fasta 可选 gzipped 文件的 URI）字段强烈建议使用。计算 MD5 的规则是去除任何非碱基符号（如 $∖ n$ 、序列名称或长度和空格），并将其余部分转换为大写。以下是一些示例：

> samtools faidx human_g1k_v37.fasta 1 | grep -v ,^>' | tr -d '\n' | tr a-z A-Z | md5sum
-
1b22b98cdeb4a9304cb5d48026a85128 -
> samtools faidx human_g1k_v37.fasta 1:10-20 |grep -v '^>' |tr -d '\n' |tr a-z A-Z |md5sum
Of2a4865e3952676ffad2c3671f14057 -

Please note that the latter calculates the checksum for 11 bases from position 10 (inclusive) to 20 (inclusive) and the bases are counted 1-based, so the first base position is 1.
请注意，后者计算从位置 10（包含）到 20（包含）的 11 个碱基的校验和，碱基是以 1 为基数计数的，因此第一个碱基位置是 1。
2. All CRAM reader implementations are expected to check for reference MD5 checksums and report any missing or mismatching entries. Consequently, all writer implementations are expected to ensure that all checksums are injected or checked during compression time.
2. 所有 CRAM 读取器实现都应检查参考 MD5 校验和，并报告任何缺失或不匹配的条目。因此，所有写入器实现都应确保在压缩时注入或检查所有校验和。
3. In some cases reads may be mapped beyond the reference sequence. All out of range reference bases are all assumed to be ’ N '.
在某些情况下，读取可能会映射到参考序列之外。所有超出范围的参考碱基都假定为 'N'。
4. MD5 checksum bytes in slice header should be ignored for unmapped or multiref slices.
4. 对于未映射或多引用切片，切片头中的 MD5 校验和字节应被忽略。

12 Indexing 12 索引

General notes 一般说明

Indexing is only valid on coordinate (reference ID and then leftmost position) sorted files.
索引仅在按坐标（参考 ID 然后是最左侧位置）排序的文件上有效。
Please note that CRAM indexing is external to the file format itself and may change independently of the file format specification in the future. For example, a new type of index file may appear.
请注意，CRAM 索引是外部于文件格式本身的，并且可能在未来独立于文件格式规范而变化。例如，可能会出现一种新的索引文件类型。

Individual records are not indexed in CRAM files, slices should be used instead as a unit of random access. Another important difference between CRAM and BAM indexing is that CRAM container header and compression header block (first block in container) must always be read before decoding a slice. Therefore two read operations are required for random access in CRAM.
在 CRAM 文件中，单个记录没有被索引，应该使用切片作为随机访问的单位。CRAM 和 BAM 索引之间的另一个重要区别是，CRAM 容器头和压缩头块（容器中的第一个块）必须在解码切片之前始终读取。因此，在 CRAM 中进行随机访问需要两个读取操作。

Indexing a CRAM file is deemed to be a lightweight operation because it usually does not require any CRAM records to be read. Indexing information can be obtained from container headers, namely sequence id, alignment start and span, container start byte offset and slice byte offset inside the container (landmarks). The exception to this is with multi-reference containers, where the “RI” data series must be read.
索引 CRAM 文件被认为是一项轻量级操作，因为通常不需要读取任何 CRAM 记录。索引信息可以从容器头部获取，即序列 ID、比对起始位置和跨度、容器起始字节偏移量以及容器内的切片字节偏移量（标志）。例外情况是多参考容器，在这种情况下必须读取“RI”数据系列。

CRAM index CRAM 索引

A CRAM index is a gzipped tab delimited file containing the following columns:
CRAM 索引是一个 gzipped 制表符分隔的文件，包含以下列：

Reference sequence id 参考序列 ID
Alignment start (ignored on read for unmapped slices, set to 0 on write)
对齐开始（对于未映射的切片在读取时被忽略，写入时设置为 0）
Alignment span (ignored on read for unmapped slices, set to 0 on write)
对齐跨度（对未映射切片的读取忽略，写入时设置为 0）
Absolute byte offset of Container header in the file.
文件中容器头的绝对字节偏移量。
Relative byte offset of the Slice header block, from the end of the container header. This is the same as the “landmark” field in the container header.
切片头块的相对字节偏移量，从容器头部的末尾开始。这与容器头部中的“地标”字段相同。
Slice size in bytes (including slice header and all blocks).
切片大小（以字节为单位，包括切片头和所有块）。

Each line represents a slice in the CRAM file. Please note that all slices must be listed in the index file.
每一行代表 CRAM 文件中的一个切片。请注意，所有切片必须在索引文件中列出。
Multi-reference slices may need to have multiple lines for the same slice; one for each reference contained within that slice. In this case the index reference sequence ID will be the actual reference ID (from the “RI” data series) and not -2 .
多参考切片可能需要为同一切片有多行；每个切片中包含的每个参考都有一行。在这种情况下，索引参考序列 ID 将是实际的参考 ID（来自“RI”数据系列），而不是 -2。
Slices containing solely unmapped unplaced data (reference ID -1) still require values for all columns, although the alignment start and span will be ignored. It is recommended that they are both set to zero.
仅包含未映射未放置数据的切片（参考 ID -1）仍然需要所有列的值，尽管对齐开始和跨度将被忽略。建议将它们都设置为零。

To illustrate this the absolute and relative offsets used in a three slice container are shown in the diagram below.
为了说明这一点，下面的图示出了在三片容器中使用的绝对和相对偏移量。

BAM index BAM 索引

BAM indexes are supported by using 4-byte integer pointers called landmarks that are stored in container header. BAM index pointer is a 64 -bit value with 48 bits reserved for the BAM block start position and 16 bits reserved for the in-block offset. When used to index CRAM files, the first 48 bits are used to store the CRAM container start position and the last 16 bits are used to store the index of the landmark in the landmark array stored in container header. The landmark index can be used to access the appropriate slice.
BAM 索引通过使用称为地标的 4 字节整数指针来支持，这些指针存储在容器头中。BAM 索引指针是一个 64 位值，其中 48 位保留用于 BAM 块的起始位置，16 位保留用于块内偏移量。当用于索引 CRAM 文件时，前 48 位用于存储 CRAM 容器的起始位置，最后 16 位用于存储容器头中地标数组的地标索引。地标索引可用于访问相应的切片。

The above indexing scheme treats CRAM slices as individual records in BAM file. This allows to apply BAM indexing to CRAM files, however it introduces some overhead in seeking specific alignment start because all preceding records in the slice must be read and discarded.
上述索引方案将 CRAM 切片视为 BAM 文件中的单独记录。这允许对 CRAM 文件应用 BAM 索引，但在查找特定比对起始位置时会引入一些开销，因为必须读取并丢弃切片中的所有前置记录。

13 Encodings 13 编码

13.1 Introduction 13.1 介绍

The basic idea for codings is to efficiently represent some values in binary format. This can be achieved in a number of ways that most frequently involve some knowledge about the nature of the values being encoded, for example, distribution statistics. The methods for choosing the best encoding and determining its parameters are very diverse and are not part of the CRAM format specification, which only describes how the information needed to decode the values should be stored.
编码的基本思想是高效地以二进制格式表示某些值。这可以通过多种方式实现，通常涉及对被编码值的性质的一些了解，例如分布统计。选择最佳编码和确定其参数的方法非常多样，并不属于 CRAM 格式规范的内容，后者仅描述了解码值所需信息的存储方式。
Note two of the encodings (Golomb and Golomb-Rice) are listed as deprecated. These are still formally part of the CRAM specification, but have not been used by the primary implementations and may not be well supported. Therefore their use is permitted, but not recommended.
注意，两个编码（Golomb 和 Golomb-Rice）被列为不推荐使用。这些编码仍然是 CRAM 规范的正式部分，但主要实现中未使用，并且可能不被很好支持。因此，允许使用它们，但不推荐。

Offset 偏移量

Many of the codings listed below encode positive integer numbers. An integer offset value is used to allow any integer numbers and not just positive ones to be encoded. It can also be used for monotonically decreasing distributions with the maximum not equal to zero. For example, given offset is 10 and the value to be encoded is 1 , the actually encoded value would be offset + value

= 11

. Then when decoding, the offset would be subtracted from the decoded value.
以下列出的许多编码用于编码正整数。使用整数偏移值可以允许编码任何整数，而不仅仅是正整数。它也可以用于最大值不等于零的单调递减分布。例如，给定的偏移量为 10，待编码的值为 1，则实际编码的值为偏移量 + 值

= 11

。然后在解码时，偏移量将从解码值中减去。

13.2 EXTERNAL: codec ID 1
13.2 外部: 编解码器 ID 1

Can encode types Byte, Integer.
可以编码类型 Byte、Integer。
The EXTERNAL coding is simply storage of data verbatim to an external block with a given ID. If the type is Byte the data is stored as-is, otherwise for Integer type the data is stored in ITF8.
外部编码只是将数据逐字存储到具有给定 ID 的外部块中。如果类型是字节，则数据按原样存储；否则，对于整数类型，数据以 ITF8 格式存储。

Parameters 参数

CRAM format defines the following parameters of EXTERNAL coding:
CRAM 格式定义了 EXTERNAL 编码的以下参数：

Data type 数据类型	Name 名称	Comment 评论
itf8	external id 外部 ID	id of an external block containing the byte stream 外部块的 ID，包含字节流

13.3 Huffman coding: codec ID 3
13.3 哈夫曼编码：编解码器 ID 3

Can encode types Byte, Integer.
可以编码类型 Byte、Integer。

Huffman coding replaces symbols (values to encode) by binary codewords, with common symbols having shorter codewords such that the total message of binary codewords is shorter than using uniform binary codeword lengths. The general process consists of the following steps.
霍夫曼编码通过二进制代码字替换符号（要编码的值），常见符号具有较短的代码字，从而使得二进制代码字的总消息长度比使用统一的二进制代码字长度更短。一般过程包括以下步骤。

Obtain symbol code lengths.
获取符号代码长度。
If encoding: 如果编码：
Compute symbol frequencies.
计算符号频率。
Compute code lengths from frequencies.
根据频率计算代码长度。
If decoding: 如果解码：
Read code lengths from codec parameters.
从编解码参数读取代码长度。
Compute canonical Huffman codewords from code lengths $^{5}$ .
从码长 $^{5}$ 计算规范哈夫曼码字。
Encode or decode bits as per the symbol to codeword table. Codewords have the “prefix property” that no codeword is a prefix of another codeword, enabling unambiguous decode bit by bit.
根据符号到代码字表对比特进行编码或解码。代码字具有“前缀属性”，即没有任何代码字是另一个代码字的前缀，从而实现逐位无歧义解码。

The use of canonical Huffman codes means that we only need to store the code lengths and use the same algorithm in both encoder and decoder to generate the codewords. This is achieved by ensuring our symbol alphabet has a natural sort order and codewords are assigned in numerical order.
使用规范哈夫曼编码意味着我们只需存储码长，并在编码器和解码器中使用相同的算法来生成码字。这是通过确保我们的符号字母表具有自然排序顺序，并以数字顺序分配码字来实现的。
Important note: for alphabets with only one value, the codeword will be zero bits long. This makes the Huffman codec an efficient mechanism for specifying constant values.
重要说明：对于只有一个值的字母，代码字将是零位长。这使得霍夫曼编码器成为指定常量值的有效机制。

Canonical code computation
规范代码计算

Sort the alphabet ascending using bit-lengths and then using numerical order of the values.
按位长度升序排列字母，然后按值的数值顺序排列。
The first symbol in the list gets assigned a codeword which is the same length as the symbol’s original codeword but all zeros. This will often be a single zero (‘0’).
列表中的第一个符号被分配一个代码字，该代码字与符号的原始代码字长度相同，但全部为零。这通常是一个单独的零（‘0’）。
Each subsequent symbol is assigned the next binary number in sequence, ensuring that following codes are always higher in value.
每个后续符号都被分配下一个顺序中的二进制数字，确保后续代码的值始终更高。
When you reach a longer codeword, then after incrementing, append zeros until the length of the new codeword is equal to the length of the old codeword.
当你达到一个较长的代码字时，在递增后，附加零直到新代码字的长度等于旧代码字的长度。

Examples 示例

Symbol 符号	Code length 代码长度	Codeword 代码词
A	1	0
B	3	100
C	3	101
D	3	110
E	4	1110
F	4	1111

Parameters 参数

Data type 数据类型	Name 名称	Comment 评论
itf8[]	alphabet 字母表	list of all encoded symbols (values) 所有编码符号（值）的列表
itf8[]	bit-lengths 位长	array of bit-lengths for each symbol in the alphabet 字母表中每个符号的位长度数组

13.4 Byte array coding
13.4 字节数组编码

Often there is a need to encode an array of bytes where the length is not predetermined. For example the read identifiers differ per alignment record, possibly with different lengths, and this length must be stored somewhere. There are two choices available: storing the length explicitly (BYTE_ARRAY_LEN) or continuing to read bytes until a termination value is seen (BYTE_ARRAY_STOP).
通常需要对一个字节数组进行编码，而其长度并未预先确定。例如，读取标识符因对齐记录而异，可能具有不同的长度，并且该长度必须存储在某处。有两种选择可用：显式存储长度（BYTE_ARRAY_LEN）或继续读取字节直到看到终止值（BYTE_ARRAY_STOP）。
Note in contrast to this, quality values are known to be the same length as the sequence which is an already known quantity, so this does not need to be encoded using the byte array codecs.
请注意，与此相反，质量值的长度与序列相同，这是一个已知的量，因此不需要使用字节数组编解码器进行编码。

BYTE_ARRAY_LEN: codec ID 4
BYTE_ARRAY_LEN: 编解码器 ID 4

Can encode types Byte [ ].
可以编码类型 Byte [ ]。
Byte arrays are captured length-first, meaning that the length of every array element is written using an additional encoding. For example this could be a HUFFMAN encoding or another EXTERNAL block. The length is decoded first followed by the data, followed by the next length and data, and so on.
字节数组是按长度优先捕获的，这意味着每个数组元素的长度是使用额外编码写入的。例如，这可以是霍夫曼编码或另一个外部块。长度首先被解码，然后是数据，接着是下一个长度和数据，依此类推。
This encoding can therefore be considered as a nested encoding, with each pair of nested encodings containing their own set of parameters. The byte stream for parameters of the BYTE_ARRAY_LEN encoding is therefore the concatenation of the length and value encoding parameters as described in section 2.3 .
因此，这种编码可以被视为嵌套编码，每对嵌套编码包含其自己的参数集。因此，BYTE_ARRAY_LEN 编码的参数的字节流是第 2.3 节中描述的长度和数值编码参数的连接。
The parameter for BYTE_ARRAY_LEN are listed below:
BYTE_ARRAY_LEN 的参数如下：

Data type 数据类型

Name 名称

Comment 评论

encoding<int> 编码

lengths encoding 长度编码

一个编码，描述如何捕获数组的长度

an encoding describing how the arrays lengths are

captured

encoding<byte> 编码

values encoding 值编码

an encoding describing how the values are captured
一个编码，描述了如何捕获这些值

For example, the bytes specifying a BYTE_ARRAY_LEN encoding, including the codec and parameters, for a 16-bit X0 auxiliary tag (“X0C”) may use

\overset{―}{H}

UFFMA

\overset{―}{N}

encoding to specify the length (always 2 bytes) and an EXTERNAL encoding to store the value to an external block with ID 200.
例如，指定 BYTE_ARRAY_LEN 编码的字节，包括编解码器和参数，对于 16 位 X0 辅助标签（“X0C”）可以使用

\overset{―}{H}

UFFMA

\overset{―}{N}

编码来指定长度（始终为 2 字节），并使用 EXTERNAL 编码将值存储到 ID 为 200 的外部块中。

Bytes 字节

Meaning 意义

0x04

BYTE_ARRAY_LEN codec ID BYTE_ARRAY_LEN 编解码器 ID

0x0a

10 remaining bytes of BYTE_ARRAY_LEN parameters
10 个剩余字节的 BYTE_ARRAY_LEN 参数

0x03

HUFFMAN codec ID, for aux tag lengths
霍夫曼编码 ID，用于辅助标签长度

0x04

4 more bytes of HUFFMAN parameters
4 个字节的霍夫曼参数

0x01

Alphabet array size

= 1

字母数组大小

= 1

0x02

alphabet symbol; (length

= 2)

字母符号；（长度

= 2)

0x01

Codeword array size

= 1

代码字数组大小

= 1

0x00

Code length

= 0

(zero bits needed as alphabet is size 1)
代码长度

= 0

（需要零位，因为字母表大小为 1）

0x01

EXTERNAL codec ID, for aux tag values
外部编解码器 ID，用于辅助标签值

0x02

2 more bytes of EXTERNAL parameters
2 个额外字节的外部参数

0x80 0xc8

ITF8 encoding for block ID 200
块 ID 200 的 ITF8 编码

BYTE_ARRAY_STOP: codec ID 5
BYTE_ARRAY_STOP: 编解码器 ID 5

Can encode types Byte [ ].
可以编码类型 Byte [ ]。
Byte arrays are captured as a sequence of bytes terminated by a special stop byte. The data returned does not include the stop byte itself. In contrast to BYTE_ARRAY_LEN the value is always encoded with EXTERNAL so the parameter is an external id instead of another encoding.
字节数组被捕获为以特殊停止字节终止的字节序列。返回的数据不包括停止字节本身。与 BYTE_ARRAY_LEN 相比，值始终使用 EXTERNAL 编码，因此参数是外部 ID，而不是其他编码。

Data type 数据类型	Name 名称	Comment 评论
byte 字节	stop byte 停止字节	a special byte treated as a delimiter 一个作为分隔符处理的特殊字节
itf8	external id 外部 ID	id of an external block containing the byte stream 外部块的 ID，包含字节流

13.5 Beta coding: codec ID 6
13.5 Beta 编码：编解码器 ID 6

Can encode types Integer.
可以编码类型整数。

Definition 定义

Beta coding is a most common way to represent numbers in binary notation and is sometimes referred to as binary coding. The decoder reads the specified fixed number of bits (most significant first) and subtracts the offset value to get the decoded integer.
贝塔编码是以二进制表示数字的最常见方式，有时被称为二进制编码。解码器读取指定的固定数量的位（最重要的位优先），并减去偏移值以获得解码后的整数。

Parameters 参数

CRAM format defines the following parameters of beta coding:
CRAM 格式定义了 beta 编码的以下参数：

Data type 数据类型

Name 名称

Comment 评论

itf8

offset 偏移量

在解码过程中，从每个值中减去偏移量

offset is subtracted from each

value during decode

itf8

length 长度

the number of bits used
使用的位数

Examples 示例

If we have integer values in the range 10 to 15 inclusive, the largest value would traditionally need 4 bits, but with an offset of -10 we can hold values 0 to 5 , using a fixed size of 3 bits. Using fixed Offset and Length coming from the beta parameters, we decode these values as:
如果我们有范围在 10 到 15（包括 10 和 15）之间的整数值，传统上最大的值需要 4 位，但通过使用-10 的偏移量，我们可以用 3 位固定大小表示 0 到 5 的值。使用来自 beta 参数的固定偏移量和长度，我们将这些值解码为：

Offset 偏移量	Length 长度	Bits 比特	Value 值
-10	3	000	10
-10	3	001	11
-10	3	010	12
-10	3	011	13
-10	3	100	14
-10	3	101	15

13.6 Subexponential coding: codec ID 7
13.6 亚指数编码：编解码器 ID 7

Can encode types Integer.
可以编码类型整数。

Definition 定义

Subexponential coding

^{6}

is parametrized by a non-negative integer

k

. For values

n < 2^{k + 1}

subexponential coding produces codewords identical to Rice coding

^{7}

. For larger values it grows logarithmically with

n

.
亚指数编码

^{6}

由一个非负整数

k

参数化。对于值

n < 2^{k + 1}

，亚指数编码生成与 Rice 编码

^{7}

相同的代码字。对于更大的值，它以

n

的对数方式增长。

Encoding 编码

Add offset to $n$ .
将偏移量添加到 $n$ 。
Determine $u$ and $b$ values from $n$
从 $n$ 确定 $u$ 和 $b$ 的值

b = {\begin{cases} k & if n < 2^{k} \\ ⌊ \log_{2} n ⌋ & if n \geq 2^{k} \end{cases} u = {\begin{cases} 0 & if n < 2^{k} \\ b - k + 1 & if n \geq 2^{k} \end{cases}

Write $u$ in unary form; $u 1$ bits followed by a single 0 bit.
以一元形式写 $u$ ； $u 1$ 位后跟一个 0 位。
Write the bottom $b$ -bits of $n$ in binary form.
以二进制形式写出 $n$ 的最低 $b$ 位。

Decoding 解码

Read $u$ in unary form, counting the number of leading 1 s (prefix) in the codeword (discard the trailing 0 bit).
以一元形式读取 $u$ ，计算码字中前导 1 的数量（前缀）（忽略尾随的 0 位）。
Determine $n$ via: 通过以下方式确定 $n$ ：
(a) if $u = 0$ then read $n$ as a $k$ -bit binary number.
如果 $u = 0$ 则将 $n$ 读取为 $k$ 位二进制数。
(b) if $u \geq 1$ then read $x$ as a $(u + k - 1)$ -bit binary. Let $n = 2^{u + k - 1} + x$ .
(b) 如果 $u \geq 1$ 则将 $x$ 读取为 $(u + k - 1)$ 位二进制。设 $n = 2^{u + k - 1} + x$ 。
Subtract offset from $n$ .
从 $n$ 中减去偏移量。

Examples 示例

Number 数字	Codeword, $k = 0$ 代码字， $k = 0$	Codeword, $k = 1$ 代码字， $k = 1$	Codeword, $k = 2$ 代码字， $k = 2$
0	0	00	000
1	10	01	001
2	1100	100	010
3	1101	101	011
4	111000	11000	1000
5	111001	11001	1001
6	111010	11010	1010
7	111011	11011	1011
8	11110000	1110000	110000
9	11110001	1110001	110001
10	11110010	1110010	110010

Parameters 参数

Data type 数据类型	Name 名称	Comment 评论
itf8	offset 偏移量	offset is subtracted from each value during decode 在解码过程中，从每个值中减去偏移量
itf8	k	the order of the subexponential coding 子指数编码的顺序

13.7 Gamma coding: codec ID 9
13.7 伽马编码：编解码器 ID 9

Can encode types Integer.
可以编码类型整数。

Definition 定义

Elias gamma code is a prefix encoding of positive integers. This is a combination of unary coding and beta coding. The first is used to capture the number of bits required for beta coding to capture the value.
Elias gamma 码是正整数的前缀编码。这是单一编码和贝塔编码的组合。前者用于捕获贝塔编码所需的位数，以捕获值。

Encoding 编码

Write it in binary.
用二进制写。
Subtract 1 from the number of bits written in step 1 and prepend that many zeros.
从步骤 1 中写入的位数中减去 1，并在前面添加那么多零。
An equivalent way to express the same process:
表达相同过程的等效方式：
Separate the integer into the highest power of 2 it contains $(2 N)$ and the remaining $N$ binary digits of the integer.
将整数分解为其包含的最高 2 的幂 $(2 N)$ 和整数的剩余 $N$ 个二进制位。
Encode $N$ in unary; that is, as $N$ zeroes followed by a one.
将 $N$ 编码为一元；即， $N$ 个零后跟一个一。
Append the remaining $N$ binary digits to this representation of $N$ .
将剩余的 $N$ 个二进制位附加到 $N$ 的表示中。

Decoding 解码

Read and count 0 s from the stream until you reach the first 1 . Call this count of zeroes $N$ .
从流中读取并计数 0，直到遇到第一个 1。将这个零的计数称为 $N$ 。
Considering the one that was reached to be the first digit of the integer, with a value of $2 N$ , read the remaining $N$ digits of the integer.
考虑到达到的那个是整数的第一位，值为 $2 N$ ，读取整数的其余 $N$ 位。

Examples 示例

Value 值	Codeword 代码词
1	1
2	010
3	011
4	00100

Parameters 参数

Data type 数据类型

Name 名称

Comment 评论

itf8

offset 偏移量

解码后从每个值中减去的偏移量

offset to subtract from each

value after decode

13.8 DEPRECATED: Golomb coding: codec ID 2
13.8 已弃用：Golomb 编码：编解码器 ID 2

Definition 定义

Golomb encoding is a prefix encoding optimal for representation of random positive numbers following geometric distribution.
高隆布编码是一种前缀编码，最适合表示遵循几何分布的随机正数。

Encoding 编码

Fix the parameter $M$ to an integer value.
将参数 $M$ 修复为整数值。
For $N$ , the number to be encoded, find
对于 $N$ ，要编码的数字，找到
(a) quotient $q = ⌊ N / M ⌋$ (a) 商 $q = ⌊ N / M ⌋$
(b) remainder $r = N mod M$ (b) 余数 $r = N mod M$
Generate Codeword 生成代码词
(a) The Code format: <Quotient Code><Remainder Code>, where
（a）代码格式：<商代码><余数代码>，其中
(b) Quotient Code (in unary coding)
(b) 商码（单一编码）
i. Write a $q$ -length string of 1 bits
编写一个 $q$ 长度的 1 位字符串
ii. Write a 0 bit
ii. 写入 0 位
© Remainder Code (in truncated binary encoding)
© 剩余代码（以截断二进制编码）

Set

b = ⌈ \log_{2} (M) ⌉

设置

b = ⌈ \log_{2} (M) ⌉

i. If

r < 2^{b} - M

code

r

as plain binary using

b - 1

bits.
如果

r < 2^{b} - M

代码

r

作为使用

b - 1

位的纯二进制。
ii. If

r \geq 2^{b} - M

code the number

r + 2^{b} - M

in plain binary representation using

b

bits.
ii. 如果

r \geq 2^{b} - M

使用

b

位以普通二进制表示数字

r + 2^{b} - M

。

Decoding 解码

Read $q$ via unary coding: count the number of 1 bits and consume the following 0 bits.
通过一元编码读取 $q$ ：计算 1 位的数量并消耗后续的 0 位。
Set $b = ⌈ \log_{2} (M) ⌉$ 设置 $b = ⌈ \log_{2} (M) ⌉$
Read $r$ via $b - 1$ bits of binary coding
通过 $b - 1$ 位二进制编码读取 $r$
If $r \geq 2^{b} - M$ 如果 $r \geq 2^{b} - M$
(a) Read 1 single bit, $x$ .
(a) 读取 1 个单独的位， $x$ 。
(b) Set $r = r * 2 + x - (2^{b} - M)$ (b) 设置 $r = r * 2 + x - (2^{b} - M)$
Value is $q * M + r -$ offset 值为 $q * M + r -$ 偏移量

Examples 示例

Number 数字

代码字，M=10，（因此 b=4）

Codeword, M=10,

(thus b=4)

0000

0100

10000

1101100

11110010

Parameters 参数

Golomb coding takes the following parameters:
Golomb 编码采用以下参数：

Data type 数据类型

Name 名称

Comment 评论

itf8

offset 偏移量

offset is added to each value
每个值都添加了偏移量

itf8

高隆布参数（箱子数量）

the golomb parameter (number

of bins)

13.9 DEPRECATED: Golomb-Rice coding: codec ID 8
13.9 已弃用：Golomb-Rice 编码：编解码器 ID 8

Can encode types Integer.
可以编码类型整数。
Note this codec has not been used in any known CRAM implementation since before CRAM v1.0. Nor is it implemented in some of the major software. Therefore its use is not recommended.
请注意，自 CRAM v1.0 之前，该编解码器在任何已知的 CRAM 实现中都未被使用。它在一些主要软件中也未被实现。因此，不建议使用它。
Golomb-Rice coding is a special case of Golomb coding when the M parameter is a power of 2. The reason for this coding is that the division operations in Golomb coding can be replaced with bit shift operators as well as avoiding the extra

r < 2^{b} - M

check.
Golomb-Rice 编码是 Golomb 编码的特例，当 M 参数是 2 的幂时。使用这种编码的原因是，Golomb 编码中的除法操作可以用位移运算符替代，并且避免了额外的

r < 2^{b} - M

检查。

14 External compression methods
14 外部压缩方法

External encoding operates on bytes only. Therefore any data series must be translated into bytes before sending data into an external block. The following methods are defined. Exact definitions of these methods are in their respective internet links or the ancillary CRAMcodecs document found along side this specification.
外部编码仅在字节上操作。因此，任何数据序列必须在将数据发送到外部块之前转换为字节。定义了以下方法。这些方法的确切定义在各自的互联网链接中或在本规范旁边找到的辅助 CRAMcodecs 文档中。

Integer values are written as ITF8, which then can be translated into an array of bytes.
整数值以 ITF8 格式写入，然后可以转换为字节数组。
Strings, like read name, are translated into bytes according to UTF8 rules. In most cases these should coincide with ASCII, making the translation trivial.
字符串，如读取名称，按照 UTF8 规则转换为字节。在大多数情况下，这些应该与 ASCII 一致，使得转换变得简单。

Each method has an associated numeric code which is defined in Section 8.
每个方法都有一个相关的数字代码，该代码在第 8 节中定义。

14.1 Gzip

The Gzip specification is defined in RFC 1952. Gzip in turn is an encapsulation on the Deflate algorithm defined in RFC 1951.
Gzip 规范在 RFC 1952 中定义。Gzip 反过来是对 RFC 1951 中定义的 Deflate 算法的封装。

14.2 Bzip2

First available in CRAM v2.0.
首次在 CRAM v2.0 中可用。
Bzip2 is a compression method utilising the Burrows Wheeler Transform, Move To Front transform, Run Length Encoding and a Huffman entropy encoder. It is often superior to Gzip for textual data.
Bzip2 是一种压缩方法，利用了 Burrows Wheeler 变换、前移变换、游程编码和霍夫曼熵编码。对于文本数据，它通常优于 Gzip。
An informal format specification exists:
存在一种非正式的格式规范：
https://github.com/dsnet/compress/blob/master/doc/bzip2-format.pdf

14.3 LZMA

First available in CRAM v3.0.
首次在 CRAM v3.0 中可用。
LZMA is the Lempel-Ziv Markov chain algorithm. CRAM uses the xz Stream format to encapsulate this algorithm, as defined in https://tukaani.org/xz/xz-file-format.txt.
LZMA 是 Lempel-Ziv 马尔可夫链算法。CRAM 使用 xz 流格式来封装该算法，具体定义见 https://tukaani.org/xz/xz-file-format.txt。

14.4 rANS4x8 codec 14.4 rANS4x8 编解码器

First available in CRAM v3.0.
首次在 CRAM v3.0 中可用。
rANS is the range-coder variant of the Asymmetric Numerical System

^{8}

.
rANS 是不对称数值系统

^{8}

的范围编码变体。
" 4 x 8 " refers to 4 -way interleaving with 8 -bit renormalisation.
"4 x 8" 指的是 4 路交错与 8 位重新归一化。
This variant of rANS first appeared in CRAM v3.0.
这种 rANS 的变体首次出现在 CRAM v3.0 中。
Details of this algorithm have been moved to the CRAMcodecs document.
该算法的详细信息已移至 CRAMcodecs 文档。

14.5 rANS4x16 codec 14.5 rANS4x16 编解码器

First available in CRAM v3.1.
首次在 CRAM v3.1 中可用。
"

4 \times 16

" refers to 4 -way interleaving with 16 -bit renormalisation.
“

4 \times 16

”指的是 4 路交错与 16 位重新归一化。
This variant of rANS first appeared in CRAM v3.1.
这种 rANS 的变体首次出现在 CRAM v3.1 中。
Details of this algorithm are listed in the CRAMcodecs document.
该算法的详细信息列在 CRAMcodecs 文档中。

14.6 adaptive arithemtic coding
14.6 自适应算术编码

First available in CRAM v3.1.
首次在 CRAM v3.1 中可用。
An entropy encoder that is slower but slightly more concise than rANS. It achieves this by adapting the probabilities as it compresses and decompresses instead of using a fixed table.
一种熵编码器，速度较慢但比 rANS 略为简洁。它通过在压缩和解压缩时调整概率，而不是使用固定表来实现这一点。

Details of this algorithm are listed in the CRAMcodecs document.
该算法的详细信息列在 CRAMcodecs 文档中。

14.7 fqzcomp codec 14.7 fqzcomp 编解码器

First available in CRAM v3.1.
首次在 CRAM v3.1 中可用。
This is a method dedicated to compression of quality values.
这是一个专门用于压缩质量值的方法。
Details of this algorithm are listed in the CRAMcodecs document.
该算法的详细信息列在 CRAMcodecs 文档中。

14.8 name tokeniser 14.8 名称标记器

First available in CRAM v3.1.
首次在 CRAM v3.1 中可用。
This is a method dedicated to compression of read names.
这是一个专门用于压缩读取名称的方法。
Details of this algorithm are listed in the CRAMcodecs document.
该算法的详细信息列在 CRAMcodecs 文档中。

15 Appendix 15 附录

15.1 Choosing the container size
15.1 选择容器大小

CRAM format does not constrain the size of the containers. However, the following should be considered when deciding the container size:
CRAM 格式不限制容器的大小。然而，在决定容器大小时应考虑以下因素：

Data can be compressed better by using larger containers
数据可以通过使用更大的容器来更好地压缩
Random access performance is better for smaller containers
随机访问性能在较小的容器中更好
Streaming is more convenient for small containers
流式传输对小容器来说更方便
Applications typically buffer containers into memory
应用程序通常将容器缓冲到内存中

We recommend 1 megabyte containers. They are small enough to provide good random access and streaming performance while being large enough to provide good compression. 1 MB containers are also small enough to fit into the L2 cache of most modern CPUs.
我们推荐 1 兆字节的容器。它们足够小，可以提供良好的随机访问和流媒体性能，同时又足够大，可以提供良好的压缩。1MB 的容器也足够小，可以适应大多数现代 CPU 的 L2 缓存。
Some simplified examples are provided below to fit data into 1 MB containers.
以下提供了一些简化的示例，以将数据适配到 1 MB 的容器中。

Unmapped short reads with bases, read names, recalibrated and original quality scores
未映射的短读段，包括碱基、读取名称、重新校准和原始质量分数

We have 10,000 unmapped short reads (100bp) with read names, recalibrated and original quality scores. We estimate 0.4 bits/base (read names) +0.4 bits/base (bases) +3 bits/base (recalibrated quality scores) +3 bits/base (original quality scores)

\approx 7

bits/base. Space estimate is

10000 \times 100 \times 7

bits

\approx 0.9 MB

. Data could be stored in a single container.
我们有 10,000 个未映射的短读段（100bp），带有读取名称、重新校准和原始质量分数。我们估计 0.4 位/碱基（读取名称）+0.4 位/碱基（碱基）+3 位/碱基（重新校准的质量分数）+3 位/碱基（原始质量分数）

\approx 7

位/碱基。空间估计为

10000 \times 100 \times 7

位

\approx 0.9 MB

。数据可以存储在一个单一的容器中。

Unmapped long reads with bases, read names and quality scores
未映射的长读数，包括碱基、读名和质量分数

We have 10,000 unmapped long reads ( 10 kb ) with read names and quality scores. We estimate: 0.4 bits/base (bases) +3 bits/base (original quality scores)

\approx 3.5

bits/base. Space estimate is

10000 \times 10000 \times 3.5

bits

\approx

42 MB . Data could be stored in

42 \times 1 MB

containers.
我们有 10,000 个未映射的长读数（10 kb），带有读取名称和质量分数。我们估计：0.4 位/碱基（碱基）+ 3 位/碱基（原始质量分数）

\approx 3.5

位/碱基。空间估计为

10000 \times 10000 \times 3.5

位

\approx

42 MB。数据可以存储在

42 \times 1 MB

容器中。

Mapped short reads with bases, pairing and mapping information
映射的短读段，包含碱基、配对和映射信息

We have 250,000 mapped short reads ( 100 bp ) with bases, pairing and mapping information. We estimate the compression to be 0.2 bits/base. Space estimate is

250000 \times 100 \times 0.2

bits

\approx 0.6 MB

. Data could be stored in a single container.
我们有 250,000 个映射的短读数（100 bp），包含碱基、配对和映射信息。我们估计压缩率为 0.2 位/碱基。空间估计为

250000 \times 100 \times 0.2

位

\approx 0.6 MB

。数据可以存储在一个单一的容器中。

Embedded reference sequences
嵌入式参考序列

We have a reference sequence ( 10 Mb ). We estimate the compression to be 2 bits/base. Space estimate is

10000000 \times 2

bits

\approx 2.4 MB

. Data could be written into three containers:

1 MB + 1 MB + 0.4 MB

.
我们有一个参考序列（10 Mb）。我们估计压缩为每个碱基 2 位。空间估计为

10000000 \times 2

位

\approx 2.4 MB

。数据可以写入三个容器：

1 MB + 1 MB + 0.4 MB

。

15.2 CRAM History 15.2 CRAM 历史

Pre-CRAM: 2010 预 CRAM：2010

The primary concepts and ideas of CRAM stem from work at the European Bioinformatics Institute in 2010 and 2011, published in:
CRAM 的主要概念和思想源于 2010 年和 2011 年在欧洲生物信息学研究所的工作，发表在：

Markus Hsi-Yang Fritz, Rasko Leinonen, Guy Cochrane, and Ewan Birney, Efficient storage of high
马库斯·希-杨·弗里茨、拉斯科·莱诺宁、盖·科克伦和尤安·伯尼，高效存储高throughput DNA sequencing data using reference-based compression, Genome Res. 2011 21:
通过基于参考的压缩处理 DNA 测序数据，基因组研究。2011 21: $734 - 740$ ; doi:10.1101/gr.114819.110; PMID:21245279.

CRAM 0.x: 2011

Vadim Zalunin implemented the ideas in the paper, now named CRAM, in the Java CRAMtools package. This included versions from 0.3 to

{0.86}^{9}

.
Vadim Zalunin 在名为 CRAM 的论文中实现了这些想法，现已在 Java CRAMtools 包中实现。这包括从 0.3 到

{0.86}^{9}

的版本。

CRAM 1.0: 2012 CRAM 1.0：2012

The first official launch of the CRAM specification, in the Java CRAMtools package

^{10}

CRAM 规范的首次官方发布，在 Java CRAMtools 包中

^{10}

This was publicised at https://github.com/enasequence/cramtools.
此信息已在 https://github.com/enasequence/cramtools 上公开。

CRAM 2.0: 2013 CRAM 2.0：2013

Reimplementing CRAM in

C^{11}

exposed a number of issues with the 1.0 specification and disparities between the specification text and the Java implementation. CRAM 2.0 unified implementation with specification.
在

C^{11}

中重新实现 CRAM 暴露了 1.0 规范的一些问题，以及规范文本与 Java 实现之间的差异。CRAM 2.0 统一了实现与规范。

Other changes included: 其他更改包括：

Support for multiple references per container, to permit storage of highly fragmented assemblies.
支持每个容器多个引用，以允许存储高度碎片化的程序集。
Soft-clips and inserted bases moved to their own separate data-series instead of sharing one.
软剪接和插入碱基移至各自独立的数据系列，而不是共享一个。
Slice headers contain meta-data tracking the number of records and bases.
切片头包含跟踪记录数量和基础的元数据。
Corrected the BF (bam flag) data series to match the BAM specification.
修正了 BF（bam 标志）数据系列以符合 BAM 规范。
Improved encoding of auxiliary tags.
改进了辅助标签的编码。

CRAM 2.1: 2014 CRAM 2.1：2014

This is the first version to appear in HTSJDK (version 1.127), ported from the Java CRAMtools package.
这是在 HTSJDK 中出现的第一个版本（版本 1.127），移植自 Java CRAMtools 包。

EOF blocks are added in order to spot truncated files.
EOF 块被添加以便于识别截断的文件。

CRAM 3.0: 2014 CRAM 3.0：2014
Primarily this is an optimisation of size and speed.
主要这是对大小和速度的优化。

Inclusion of LZMA compression library.
包含 LZMA 压缩库。
Inclusion of the custom rANS Order-0 and Order-1 entropy encoders.
包含自定义的 rANS 0 阶和 1 阶熵编码器。
Checksums added to all file format structures to ensure data integrity.
所有文件格式结构都添加了校验和，以确保数据完整性。

CRAM 3.1: 2023 CRAM 3.1：2023
Note: the formal draft appeared in 2019, and was initially demonstrated in 2016.
注意：正式草案于 2019 年出现，并于 2016 年首次演示。
This adds new EXTERNAL compression methods, described in the separate CRAMcodecs document, and expands the list of permitted “methods” in the CRAM Block structure.
这增加了新的外部压缩方法，详见单独的 CRAMcodecs 文档，并扩展了 CRAM 块结构中允许的“方法”列表。
The aim of the new compression methods is improved compression, both performance with the newer SIMD rANS implementation and file size with custom name tokeniser and quality codec.
新压缩方法的目标是提高压缩性能，既包括使用更新的 SIMD rANS 实现的性能，也包括通过自定义名称分词器和质量编解码器来减小文件大小。

The format is otherwise identical to 3.0 .
格式与 3.0 完全相同。

15.3 Contributors and Acknowledgements
15.3 贡献者与致谢

Markus Fritz, Rasko Leinonen, Guy Cochrane and Ewan Birney (EBI): Initial ideas behind CRAM.
马库斯·弗里茨、拉斯科·莱农宁、盖·科克伦和尤安·伯尼（EBI）：CRAM 背后的初步想法。
Vadim Zalunin (EBI): Initial JAVA implementation of CRAM and previous maintainer of CRAM specification.
Vadim Zalunin (EBI)：CRAM 的初始 JAVA 实现及 CRAM 规范的前维护者。
James Bonfield (Sanger Institute): Initial C implementation of CRAM and current maintainer of CRAM specification.
詹姆斯·邦菲尔德（桑格研究所）：CRAM 的初始 C 实现者及当前 CRAM 规范的维护者。
Joel Thibault (Broad Institute): previous maintainer of CRAM specification.
Joel Thibault（布罗德研究所）：CRAM 规范的前维护者。
Chris Norman (Broad Institute): previous maintainer of CRAM specification and worked on the HTSJDK implementation.
克里斯·诺曼（布罗德研究所）：CRAM 规范的前维护者，并参与了 HTSJDK 实现的工作。
Robert Buels (UC Berkeley): First JavaScript implementation of CRAM
罗伯特·比尔斯（加州大学伯克利分校）：CRAM 的第一个 JavaScript 实现
Michael Macias (St Jude Children’s Research Hospital): First Rust implementation of CRAM
迈克尔·马西亚斯（圣犹大儿童研究医院）：CRAM 的首个 Rust 实现
Other specification contributors include: John Marshall, Rishi Nag, Kenta Sato, Artem Tarasov and Jason Travis.
其他规范贡献者包括：John Marshall、Rishi Nag、Kenta Sato、Artem Tarasov 和 Jason Travis。
Plus a big thank you to everyone who has raised GitHub issues and/or helped us improve the specification in other ways.
非常感谢所有提出 GitHub 问题和/或以其他方式帮助我们改进规范的每一个人。

$^{1}$ Markus Hsi-Yang Fritz, Rasko Leinonen, Guy Cochrane, and Ewan Birney, Efficient storage of high throughput DNA sequencing data using reference-based compression, Genome Res. 2011 21: 734-740; doi:10.1101/gr.114819.110; PMID:21245279.
$^{1}$ 马库斯·希-杨·弗里茨、拉斯科·莱农、盖·科克伦和尤安·伯尼，基于参考的压缩高通量 DNA 测序数据的高效存储，《基因组研究》。2011 年 21: 734-740；doi:10.1101/gr.114819.110；PMID:21245279。
$^{a}$ Formerly MAPPED_SLICE_HEADER. Now used by all slice headers regardless of mapping status.
$^{a}$ 以前是 MAPPED_SLICE_HEADER。现在所有切片头都使用它，无论映射状态如何。
$^{2}$ The precise order is defined in section 10 .
$^{2}$ 精确的顺序在第 10 节中定义。
$^{3}$ Unmapped reads can be placed or unplaced. By placed unmapped read we mean a read that is unmapped according to bit $0 \times 4$ of the BF (BAM bit flags) data series, but has position fields filled in, thus “placing” it on a reference sequence. In contrast, unplaced unmapped reads have have a reference sequence ID of -1 and alignment position of 0 .
$^{3}$ 未映射的读取可以是已放置或未放置的。我们所说的已放置未映射读取是指根据 BF（BAM 位标志）数据系列的位 $0 \times 4$ 未映射的读取，但其位置信息字段已填写，从而将其“放置”在参考序列上。相反，未放置的未映射读取的参考序列 ID 为 -1，且对齐位置为 0。
$^{4}$ Interleaving can sometimes provide better compression, however it also adds dependency between types of data meaning it is not possible to selectively decode one data series if it co-locates with another data series in the same block.
$^{4}$ 交错有时可以提供更好的压缩，但它也增加了数据类型之间的依赖关系，这意味着如果一个数据系列与另一个数据系列在同一块中共存，就无法选择性地解码一个数据系列。
$^{5}$ https://en.wikipedia.org/wiki/Canonical_Huffman_code
$^{6}$ Fast progressive lossless image compression, Paul G. Howard and Jeffrey Scott Vitter, 1994. http://www.ittc.ku.edu/ jsv/ Papers/HoV94.progressive_FELICS.pdf
$^{6}$ 快速渐进无损图像压缩，保罗·G·霍华德和杰弗里·斯科特·维特，1994 年。http://www.ittc.ku.edu/jsv/Papers/HoV94.progressive_FELICS.pdf
$^{7}$ https://en.wikipedia.org/wiki/Golomb_coding#Rice_coding
$^{8}$ J. Duda, Asymmetric numeral systems: entropy coding combining speed of Huffman coding with compression rate of arithmetic coding, http://arxiv.org/abs/1311.2540
$^{8}$ J. Duda, 非对称数字系统：结合霍夫曼编码速度与算术编码压缩率的熵编码，http://arxiv.org/abs/1311.2540
$^{9}$ https://github.com/vadimzalunin/crammer/releases
$^{10}$ https://github.com/enasequence/cramtools
$^{11}$ Staden IO_Lib 1.13.0 and later HTSlib 0.2.0
$^{11}$ Staden IO_Lib 1.13.0 及更高版本 HTSlib 0.2.0

CRAM format specification (version 3.1) CRAM 格式规范（版本 3.1）

Abstract 摘要

1 Overview 1 概述

2 Data types 2 数据类型

2.1 Logical data types2.1 逻辑数据类型

Byte 字节

Integer 整数

Long 长

Array 数组

2.2 Writing bits to a bit stream2.2 将位写入位流

Example of writing to bit stream写入位流的示例

Note on writing to bit stream写入比特流的注意事项

2.3 Writing bytes to a byte stream2.3 将字节写入字节流

Boolean (bool) 布尔值 (bool)

Integer (int32) 整数 (int32)

Long (int64) 长整型 (int64)

ITF-8 integer (itf8) ITF-8 整数 (itf8)

LTF-8 long (ltf8) LTF-8 长 (ltf8)

Array (array<type>) 数组 (array<类型>)

Encoding 编码

String 字符串

3 Encodings 3 编码

4 Checksums 4 个校验和

4.1 CRC32

4.2 CRC32 sum 4.2 CRC32 校验和

5 File structure 5 文件结构

6 File definition 6 文件定义

7 Container header structure7 容器头结构

7.1 CRAM header container7.1 CRAM 头部容器

8 Block structure 8 块结构

8.1 Block content types8.1 块内容类型

8.2 Block content id8.2 块内容 ID

Data blocks 数据块

8.3 CRAM header block(s)8.3 CRAM 头块

8.4 Compression header block8.4 压缩头块

Preservation map 保护地图

Data series encodings 数据系列编码

Tag encodings 标签编码

Tag values 标签值

8.5 Slice header block8.5 切片头块

8.6 Core data block8.6 核心数据块

8.7 External data blocks8.7 外部数据块

9 End of file container9 文件结束容器

10 Record structure 10 记录结构

10.1 CRAM record 10.1 CRAM 记录

BAM bit flags (BF data series)BAM 位标志 (BF 数据系列)

CRAM bit flags (CF data series)CRAM 位标志 (CF 数据系列)

Decode pseudocode 解码伪代码

10.2 CRAM positional data10.2 CRAM 位置数据

10.3 Read names (RN data series)10.3 读取名称（RN 数据系列）

10.4 Mate records10.4 Mate 记录

Next mate bit flags (MF data series)下一个配对位标志（MF 数据系列）

Decode mate pseudocode 解码配对伪代码

10.5 Auxiliary tags 10.5 辅助标签

10.6 Mapped reads 10.6 映射读取

Read feature records 读取特性记录

Read feature codes 读取功能代码

Base substitution codes (BS data series)基本替代代码（BS 数据系列）

Substitution Matrix Format替代矩阵格式

Substitution Code Assignment替代代码分配

Decode mapped read pseudocode解码映射读取伪代码

10.7 Unmapped reads10.7 未映射的读数

11 Reference sequences11 参考序列

12 Indexing 12 索引

General notes 一般说明

CRAM index CRAM 索引

BAM index BAM 索引

13 Encodings 13 编码

13.1 Introduction 13.1 介绍

Offset 偏移量

13.2 EXTERNAL: codec ID 113.2 外部: 编解码器 ID 1

Parameters 参数

13.3 Huffman coding: codec ID 313.3 哈夫曼编码：编解码器 ID 3

Can encode types Byte, Integer.可以编码类型 Byte、Integer。

Canonical code computation规范代码计算

Examples 示例

Parameters 参数

13.4 Byte array coding13.4 字节数组编码

BYTE_ARRAY_LEN: codec ID 4BYTE_ARRAY_LEN: 编解码器 ID 4

BYTE_ARRAY_STOP: codec ID 5BYTE_ARRAY_STOP: 编解码器 ID 5

CRAM format specification (version 3.1)
CRAM 格式规范（版本 3.1）

2.1 Logical data types
2.1 逻辑数据类型

2.2 Writing bits to a bit stream
2.2 将位写入位流

Example of writing to bit stream
写入位流的示例

Note on writing to bit stream
写入比特流的注意事项

2.3 Writing bytes to a byte stream
2.3 将字节写入字节流

7 Container header structure
7 容器头结构

7.1 CRAM header container
7.1 CRAM 头部容器

8.1 Block content types
8.1 块内容类型

8.2 Block content id
8.2 块内容 ID

8.3 CRAM header block(s)
8.3 CRAM 头块

8.4 Compression header block
8.4 压缩头块

8.5 Slice header block
8.5 切片头块

8.6 Core data block
8.6 核心数据块

8.7 External data blocks
8.7 外部数据块

9 End of file container
9 文件结束容器

BAM bit flags (BF data series)
BAM 位标志 (BF 数据系列)

CRAM bit flags (CF data series)
CRAM 位标志 (CF 数据系列)

10.2 CRAM positional data
10.2 CRAM 位置数据

10.3 Read names (RN data series)
10.3 读取名称（RN 数据系列）

10.4 Mate records
10.4 Mate 记录

Next mate bit flags (MF data series)
下一个配对位标志（MF 数据系列）

Base substitution codes (BS data series)
基本替代代码（BS 数据系列）

Substitution Matrix Format
替代矩阵格式

Substitution Code Assignment
替代代码分配

Decode mapped read pseudocode
解码映射读取伪代码

10.7 Unmapped reads
10.7 未映射的读数

11 Reference sequences
11 参考序列

13.2 EXTERNAL: codec ID 1
13.2 外部: 编解码器 ID 1

13.3 Huffman coding: codec ID 3
13.3 哈夫曼编码：编解码器 ID 3

Can encode types Byte, Integer.
可以编码类型 Byte、Integer。

Canonical code computation
规范代码计算

13.4 Byte array coding
13.4 字节数组编码

BYTE_ARRAY_LEN: codec ID 4
BYTE_ARRAY_LEN: 编解码器 ID 4

BYTE_ARRAY_STOP: codec ID 5
BYTE_ARRAY_STOP: 编解码器 ID 5

13.5 Beta coding: codec ID 6
13.5 Beta 编码：编解码器 ID 6

13.6 Subexponential coding: codec ID 7
13.6 亚指数编码：编解码器 ID 7

13.7 Gamma coding: codec ID 9
13.7 伽马编码：编解码器 ID 9

13.8 DEPRECATED: Golomb coding: codec ID 2
13.8 已弃用：Golomb 编码：编解码器 ID 2

13.9 DEPRECATED: Golomb-Rice coding: codec ID 8
13.9 已弃用：Golomb-Rice 编码：编解码器 ID 8

14 External compression methods
14 外部压缩方法

14.6 adaptive arithemtic coding
14.6 自适应算术编码

15.1 Choosing the container size
15.1 选择容器大小

Unmapped short reads with bases, read names, recalibrated and original quality scores
未映射的短读段，包括碱基、读取名称、重新校准和原始质量分数

Unmapped long reads with bases, read names and quality scores
未映射的长读数，包括碱基、读名和质量分数

Mapped short reads with bases, pairing and mapping information
映射的短读段，包含碱基、配对和映射信息

Embedded reference sequences
嵌入式参考序列

15.3 Contributors and Acknowledgements
15.3 贡献者与致谢