Welcome to the HerediVar Wiki

General Thoughts & Conventions

There are four types of users in HerediVar:

1. Superuser
2. Standard user
3. Read only user
4. Anonymous user
5. Account manager

An anonymous user can not view or edit any variant information on HerediVar. Anonymous users must ask an account manager to create an account for them. As the name implies, the read only user can only view information. He can neither insert variants nor classify them. The standard user is allwed to view and edit information on HerediVar and the superuser has access to the admin dashboard which allows him to import variants from HerediCare, reannotate all variants at once and do multiple other administrative tasks.
The account manager is a special role which allows the user to create and modify user data.

Conventions for links: It is very easy to differentiate external links from internal ones: Whenever a link is displayed like this  it references an external website and if a link is shown like this it references an internal page.

It is very important to understand that each user is able to insert one classification for each variant - classification scheme combination. In addition, a superuser can insert one consensus classification for each variant. Consensus classifications are always superseded by the newest consensus classification. But all previous consensus classifications are kept and can still be viewed.

The workflow

Insert variants

There are two ways to insert small variants. The most common one is to import variants from HerediCare. However, only superusers can do that. Standard users can insert variants through the create variant page for small variants. New variants are automatically added to the annotation queue and processed once a worker is ready to process it. The status of the annotation can be seen when navigating to the variant details page.

HerediVar also supports structural variants, however, in a limited manner. Thus, it is currently only possible to insert deletions, duplications and inversions. These must be inserted manually through the create structural variant page. Although they generally behave identical compared to a small variant, they are currently not annotated with meta information.

Browse variants

To find the variant you are looking for navigate to the search variants page. This page shows a paginated table of all variants. The columns of this table are interpreted like this:

1. CHR: chromosome
2. POS: GRCH38, left-aligned genomic position
3. REF: reference base(s)
4. ALT: alternative base(s)
5. VARTYPE: the type of the variant. This value is "sv:sv_type" if the variant is a structural variant or "small" if the variant is a regular small variant
6. HGVS c.: the HGVS c. string for this variant. The reference transcript is the "best" transcript* for the gene of this variant.
7. HGVS p.: the HGVS p. HGVS string for this variant. The reference transcript is the "best" transcript* for the gene of this variant.
8. GENE: the gene which has the variant. Sometimes there are multiple genes, because the variant has consequences in all of them.
9. Your classification: the most recent classification of the user which is currently logged in.
10. Consensus classificaiton: the most recent consensus class from the VUS-task-force.

*: "best" transcript refers to the preferred transcript which is calculated for each gene individually: MANE select/plus clinical -> longest coding -> longest non-coding

To filter the table of all variants click the magnifiying glass to the top right. You can filter the table of variants by:

• A variant:
  The variant strings are of this format: chrom-pos-ref-alt in case of small variants and chrom-start-end-sv_type in case of structural variants
• The variant type: either small variants or structural variants. Checking both is the same as leaving both empty
• A gene name or unique alias or HGVS-ID (e. g. BARD1)
• A genomic range is described by providing chromosome start position and end position. These values must be separated with ":", "-" or whitespace (except new lines). Both, adding as well as removing the "chr" prefix from the chromosome is allowed and should yield the same result. Example formats that work:
  • chr1:start-end
  • chr1-start-end
  • chr1 start end
  • chr1[tab]start[tab]end
  • 1:start:end
  Examples that do not work:
  • chr1- start-end (note the space between the first dash and the start position)
  • chr1::start-end
  HerediVar allows to upload a bed file in addition to providing chromosomal ranges manually through the textarea. Simply click the "upload bed..." button and choose a bed file from your local storage. Keep in mind that start positions within bed files are zero based (ie. inclusive) while end coordinates are one based (ie. exclusive) within bed files. HerediVar automatically converts the endposition to a zero based (ie. inclusive) position. Choosing this option will automatically append all relevant fields in a HerediVar supported format to the textarea.
  WARNING: Due to the fact that .bed files can contain any character each bed style range must reside in its own line (ie. they must be separated with newline characters)!
• cDNA ranges
  This option allows you to filter the variants by ranges of cDNA positions. There are three required values for each query.
  
  1. The transcript or a gene symbol. When specifiying a gene symbol the algorithm will choose the best transcript for this gene.
  2. The cDNA start position relative to 1
  3. The cDNA end position relative to 1
  These values must be spearated either with a space or tabulator.
  You can also scan intronic regions by adding or subtracting to the start or end cDNA position. (eg. ENST00000380152 1 68+10). Keep in mind that cDNA positions are counted from the larger genomic position to the smaller one if the gene is defined on the reverse or minus strand. Still, the smaller cDNA position must be inserted as start and the bigger cDNA position as end.
  If you want to scan regions outside the gene region add an asterisk (*) or a minus (-) character before the start or end position (eg. ENST00000380152 -100 1).
• A HGVS c. string
  This search option is most useful when you know the reference transcript. In this case please specify the search string like this: Transcript:c.PositionReference>Alternative (e. g. ENST00000260947:c.1972C>T).
  If you do not know the transcript you can also specify the gene symbol (or alias or HGNC-ID) instead of the transcript (e. g. BARD1:c.1972C>T)
  In case you neither know the transcript nor the gene it is also possible to omit the reference sequence. But be careful with this type of search as it will provide you with ALL possible nucleotide changes that COULD be the one you are looking for. Thus, you should inspect the results carefully before continueing. (e. g. c.1972C>T)
  WARNING: HerediVar will choose the ensembl mane select transcript as reference, if you specify the gene instead of the transcript. If there is no mane select transcript it will omit this HGNC.
• IDs
  You can search for HerediVar variant_ids or dbSNP rsids, clinvar variation ids, COSMIC ids (COSV) or heredicare vids.
  You can insert the ids directly or choose to append a ":" followed by the database name. For example: You can search for rs1057519871, 1057519871:rsid or 1057519871. All of which return the same variant.
  It is recommended to specify the database of the identifier to make results more accurate.
  Extensions used by heredivar:
  
  • HerediVar variant_ids: heredivar
  • dbSNP rsids: rsid
  • ClinVar variation ids: clinvar
  • COSMIC COSV ids: cosmic
  • HerediCaRe VIDs: heredicare
• Annotations
  First select the annotation from the dropdown menu, then type the operator. For numerical values you may choose from <, <=, >, >=, = and !=. For text-like values you may choose from =, != and ~. Hereby, ~ is a case insensitive substring match. Finally, provide the value in the next textbox.
  It is always possible to add more annotation searches. But be aware that resulting variants must always satisfy all of the criteria at the same time to appear in the variant list.
• A consensus classification. This filters only for consensus classifications which were made within HerediVar and excludes consensus classification which were imported from HerediCaRe. However, if the "include_heredicare" checkbox is ticked, the search will also display imported consensus classifications (see section on consensus classifications in documentation for further details on how to spot imported consensensus classifications).
  Be mindful though: HerediVar native consensus classifications always overshadow imported ones. So a variant which has an imported consensus classification of 1, but a HerediVar native consensus classification of 2 will not be found if class 1 and include_heredicare are checked (provided class 2 is not checked).
• Your classification
• A list of variants

If multiple constraints are selected they are joined with 'AND'. This means that if you choose to search for BARD1 in the genes and select consensus classification 1 you will get all variants from BARD1 which are classified with 1.
You can separate multiple genes, HGVS or chromosomal ranges in their respective fields either with semicolons (';'), commas (',') or newlines. It is also possible to have a combination of them.
It is also possible to add all variants which satisfy the current filtering criteria to a user defined list by clicking the "Add to list" button located at the bottom left. To create a new list go here. More information about user variant lists is here.
Clicking on any of the rows will get you to its variant details page. To view details about a particular gene just click its name.

The variant details page

This page displays all annotations of a variant. The top headline shows the variant and its most recent consensus classification by the VUS task-force. There are multiple types of consensus classifications:

These are interpreted as follows:

• -: no classification
• 1: benign
• 2: likely benign
• 3-: uncertain with tendency to benign
• 3: uncertain
• 3+: uncertain with tendency to pathogenic
• 4: likely pathogenic
• 4M: modifier
• 5: pathogenic

If the consensus classification symbol shows a red download icon like so: It means that the consensus classification was imported from HerediCare and there is no consensus classification available for this variant which was made on HerediVar.
Right below the headline one can find status information about the variant. The first pill shows the status of the annotation. It could be queued, processing, done or erroneous. Next to the annotation status pill there is the clinvar submission status. This shows if the variant was already uploaded to ClinVar from HerediVar. There is one additional, optional status pill which sais "HIDDEN" if the variant is hidden. When you click the "gear" button the website presents options on what to do with the variant.
The main body of the page displays visualizations, classifications and annotations which are organized in multiple tabs. The tabs contain the following information:

• Classification: HerediVar consensus classification, HerediVar user classifications, HerediCare center classifications, ClinVar classifications, BRCA exchange and ARUP BRCA classifications
• Population & in-silico annotations: phylop-100way, cadd scaled, revel, spliceai, maxentscan, gnomAD, flossies, cancerhotspots, tp53db, hexplorer, maxhbond score
• Consequence: The variant consequences with associated HGVS strings and protein domains
• Assays: Functional, splicing, etc. assays. Add a new assay by clicking the gear button at the top.
• Literature: Papers annotated by VEP, TP53db and litvar2
• IGV: The IGV genome browser. The first track shows the variant itself. The second and third track show all classified variants (click on them to find a link to the variant details page). The fourth track shows the ensembl transcripts. Red transcripts are MANE select or MANE plus clinical transcripts, orange ones are ensembl canonical and dark blue ones are gencode basic transcripts. Other transcripts which do not satisfy the aforementioned criteria are not shown.

Remember that annotations are not shown if the variant is unknown to the respective database.

Classify a variant

To classify a variant click the gear button and select "Classify". On the classify variant page you can first select if you want to insert a user classification or a consensus classification. However, only superusers can insert consensus classifications. Next, select the classification scheme or no scheme if you just want to insert a freetext classification not following a scheme. The webpage automatically chooses the best scheme for the variant if possible.
Click a criteria button to see more details about it. Here is an example for PVS1:

First, insert evidence and then click the selectbox next to the headline of the criterion to change its state. The following criterion states are possible:

1. unchecked: we do not have enough evidence to say anything about this criterion -> not assessed / unknown evidence
2. selected: evidence suggests this criterion is true -> assessed / true evidence
3. unselected: evidence suggests this criterion should not be selected -> we KNOW that this criterion is not selected because of evidence -> use this for documentation purposes

It is also possible to adjust the strength of some criteria. The classification preview to the right will update automatically based on the selected criteria.
Once all criteria have been assessed you can insert further evidence by adding literature. Simply add a blank row or add one from the text mining results and copy the section of interest.
Finally, select the final classification and optionally leave a comment. This is especially encouraged when the selected final classification differs from the proposed classification from the classification scheme.
Note that each user can only have one user classification per variant and scheme, but they can be edited anytime.
Consensus classifications work just alike. The only difference is that the number of users who chose that criterion is displayed next to it like so: The selected criterion, "PS1" was chosen by two HerediVar users to be important for this variant. The actual user input is shown in the "User selections" table. When you click the copy symbol it is possible to quickly copy the selection and evidence of this user. The criterion will be in an intermediate state (shown with diagonal strips). Criteria in the intermediate state simply tell the user that the criterion was selected by some automatic procedure. Every intermediate criterion will be submitted just like non-intermediate criteria. So there is no need to get rid of the intermediate state. Simply be extra critical about intermediate criteria.

Automatic classification algorithm: HerediClassify

The automatic classification algorithm called HerediClassify takes the evidence collected by HerediVar and automatically assesses ACMG criteria. By default it uses the ACMG SVI adaptation classification scheme, but it also supports gene specific ACMG classification schemes. These include:

• ATM
• BRCA1
• BRCA2
• CDH1
• PALB2
• PTEN
• TP53

The best scheme is automatically selected by HerediClassify. It always calculates two classifications for the same scheme. One based on splicing evidence and the other on protein evidence.
HerediClassify is run by the annotation service of HerediVar. So a reannotation also updates the automatic classification.
The variant classify page allows to copy all selected and unselected criteria from HerediClassify along with their strength and evidence to help speed up the classification process. Using the gear button the user can choose if the criteria using the splicing or protein evidence should be copied.
Every criterion selected in this way will be in the intermediate state. The intermediate state is indicated with dark stripes across the criterion button and is meant as a visual indication for the user that the criterion might need further attention. All intermediate criteria will be treated as if they are not intermediate. This means that they are submitted like they are not intermediate.

User variant lists

Each registered user can add new variant lists here. Click the "+" button:

Enter a name for the list and select if it is readable / editable by all HerediVar users. If a list is readable everyone can see the list, but they can not add or remove variants from it. This is however possible when the list is also editable.
There are two ways to insert variants to the newly created variant list. The first one is to add variants to a list on a one-by-one basis is to navigate to the variant details page, click the gear button and select "Add to list".
The second one is to visit the browse variants page. You can simply select the variants that you wish to save to a list and select "Add selected to list". To simplify things one can also choose to select and unselect all variants. Keep in mind that only variants which satisfy the current search parameters are added when select all variants is active. The page also keeps track of selected variants through pages of the variant table. So it is save to first select all variants and then click the "Add selected to list" button once. Keep in mind though that your selection will reset upon querying a new search.

All variants collected in these ways are displayed when clicked on the name of the list at the user lists page. The table of variants behaves exactly the same as the one shown on the browse variants page. It can be filtered and when a row is clicked it takes you to the variant details page.
It is also possible to export all variants in one of the lists to vcf by clicking the "Export to VCF" button on the bottom of the page.
If you want to change the properties or delete a list that was created by you. Just click the little pencil button next to the list name. Beware that private lists can not be seen by other HerediVar users.

To further simplify handling these lists there are four possible actions to manipulate variant lists. First click the list you wish to edit. Then, you can see four icon-buttons on the top which are explained as follows:

• : duplicate the list
• : intersect this list with another list
• : subtract another list from this list
• : combine this list with another list

As you can see, these implement simple set operations. The website will ask some more questions about how to do each of the operations. For example, some operations allow you to do it either inplace or or not in place. When you choose inplace it will take the result of the operation and write it to the currently selected list. When this is not selected it will create a new list (asking you to choose a new name and access rights).

Publish variants

A superuser can upload or publish variants and their annotations or classifications to external databases. Currently, HerediVar offers to upload to ClinVar and HerediCaRe. To publish one or multiple variants the user has to navigate to one of the following pages:

• The variant details page: for single variant uploads
• The user variant lists page: uploads all variants in that user defined variant list
• The admin dashboard: automatically select all variants which got an update to their consensus classification since the last upload

The publish variants page presents a list of all variants which are about to be submitted. Simply check the database(s) below that list and fill out the required information. After the form is submitted your request will be processed in the background. You can get status information about each submission from the respective variant details page.
There is an automatic upload algorithm running in the background which will regularily (at least once a month) check for updated consensus classifications and upload them to HerediCaRe.

Caveat:
It is possible to submit the same data multiple times. Though, HerediVar will skip the upload request and show a red triangle within the respective status pill on the variant details page. Consider this case: A user made a fresh consensus classification and submitted that to HerediCaRe. Right after he notices that the consensus classification needs adjustments. So he creates another consensus classification and submits that as well. In this case the updated consensus classification WILL NOT BE SUBMITTED, but skipped and the red triangle will show up.
This however will be resolved once a user resubmits the consensus classification after the previous one is finished or once the automatic upload algorithm catches the updated consensus classification. So whenever this happens consensus classifications take more time to fully update in the third party database.

Structural variants

Structural variants can only be inserted using the create structural variants page. They generally behave identical to a small variant, but are not annotated by the annotation service. Also, the interpretation of the information in the browse variants table differs slightly:

The differences are:

• If a deletion is longer than 1000 bp, the POS column contains the start and end position of the structural variant separated by a dash (-). The sequence of duplications and inversions is never displayed, independent of the length of the variant.
• The POS column will show a red triangle if the position is imprecise
• The HGVS c. and p. columns contain the hgvs strings that were provided by the user upon creation of the variant. They are not ordered in any way nor are they curated or correspond to the genes shown in the gene column
• The GENE column shows only genes that overlap the breakpoints of the structural variants

The variant details page of structural variants is also similar to that of small variants with the only difference being that the variant banner at the top shows all genes that overlap the region of the structural variant. These are color coded:

• blue: gene overlaps breakpoint
• bold: VUS-Task-Force important gene
• black: non breakpoint overlapping gene

Download data

Data can be downloaded using file downloads or programmatically using the application programming interface (API).

File download

Anonymous users can download all classified variants and all classified structural variants in vcf here. They will only see the consensus classifications by the VUS-task-force along with some meta information. Most of this data is also publically available through ClinVar.

Registered users are able to download a vcf file for one variant through the respective variant details page by clicking the gear button and selecting "Export to VCF". This file will contain all information that are available for this variant. Including all annotations and classifications.

If a registered user wants to download more than one variant in a single file they have to collect relevant variants in a user defined list (see previous section on how to create one). Then, simply click the "Export list to VCF" button at the bottom right of the list details page. Note that structural variants and small variants can be mixed in this case.

In rare cases ClinVar submissions are missing although there is a ClinVar summary available. In such cases the clinvar_submissions info in the downloaded vcf file will be set to None. This is usually because of erroneous data hosted by ClinVar and is often fixed by updating ClinVar.

In any case, downloaded VCF files are encoded using the url encoding (Wikipedia). Excluding whitespace, which is replaced with underscores "_". This ensures that the file is machine readable and consistent when special characters that are also used as delimiters are used within the actual information. It is fast forward to revert the encoding once relevant information was read from the file. Many programming languages support url decoding out of the box.

The INFO column of VCF files generated by HerediVar adhere to this delimiter order:

1. ;
2. &
3. |
4. $
5. +

API reference

In order to use the HerediVar API it is first required to get an API-key. A logged in user can request an API-key by navigating to the profile page. If you do not have a login please reach out to us so we can discuss options. On the profile page click the (re-) generate button to generate a new API-key. The key is only shown once so save it somewhere locally. Do not share your API-key with anyone.
Once you created your API-key you can use it in one of the specified endpoints:

User management

Create a new user

Only users with the "account_manager" role are allowed to create new users. There is no possibility to self-register in HerediVar. An account manager can go here to create a new user account. Simply fill out the form which is presented to you. Keep in mind that the username must be unique and can not be changed later. The mail address must be unique as well.
Upon submission Heredivar will automatically notify the user that about the newly created account using the provided e-mail. The new user will recieve two mails: one with the username specified and one with an automatically generated initial password.

Change roles & disable users

An account manager can edit existing users by visiting /show_users. Simply select a user from the list to edit its information. It is possible to disable users or change their roles from this page.
Keep in mind that changeing the e-mail will require the user to verify the mail upon next login.

Change password

Every user can change their own password by visiting this page. This will redirect to the keycloak account management console. First click the Update-button:

Then, you are probably asked to re-authenticate using your old password. After that you can insert a new password.