Variant expansion and normalisation
Genetic variants are drawing increasing interest regarding their role in pathologies, for designing new drugs or refining treatment efficacy through stratification. However, variant interpretation depends on time-consuming curation tasks. To support variant interpretation efforts and decisions based on the latest evidence, we propose Variomes [1, 2], a service performing variant-specific triage of publications.
To increase the comprehensiveness of Variomes, we developed SynVar. This tool enables variant expansion and cross-level representation normalisation. This task faces different challenges:
While several variant databases and registries exist, such as ClinVar, dbSNP, and the ClinGen Allele Registry, relying on them as reference terminologies presents several limitations:
SynVar supports effective retrieval and annotation of variants in the literature. From a description at the genomic (g.), coding-DNA (c.) or protein (p.) level, it resolves corresponding representations across levels and generates HGVS expressions as well as non-standard forms commonly found in publications. It can process variants that are not yet described in an existing database.
SynVar supports the following variant types according to HGVS nomenclature:
In addition to HGVS notation, variants can be provided in the following formats, which are automatically converted to HGVS before processing:
The following optional parameters generate additional synonyms in mode=expand:
Protein variant: the change is validated on an explicit or gene-associated protein reference resolved through local cross-reference tables and the UniProt API [3]. The valid variant is then back-translated into possible coding-DNA variants using the Mutalyzer 3 API [4]. Finally, the coding-DNA candidates are mapped onto GRCh37 and GRCh38 using VariantValidator [5].
Coding-DNA variant: the variant is validated and mapped to genomic coordinates using VariantValidator [5], which also predicts the corresponding protein consequence when available.
Genomic variant: the variant is validated and converted to coding-DNA representations using VariantValidator [5] when it overlaps a transcript. VariantValidator also provides protein consequences. For intergenic variants, only genomic representations are generated.
dbSNP ID: Genomic alleles associated with the dbSNP ID are retrieved through the NCBI E-utilities services [6]. Each retrieved allele then follows the genomic mapping route.
ClinGen Allele Registry ID: The genomic variant corresponding to the ClinGen Allele Registry ID (CA ID) is retrieved through the ClinGen Allele Registry [7]. The retrieved allele then follows the genomic mapping route described above.
Gene and transcript variant:
APC + c.5975C>G → select an APC transcript → NM_000038.6:c.5975C>G → NC_000005.10:g.112841569C>G.
Exact transcript variant:
NM_000038.6:c.5975C>G → preserve the requested transcript version → NC_000005.10:g.112841569C>G.
Gene and protein variant:
BRAF + V600E → validate p.Val600Glu on a BRAF protein reference → infer a compatible transcript variant → map it to NC_000007.14:g.140753336A>T. A protein change can correspond to more than one nucleotide allele.
Results are returned as a list of genomic variants, together with corresponding coding-DNA and protein representations, grouped by genes and isoforms. The output content depends on the mode parameter:
mode=expand (default): full variant expansion with the following elements:
mode=normalize: normalised identifiers without syntactic variations:
The output format is controlled by the format parameter: xml (default), json (the same structure in JSON), or vrs (a SynVar JSON response containing HGVS, identifiers, SPDI, VCF and GA4GH VRS Allele representations where available; format=vrs implies mode=normalize).
https://synvar.sibils.org/api
The previous URL /generate/literature/fromMutation is still supported for backward compatibility.
| Parameter | Description | Example | Default value | |
|---|---|---|---|---|
| variant | Variant description, ClinGen Allele Registry ID or dbSNP ID. Can include the gene/reference or free text containing variants. Also accepts SPDI, VCF, IVS and HGVS repeat notation as input. Free text (variant in standard or non-standard format, with or without gene/reference) |
V600E, BRAF V600E, c.1799T>A, NM_004333.6:c.1799T>A, rs113488022, CA251544, NC_000007.14:140753335:A:T (SPDI), 7:140753336:A:T (VCF), IVS1+1G>A | no default value | mandatory |
| ref | Gene name or chromosome number/name. Optional when included in the variant field, or when using dbSNP/ClinGen identifiers. Free text (gene name, chromosome number/name, sequence accession: RefSeq NM_/NP_/NC_, Ensembl ENST/ENSP, LRG) |
BRAF, JAK2, 9, X | no default value | optional |
| searchGenes | Allow SynVar to discover candidate gene names in the variant text. Set to false when trusted genes are supplied in ref, especially for literature prose where ordinary words may also be gene symbols. Accessions embedded in complete HGVS expressions remain usable. Possible values: true, false |
false | true | optional |
| level | Level of the variant description. any tries protein, transcript, genome, dbSNP and ClinGen in that order and stops at the first level producing a GRCh38 mapping. all combines results from every level. Possible values: protein, cdna (or transcript), genome, genome38 (or genome_grch38), genome37 (or genome_grch37), dbsnp, clingen, any, all The genome38/genome37 shortcuts combine level=genome with assembly filtering. |
protein | any | optional |
| iso | Expand to all available isoforms of the gene. Possible values: true, false |
true | false | optional |
| map | Require genome mapping. When true, results are only returned if genome mapping succeeds. When false, outputs syntactic variations even without successful genome mapping. Possible values: true, false |
true | false | optional |
| mode | Processing mode. expand generates all synonyms and syntactic variations. normalize returns only normalised identifiers (HGVS, dbSNP, ClinGen, SPDI, VCF) without syntactic variations. Possible values: expand, normalize The previous parameter norm=true is equivalent to mode=normalize. |
normalize | expand | optional |
| format | Output format. xml and json return the same structure in different formats. vrs returns a SynVar JSON response containing HGVS, identifiers, SPDI, VCF and GA4GH VRS Allele representations where available (implies mode=normalize). Possible values: xml, json, vrs |
json | xml | optional |
| startMet | Enable Start Met ±1 shift. Generates additional protein synonyms at position−1 and accepts input with +1 fallback (e.g. BRAF V600E also generates V599E). Possible values: true, false |
true | false | optional |
| insForDup | Generate insertion-equivalent synonyms for duplications (e.g. A763dup → A763_Y764insA). Possible values: true, false |
true | false | optional |
| leftAlign | Generate left-aligned (shifted) synonyms for deletions and duplications in repetitive regions. HGVS mandates 3' alignment; this adds left-aligned and intermediate forms. Possible values: true, false |
true | false | optional |
| assembly | Restrict genomic mapping to a specific genome assembly. When not specified, both GRCh38 and GRCh37 mappings are returned. Possible values: GRCh38, GRCh37, hg38, hg19 Alternatively, the assembly can be specified via the level parameter: genome38 or genome_grch38 for GRCh38, genome37 or genome_grch37 for GRCh37. |
GRCh38 | both assemblies | optional |
Example scripts to query the service and parse the output: