Beacon Instance Variant Query Options and Information

[mbaudis]

Beacon missing on option to inform about features & content

While beacons can inform about filteringTerms and their scopes and generally indicate which entities are supported by them, especially for genomic variants such information is mostly missing beyond the general indication of supported request parameters (which probably sometimes just represent the default). So in the current state there is no direct support for topics like:

Which genomes and genome editions can be queried?

Beacon provides a default query parameter assemblyId which can be used to specify the genome edition (e.g. GRCh38) in a query but the Beacon itself does not have an endpoint to expose supported assemblies, and according to the documentation no specific format is required in queries:

    assemblyId:
      $ref: ./requestParametersComponents.yaml#/definitions/Assembly

  Assembly:
    description: >-
      Genomic assembly accession and version as RefSqeq assembly accession
      (e.g. "GCF_000001405.39") or a versioned assembly name or synonym such as UCSC
      Genome Browser assembly (e.g. "hg38") or Genome Reference Consortium Human (e.g.
      "GRCh38.p13") names.
    type: string
    example:
      - GCF_000001405.39
      - hg38
      - GRCh38.p13

Therefore it isn't clear if a beacon supports or understands a requested assembly , and no specific error will be given upon a failed request.

Additionally, the assemblyId parameter might clash with version specific referenceName parameters.

Suggestions

• deprecate assemblyId and move to versioned sequence identifiers
• provide an informational endpoint about supported assemblies
• leave the "chromosome 7 on GRCh38" to refseq:NC_000007.14 conversion to front ends / implementations but outside of the Beacon specification

Which sequence identifiers are supported?

As mentioned above everything is permitted (although we suggest "assembly specific RefSeqId"):

    referenceName:
      $ref: ./requestParametersComponents.yaml#/definitions/RefSeqId

  RefSeqId:
    description: >-
      Reference sequence id for genomic reference sequence in which variant
      coordinates are given, e.g. "refseq:NC_000009.12" for human chromosome 9 in the
      GRCh38 assembly. The use of the assembly specific RefSeqId is recommended
      although alternatively names, synonymous or aliases e.g. "chr9" could be
      used in conjunction with an `Assembly` parameter.
    type: string
    example:
      - refseq:NC_000009.12
      - chr9
      - NC_012920.1

Suggestions

• limit to prefixed versioned identifiers (if prefix use isn't standard for a given identifier space => document a Beacon specific prefix use)
• provide information about the supported identifiers - either specifically or which types - through an informational endpoint

What identifiers can be used for the variantType parameter¹?

This is as above for sequence identifiers. Here a more stringent use of well documented variant types (for CNV from EFO, for sequence variants from SO as a first guess; possible use of VCF symbolic alleles if better documented...) should be settled on, but also indicated through some informational endpoint.

How are variants normalized²?

The positional normalization of variants will affect positional matching, particularly for sequence variations with shortened sequences; and there is no documentation / enforcement of a given style. This will lead e.g. to non-matches for VCF style sequence deletions when using the VRS concept of full left normalization.

Suggestions

• document a single standard use (following VRS?!)
• provide implementation guidance for coordinate transformation

What types of variant queries are supported and/or what types of variants exist in a given beacon or in its datasets?

The correct representation of supported variant parameters does not necessarily indicate what types of queries will be supported (and that is compounded by the lack of indication of supported

What to do next...

• discuss here
• contribute to Beacon Variant Scouts
• file issues & PRs...

Footnotes

1. For CNVs we have a standards documentation - developed with GA4GH GKS and the ELIXIR hCNV community inside the Beacon documentation. ↩

2. The topic was brought up by @ahwagner at a variant scouts meeting. ↩

[ahwagner]

Suggestions

• deprecate assemblyId and move to versioned sequence identifiers
• provide an informational endpoint about supported assemblies
• leave the "chromosome 7 on GRCh38" to refseq:NC_000007.14 conversion to front ends / implementations but outside of the Beacon specification

I wonder if these points could be addressed by aligning on the VRS 2 SequenceReference class?

[mbaudis]

@ahwagner It would be great to have some doodle of approximate examples here... Sure, we should all follow VRS 2 developments but ¯\(ツ)/¯