htsget-search

通过处理生物信息学文件为 htsget-rs 创建 URL 票。它

• 接收 htsget 查询并生成 htsget URL 票。
• 使用 noodles 处理文件。
• 提供了一个存储抽象层，可以表示本地或云中的数据。

概览

此 crate 是 htsget-rs 与生物信息学文件交互和处理的主体机制。它通过使用 noodles 查询文件及其索引来实现。它分为两个模块

• htsget：其中包含消除文件格式之间共性的抽象。与特定文件格式代码一起，这定义了一个处理 htsget 请求核心逻辑的接口。
• storage：它实现了一个基于对象的存储抽象，可以在本地或云中实现，用于获取数据。

未来的工作可能会将这些两个模块拆分为单独的 crates。

特质抽象

这两个模块的设计旨在消除文件格式之间的共性，并易于实现额外功能。存储模块是存储后端的所在地。此模块充当 htsget 协议中所述的“数据服务器”，实现额外的后端需要实现 Storage 特质。此特质由 htsget 使用，以获取底层文件并查询数据。例如，类似于 S3Storage，可以添加 Cloudflare R2 存储。

请注意，存储后端负责允许用户检索由票据服务器返回的URL票据。在LocalStorage的情况下，这意味着需要单独的data_server，它可以使用HTTP服务文件。S3Storage简单地返回预签名S3 URL。

使用方法

作为应用程序运行htsget-rs

该crate负责处理生物信息学文件数据。它支持BAM、CRAM、VCF和BCF文件。为了使htsget-rs正常运行，文件需要按以下方式组织

• 每种文件格式都配对了一个索引。所有文件都必须有特定的扩展名。
  • BAM：文件必须以.bam结尾；与BAI索引配对，必须以.bam.bai结尾。
  • CRAM：文件必须以.cram结尾；与CRAI索引配对，必须以.cram.crai结尾。
  • VCF：文件必须以.vcf.gz结尾；与TBI索引配对，必须以.vcf.gz.tbi结尾。
  • BCF：文件必须以.bcf结尾；与CSI索引配对，必须以.bcf.csi结尾。
• 假设VCF文件是BGZF压缩的。
• BGZF压缩文件（BAM、CRAM、VCF）可以可选地也有一个GZ索引，以使字节范围更小。
  • GZI文件必须以.gzi结尾。
  • 有关GZI的更多详细信息，请参阅最小化字节范围。

这相当不灵活，未来可能会改变以允许文件和索引的任意映射。

作为库

该crate提供的两个模块具有以下功能

• htsget：HtsGet trait代表一个实体，可以根据htsget规范解析查询。htsget trait附带了一个基本模型来表示执行搜索所需组件：Query、Format、Class、Tags、Headers、Url、Response。 HtsGetFromStorage是用于处理请求的结构。
• storage：Storage trait包含用于获取数据的函数：get、range_url、head和data_url。

功能标志

该crate具有以下功能

• s3-storage：用于启用S3Storage功能。
• url-storage：用于启用UrlStorage功能。

最小化字节范围

实现htsget的一个挑战是合理地最小化响应票据中返回的字节范围的大小。由于htsget用于通过查询文件的一部分来减少客户端需要获取的数据量，因此htsget返回的数据应尽可能小。这是通过读取索引文件或底层目标文件来实现的，以确定所需的字节范围。然而，当考虑BGZF压缩文件时，这很复杂。

对于BGZF压缩文件，htsget-rs需要返回压缩字节的地址。此外，在从URL票据中拼接数据后，生成的文件必须是有效的。这意味着字节范围必须从BGZF块开始并在块结束时结束，否则拼接将不会生成有效文件。然而，索引文件（BAI、TBI、CSI）并不包含生成最小字节范围所需的所有信息。例如，考虑这个文件

• 使用对应的索引文件（BAI文件）中的所有可用数据，有14个BGZF块的位置（块开始位置、块结束位置、线性索引位置和元数据位置）
  • 4668，256721，499249，555224，627987，824361，977196，1065952，1350270，1454565，1590681，1912645，2060795和2112141。
• 仅使用这些数据，以下查询将产生这些字节范围
  • referenceName=11，start=5015000，和end=5050000
• 将产生以下字节范围
  • bytes=0-4667
  • bytes=256721-1065951
• 然而，一个同样有效的响应，具有更小的字节范围是
  • bytes=0-4667
  • bytes=256721-647345
  • bytes=824361-842100
  • bytes=977196-996014

为了生成最小的字节范围，htsget-rs需要从其他地方找到这些数据。有两种方法可以完成这个任务

• 从底层目标文件中获取数据，通过定位到BGZF的开始，并读取直到找到块的结束。
• 从辅助索引文件中获取数据，例如GZI。

目前，htsget-rs采用后一种方法，并使用GZI文件，其中包含所有BGZF开始和结束位置的信息。然而，这并不理想，因为GZI包含比htsget-rs所需更多的信息。当考虑基于云的存储时，前一种方法也存在问题，例如在S3的情况下，没有查找操作。

htsget-rs寻找生成最小字节范围所需信息的方式在未来可能会改变，因为将实施更有效的方法。例如，可以使用数据库进一步索引文件。对数据库的查询可以尽可能具有针对性，只检索所需的信息。

基准测试

由于此crate用于查询文件数据，它是htsget-rs中最关键的性能组件。因此，使用Criterion.rs编写基准测试以测试性能。通过执行以下命令运行基准测试

cargo bench -p htsget-search --all-features

或者如果您使用cargo-criterion并希望获得机器可读的JSON输出，则运行

cargo criterion --bench search-benchmarks --message-format=json -- LIGHT 1> search-benchmarks.json

许可证

此项目根据MIT许可证授权。