Lib.rs

› 数据库实现
#子命令 #变体 #工作线程 #后台处理 #vcf #命令 #查询

app varfish-server-worker

基于 Rust 的 varfish-server 工作线程

由 Manuel Holtgrewe

17 个版本 (11 个重大变更)

0.13.0 2024 年 8 月 15 日
0.12.0 2024 年 6 月 19 日
0.11.0 2024 年 2 月 27 日
0.10.2 2023 年 10 月 5 日
0.5.1 2023 年 3 月 14 日

#13 in 数据库实现

Download history 164/week @ 2024-06-17 204/week @ 2024-07-29 102/week @ 2024-08-12

每月 306 次下载

MIT 许可证

1MB
18K SLoC

Crates.io CI codecov DOI

VarFish Server Worker

[!注意] 此存储库包含在 VarFish 服务器内部运行的代码。如果您想运行自己的 VarFish 服务器，请查看 bihealth/varfish-server。

此存储库包含 VarFish 服务器用于执行某些后台任务的 worker。它们是用 Rust 编程语言编写的，以提高某些任务的执行速度。目前存在以下子命令

  • db -- 用于构建二进制（protobuf）数据库文件的子命令
  • seqvars -- 处理序列（即小/SNV/indel）变体的子命令
    • seqvars ingest -- 将单个 VCF 文件转换为与 seqvars query 一起使用的内部格式
    • seqvars query -- 执行序列变异过滤和即时注释
    • seqvars prefilter -- 通过种群频率和/或与外显子的距离限制 seqvars prefilter 的结果
    • seqvars aggregate -- 通过 seqvars ingest 写入的多个 VCF 文件进行读取，并计算携带者计数表。
  • strucvars -- 处理结构（即大变异、CNVs 等）变体的子命令
    • strucvars ingest -- 将一个或多个结构变异文件转换为与 strucvars query 一起使用
    • strucvars aggregate -- 将每个案例的结构变异编译成一个内部数据库，然后用 strucvars txt-to-bin 转换为 .bin
    • strucvars txt-to-bin -- 将由 varfish-db-downloader 下载的文本文件转换为二进制，以便在 strucvars query 命令中快速使用
    • strucvars query -- 执行结构变异过滤和即时注释

整体设计

为了运行查询，工作工具被安装到VarFish服务器镜像中，并以可执行文件的形式运行。内部，VarFish服务器在存储在S3存储中的VCF文件上工作。

对于导入，用户将服务器访问权限授予导入的VCF文件。然后，服务器将使用工作可执行文件使用{seqvars,strucvars} ingest将数据摄入内部格式。这些文件随后存储在内部S3存储中。

对于查询，服务器将创建一个查询JSON文件，然后将此查询JSON文件与内部文件一起传递给工作可执行文件。工作可执行文件将创建一个结果文件，该文件可以被服务器直接导入并显示给用户。

未来的版本可能提供持久运行的HTTP/REST服务器，提供无需启动成本的功能。

seqvars ingest命令

此命令将单个VCF文件（来自支持的变异调用器）作为输入，并将其转换为用于进一步查询的文件。该命令解释以下字段，这些字段由常用的变异调用器（如GATK UnifiedGenotyper、GATK HaplotypeCaller和Illumina Dragen）写入。

  • FORMAT/GT -- 基因型
    • 以下GT值被写入为0/0、0/1、1/0、1/1、0|0、0|1、1|0、1|1、./.、.|.、.
    • 不会输出不叫（.）和已调用等位基因的组合
  • FORMAT/GQ -- 基因型质量
  • FORMAT/DP -- 总读取覆盖度
  • FORMAT/AD -- 等位基因深度，每个等位基因一个值（包括参考0）
  • FORMAT/PS -- 物理相分离信息，由GATK HaplotypeCaller在GVCF工作流程和Dragen变异调用器中写入
  • FORMAT/SQ -- 每个替代等位基因的“体细胞质量”，由Illumina Dragen变异调用器写入
    • 此字段将按FORMAT/GQ写入

seqvars ingest命令将使用以下信息注释变异

  • gnomAD基因组和外显子组等位基因频率
  • gnomAD-mtDNA和HelixMtDb等位基因频率
  • 遵循VCF ANN字段标准的功能注释
    • Gene_Name 以 HGNC 符号表示。
    • Gene_ID 以 HGNC ID 表示。

命令将为输入中的每个变体等位基因和每个受影响的基因生成一行输出。也就是说，如果两个变体等位基因影响两个基因，则输出文件中将写入四条记录。将输出一个影响最高的注释。

总的来说，除了 ##contig=<ID=.,length=.> 行之外，该命令还将输出以下标题行。

##fileformat=VCFv4.2
##FILTER=<ID=PASS,Description="All filters passed">
##INFO=<ID=gnomad_exomes_an,Number=1,Type=Integer,Description="Number of alleles in gnomAD exomes">
##INFO=<ID=gnomad_exomes_hom,Number=1,Type=Integer,Description="Number of hom. alt. carriers in gnomAD exomes">
##INFO=<ID=gnomad_exomes_het,Number=1,Type=Integer,Description="Number of het. alt. carriers in gnomAD exomes">
##INFO=<ID=gnomad_exomes_hemi,Number=1,Type=Integer,Description="Number of hemi. alt. carriers in gnomAD exomes">
##INFO=<ID=gnomad_genomes_an,Number=1,Type=Integer,Description="Number of alleles in gnomAD genomes">
##INFO=<ID=gnomad_genomes_hom,Number=1,Type=Integer,Description="Number of hom. alt. carriers in gnomAD genomes">
##INFO=<ID=gnomad_genomes_het,Number=1,Type=Integer,Description="Number of het. alt. carriers in gnomAD genomes">
##INFO=<ID=gnomad_genomes_hemi,Number=1,Type=Integer,Description="Number of hemi. alt. carriers in gnomAD genomes">
##INFO=<ID=helix_an,Number=1,Type=Integer,Description="Number of alleles in HelixMtDb">
##INFO=<ID=helix_hom,Number=1,Type=Integer,Description="Number of hom. alt. carriers in HelixMtDb">
##INFO=<ID=helix_het,Number=1,Type=Integer,Description="Number of het. alt. carriers in HelixMtDb">
##INFO=<ID=ANN,Number=.,Type=String,Description="Functional annotations: 'Allele | Annotation | Annotation_Impact | Gene_Name | Gene_ID | Feature_Type | Feature_ID | Transcript_BioType | Rank | HGVS.c | HGVS.p | cDNA.pos / cDNA.length | CDS.pos / CDS.length | AA.pos / AA.length | Distance | ERRORS / WARNINGS / INFO'">
##FORMAT=<ID=AD,Number=R,Type=Integer,Description="Allelic depths for the ref and alt alleles in the order listed">
##FORMAT=<ID=DP,Number=1,Type=Integer,Description="Approximate read depth (reads with MQ=255 or with bad mates are filtered)">
##FORMAT=<ID=GQ,Number=1,Type=Integer,Description="Genotype Quality">
##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
##FORMAT=<ID=PID,Number=1,Type=String,Description="Physical phasing ID information, where each unique ID within a given sample (but not across samples) connects records within a phasing group">
##x-varfish-case-uuid=d2bad2ec-a75d-44b9-bd0a-83a3f1331b7c
##x-varfish-version=<ID=varfish-server-worker,Version=x.y.z>
##x-varfish-version=<ID=orig-caller,Name=Dragen,Version=SW: 07.021.624.3.10.9, HW: 07.021.624>
##x-varfish-version=<ID=orig-caller,Name=GatkHaplotypeCaller,Version=4.4.0.0>

[!NOTE] Gnomad-mtDNA 信息写入到 INFO/gnomdad_genome_* 字段。

[!NOTE] 未来版本的工人将注释对 MANE 选择或 MANE 临床转录本的 worst effect。

seqvars prefilter 命令

此文件将 seqvars ingest 创建的文件作为输入，并通过种群频率和/或与外显子的距离来过滤变体。您可以将预过滤标准作为 JSON 传递到与以下 Rust 结构对应的命令行。

struct PrefilterParams {
    /// Path to output file.
    pub path_out: String,
    /// Maximal allele population frequency.
    pub max_freq: f64,
    /// Maximal distance to exon.
    pub max_dist: i32,
}

您可以直接在命令行上指定参数，或将以 @ 开头的 JSONL 文件的路径传递。您可以将两种方式混合使用。

$ varfish-server-worker strucvars prefilter \
    --path-input INPUT.vcf \
    --params '{"path_out": "out.vcf", "max_freq": 0.01, "max_dist": 100}' \
    [--params ...] \

# OR

$ varfish-server-worker strucvars prefilter \
    --path-input INPUT.vcf \
    --params @path/to/params.json \
    [--params ...] \

## The `seqvars aggregate` Command

This command reads through multiple files written by `seqvars ingest` and computes a in-house carrier counts table.
You can specify the VCF files individually on the command line or pass in files that have paths to the VCF files line by line.
The resulting table is a folder to a RocksDB database.

```shell session
varfish-server-worker seqvars aggregate \
    --genome-build {grch37,grch38} \
    --path-out-rocksdb rocksdb/folder \
    --path-in-vcf path/to/vcf.gz \
    --path-in-vcf @path/to/file/list.txt

seqvars query 命令

此命令执行序列变体的查询，并使用 annonars 数据库进行进一步注释。

strucvars ingest 命令

此命令将结构变异调用程序的一个或多个 VCF 文件作为输入，并将其转换为用于进一步查询的文件。该命令支持以下变异调用程序，并可从 VCF 标题和第一条记录中猜测调用程序。

  • Delly2
  • Dragen-SV（相当于 Manta）
  • Dragen-CNV
  • GATK gCNV
  • Manta
  • MELT
  • PopDel
  • Sniffles2

对于每个变异，将输出一条记录，每条记录只有一个替代等位基因。

以下为使用的符号 ALT 等位基因：

  • <DEL>
  • <DUP>
  • <INS>
  • <INV>
  • VCF 断裂端语法，例如，T[chr1:5[

以下为写入的 INFO 字段：

  • IMPRECISE -- 指定这是不精确变异的标志
  • END -- 变异的结束位置
  • SVTYPE -- 变异的类型，以下之一：<DEL>、<DUP>、<INS>、<INV>、BND
  • SVLEN -- 线性变异的 SV 的绝对长度，非线性变异为 .
  • SVCLAIM -- D（丰度变化）、J（新接头）或 DJ（丰度变化和新接头）的指定
  • callers --（非标准字段），调用变异的调用程序列表
  • chr2 --（非标准字段），BND 变异的第二个染色体
  • annsv --（非标准字段），变异对每个受影响基因的效应的注释

《annsv》字段是一个用管道字符（|）分隔的以下字段的列表

  1. 符号替换等位基因，例如，<DEL>
  2. 对基因转录本的影响，用&分隔
    • transcript_variant -- 变异影响整个转录本
    • exon_variant -- 变异影响外显子
    • splice_region_variant -- 变异影响拼接区域
    • intron_variant -- 变异仅影响内含子
    • upstream_variant -- 变异位于基因上游
    • downstream_variant -- 变异位于基因下游
    • intergenic_variant -- 默认为“未受基因影响”，但从不写入
  3. HGNC基因符号，例如，BRCA1
  4. HGNC基因ID，例如，HGNC:1100

以下FORMAT字段将被写入

  • GT --（标准字段）如果适用，基因型
  • GQ --（标准字段）如果适用，基因型质量
  • pec -- 配对末端读数覆盖的总数
  • pev -- 支持变异的配对末端读数
  • src -- 分裂读数覆盖的总数
  • srv -- 支持变异的分裂读数
  • amq -- 变异处的平均映射质量
  • cn -- 样本中变异的拷贝数
  • anc -- 样本中变异的平均标准化覆盖
  • pc -- 点计数（窗口/目标/探针）

总的来说，除了 ##contig=<ID=.,length=.> 行之外，该命令还将输出以下标题行。

##fileformat=VCFv4.4
##INFO=<ID=IMPRECISE,Number=0,Type=Flag,Description="Imprecise structural variation">
##INFO=<ID=END,Number=1,Type=Integer,Description="End position of the longest variant described in this record">
##INFO=<ID=SVTYPE,Number=1,Type=String,Description="Type of structural variant">
##INFO=<ID=SVLEN,Number=A,Type=Integer,Description="Length of structural variant">
##INFO=<ID=SVCLAIM,Number=A,Type=String,Description="Claim made by the structural variant call. Valid values are D, J, DJ for abundance, adjacency and both respectively">
##INFO=<ID=callers,Number=.,Type=String,Description="Callers that called the variant">
##INFO=<ID=chr2,Number=1,Type=String,Description="Second chromosome, if not equal to CHROM">
##INFO=<ID=annsv,Number=1,Type=String,Description="Effect annotations: 'Allele | Annotation | Gene_Name | Gene_ID'">
##FILTER=<ID=PASS,Description="All filters passed">
##FORMAT=<ID=GQ,Number=1,Type=Integer,Description="Conditional genotype quality">
##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
##FORMAT=<ID=pec,Number=1,Type=Integer,Description="Total coverage with paired-end reads">
##FORMAT=<ID=pev,Number=1,Type=Integer,Description="Paired-end reads supporting the variant">
##FORMAT=<ID=src,Number=1,Type=Integer,Description="Total coverage with split reads">
##FORMAT=<ID=srv,Number=1,Type=Integer,Description="Split reads supporting the variant">
##FORMAT=<ID=amq,Number=1,Type=Float,Description="Average mapping quality over the variant">
##FORMAT=<ID=cn,Number=1,Type=Integer,Description="Copy number of the variant in the sample">
##FORMAT=<ID=anc,Number=1,Type=Float,Description="Average normalized coverage over the variant in the sample">
##FORMAT=<ID=pc,Number=1,Type=Integer,Description="Point count (windows/targets/probes)">
##ALT=<ID=DEL,Description="Deletion">
##ALT=<ID=DUP,Description="Duplication">
##ALT=<ID=INS,Description="Insertion">
##ALT=<ID=CNV,Description="Copy Number Variation">
##ALT=<ID=INV,Description="Inversion">
##fileDate=20230421
##x-varfish-genome-build=GRCh37
##SAMPLE=<ID=index,Sex="Male",Disease="Affected">
##SAMPLE=<ID=father,Sex="Male",Disease="Unaffected">
##SAMPLE=<ID=mother,Sex="Female",Disease="Unaffected">
##PEDIGREE=<ID=index,Father="father",Mother="mother">
##PEDIGREE=<ID=father>
##PEDIGREE=<ID=mother>
##x-varfish-case-uuid=d2bad2ec-a75d-44b9-bd0a-83a3f1331b7c
##x-varfish-version=<ID=varfish-server-worker,Version="x.y.z">
##x-varfish-version=<ID=Delly,Name="Delly",Version="1.1.3">

[!注意] 《strucvars ingest》步骤不执行任何注释。它仅合并来自多个调用者的输入VCF文件（所有文件必须包含相同的样本）并将它们转换为内部格式。《INFO/annsv》字段由《strucvars query》填充。

《strucvars aggregate》命令

将《strucvars ingest》创建的多个文件导入到数据库中，该数据库可以用《strucvars txt-to-bin》转换为《.bin》格式，然后由《strucvars query》使用。您可以单独指定文件。以@字符开始的路径被视为包含路径列表的文件。您可以混合带有@和不带有@的路径。

$ varfish-server-worker strucvars aggregate \
    --genome-release {Grch37,Grch38} \
    --path-output OUT.tsv \
    --path-input IN/file1.vcf.gz \
    [--path-input IN/file1.vcf.gz] \

# OR:

$ varfish-server-worker db mk-inhouse \
    --genome-release {Grch37,Grch38} \
    --path-output OUT.tsv \
    --path-input @IN/path-list.txt \
    [--path-input @IN/path-list2.txt]

《strucvars txt-to-bin》命令

将varfish-db-downloader的输出转换为包含数据库的目录，这些数据库可以由查询命令，如《strucvars query》使用。

$ varfish-server-worker strucvars txt-to-bin \
    --input-type {ClinvarSv,StrucvarInhouse,...} \
    --path-input IN.txt \
    --path-output DST.bin

《strucvars query》命令

使用varfish工作数据库对《strucvars ingest》创建的结构变异VCF文件执行查询。

$ varfish-server-worker strucvars query \
    --genome-release grch37 \
    --path-db path/to/worker-db \
    --path-input IN.vcf.gz \
    --path-output OUT.jsonl

工作数据库具有以下结构。请注意，也读取mehari转录本，因此包括《mehari/》目录。

mehari/
    {genome_release}/
        txs.bin.zst
worker/
    noref/
        genes/
            acmg.tsv                -- ACMG SF list genes
            mim2gene.tsv            -- OMIM to NCBI mapping from clingen
            xlink.bin               -- gene crosslinks
    {genome_release}/               -- one per genome release
        features/                   -- features important for annotation
            masked_repeat.bin       -- masked repeats
            masked_seqdup.bin       -- masked segmental duplications
        strucvars/                  -- structural variant specific
            bgdbs/                  -- background databases
                dbvar.bin           -- dbVar
                dgv.bin             -- DGV
                dgv_gs.bin          -- DGV gold standard
                g1k.bin             -- 1000 genomes CNVs
                gnomad_exomes.bin   -- gnomAD-exomes/ExAC SVs
                gnomad_genomes.bin  -- gnomAD-genomes SVs
            clinvar.bin             -- ClinVar SVs
            inhouse.bin             -- inhouse SV database
            patho_mms.bed           -- well-known pathogenic DELs/DUPs
        tads/
            hesc.bed                -- hESC TAD definitions

开发者信息

本部分仅适用于《varfish-server-worker》的开发者。

开发设置

您还需要安装git LFS以获取测试数据库。

您需要最新版本的protocolbuffers，例如：

# bash utils/install-protoc.sh
# export PATH=$PATH:$HOME/.local/share/protoc/bin

要运行protolint，将其作为Python包安装：protolint-bin

# virtualenv /tmp/varfish-server-worker
# source /tmp/varfish-server-worker/bin/activate
# pip install protolint-bin

依赖项

~112MB
~2M SLoC