Welcome to the VarSeq VSWarehouse Tutorial!
Updated: February 2, 2021
Version: 2.2.2 or higher
This tutorial covers the basic VSWarehouse workflow. This tutorial focuses on connecting to a VSWarehouse instance from VarSeq, adding an existing VSWarehouse project as an annotation source, and using reports and assessment catalogs hosted on VSWarehouse.
To perform the workflow described you will need access to a demo VSWarehouse server, in addition to an active VarSeq license. You can go to Discover VarSeq to request an evaluation license, and a demo VSWarehouse server.
To complete this tutorial you can use the project created in the Cancer Panel tutorial or you can download a copy of the completed project from the following link.
Files included in the above ZIP file:
- Cancer Panel Demo – Starter project matching the project created in the Cancer Panel Tutorial
VarSeq version 2.2.2 was used to create this tutorial. While every attempt will be made to keep this content relevant, it is possible that certain features or icons may change with newer releases.
This tutorial focuses on several of the basic use cases for VarSeq and its integration with a VSWarehouse server. The VSWarehouse server allows for the simple centralized management of the variants and samples previously imported in VarSeq. Using VSWarehouse as part of an existing VarSeq workflow allows users to add previously seen variants to the current project. This can include variants from previous projects, reports or assessment catalogs. These resource are all centrally located allowing for easy management and collaboration.
The typical VarSeq workflow with VSWarehouse can be summarized with the following:
- The variants are imported in VarSeq where they are filtered down to the ones which are relevant.
- Annotation sources from VSWarehouse are added to autofill previous variants or assessments in order to speed up the final interpretation step.
- Once the initial variants have been reduced down to an actionable result set, they can be included in a report that is rendered and stored on the VSWarehouse.
- Additionally variant specific notes can be added to a VSWarehouse assessment catalog.
- Finally once the reporting is finished the project is uploaded to the VSWarehouse where its variants are added to a cohort of samples that underwent similar analysis.
The VarSeq project that is included in the ZIP file that accompanies this tutorial can be used to walk through this tutorial. Alternatively if you have previously completed the Cancer Panel VarSeq tutorial you can use that project to complete this tutorial.
Connecting to VSWarehouse
The first step to using VSWarehouse with VarSeq is setting VarSeq to talk to your VSWarehouse instance. This is completed through the VSWarehouse Manage Dialog in VarSeq.
The VSWarehouse manage dialog can be opened by going to Tools > Manage VSWarehouse… (as noted in Figure 2-1).
The first time that you open this dialog it will provide a splash page with VSWarehouse information, and a URL bar Figure 2-2.
Enter the URL of the warehouse demo server that you have been provide with. And click the Connect button. If the connection is successful the splash screen will be replaced with a view with four tabs Figure 2-3.
The Projects, Reports and Catalogs correspond to the three types of data that you can store on the warehouse. The Annotations tab allows you to add those three types of data as annotation sources. Cancer Gene Panel should be one of the projects listed in the Projects tab. This is an active project that represents all of the cancer data that we have seen so far for this gene panel.
Adding a Project as an Annotation
Any of the Projects, Reports, or Assessment Catalogs that are hosted on the VSWarehouse can be added as annotations to your VarSeq project. Adding a VSWarehouse project as an annotation, allows you to check which of the variants that your current project has in common with the previous projects. The same goes for assessment catalogs and reports which when stored on warehouse keep a record of every variant that has been previously reported along with any interpretation entered by the user.
From the VSWarehouse management dialog, switch to the Annotations tab. Check the Cancer Gene Panel source and add it as an annotation. This allows us to see if any of the variants that were in previous sample sets share variants with the samples in our current project.
The Cancer Gene Panel will then appear in the table like any other annotation source, Figure 3-2. As you can see there are two variants that are in the current filtered set that have been seen previously. Both of the allele frequencies of the two matched variants are above 0.5 indicating that they are both common variants.
Using VSWarehouse Assessment Catalogs
Assessment catalogs are modifiable annotation sources. By hosting an assessment on a VSWarehouse instance it makes it easy to share the changes to each variant in the catalog between multiple users. You can create assessment catalogs with custom fields which provides the flexibility to use them many different ways. The more common use cases center around using them as sets of white-listed or black-listed variants to speed up your variant interpretation. For this tutorial we will be using the Clinical Significance catalog that is already on the VSWarehouse.
The catalog that we will be using in this tutorial can be found in the Catalogs tab of the Manage VSWarehouse tab.
Click Open to create an assessment catalog view in VarSeq.
Next switch to the 50 Percent sample by selecting it from the current sample selector. This will update the filters allowing an additional variant into the final results.
Select the third variant, and notice that the assessment catalog view updates to the record at that position.
Fill out the assessment for this variant with a Pathogenic Classification and a Reported Classification as Confirmed somatic variant (see Figure 4-3). Click the Save button to update the VSWarehouse assessment catalog.
This assessment will then be placed on VSWarehouse were anyone can view or add the catalog as an annotation.
Additionally you will see that your change has been logged in the recent assessments section for that variant. This allows for tracking of users and their changes.
To view the assessment catalog data on the VSWarehouse. Open the internet browser of your choice and navigate to the VSWarehouse address. After login in you should see the Clinical Significance Catalog in the Assessment catalog section of the home page.
Select the Assessment catalog and find the record that you changed in VarSeq. Click on the record that was just changed in VarSeq, the record will allow you to change the variant assessment. Change the Reported Classification. to Unconfirmed somatic variant and click save.
Now, switching back to VarSeq refresh the catalog to load the changes made from the browser.
The reported classification has now changed, notice the additional edit in the Recent Assessments Log.
Using a VSWarehouse Report
Warehouse can be used to store sample report data. This allows you to view previous reports, as well as query across the variants that have been included in the report findings. Now that we have finished filtering the variants we will create a report with the filtered variants and upload it to VSWarehouse.
First, we will open a VSWarehouse hosted report template. Open the manage VSWarehouse dialog and navigate to the Reports tab Figure5-1
Select the Cancer Panel Report and click Open. This will open that report in a new VSWarehouse tab in your VarSeq project.
The next step will be to add sources required by the report that are missing from the project. These sources are used to autofill the data in the report. Click the red triangle in the upper right hand corner of the report view to view the current errors. The menu should display that two required sources are missing, and four optional sources are missing. Click each of the messages and add the missing annotations to your project.
Adding these premium annotations will allow information from these annotations to be included in the report.
While the annotations are running you can start to fill out the report template with some basic sample information.
The values that are placed in the form are used to render the report once it has been filled out. Additionally these are saved on the warehouse where they are aggregated across all of the reports that have been created using this template.
After the patient and physician information has been filled out the next step is to select the variants that will be included in the report using Variant Sets. To add a variant set click the square icon in the variant table view.
This will open the Create Variant Set dialog. Name the record set Primary Findings change the Initials to PF and click OK. Add an additional variant set named Incidental Findings with the initials IN colored green, following the same steps.
This will create two new flags fields. Add the top two variants to the Incidental Findings flags by clicking the colored square for each record under the IN field. Add the last variant to the Primary Findings category.
Finally, select the variants sets that correspond to the Primary and Incidental section in the reports view. This will take the information from the selected variants and fill it in the report.
Next check the signoff checkbox. Then click the render report button at the top of the report view. This will open a web view prompting you to log into VSWarehouse. After you log in the rendered html report will load from the VSWarehouse.
The report has now been saved on the warehouse. All of the samples and the variants in their findings can be viewed and queried from the warehouse. Additionally the variant set in the report can be used as an annotation source.
To add the variants from the findings section as an annotation source open the Manage VSWarehouse Dialog. Navigate to the annotations tab and find the Cancer Panel Report – Primary Findings source.
Adding this source will add the primary findings from the source that was just uploaded to the warehouse as an annotation source. Scrolling all the way to the right of the table you will see the variant included in the Primary Findings appear as an annotated variant.
Uploading Projects to Warehouse
After you have finished the analysis and the final report in VarSeq the final step is to upload the project to VSWarehouse. To upload the current project open the Manage VSWarehouse dialog through the Tools menu and select the Projects tab.
Next, select the Cancer Gene Panel project and click the add samples button. This will open the Add Samples to Warehouse wizard.
The first step of the Add Samples to Warehouse wizard is editing the sample fields. This allows you to change the sample fields in the same manner that they are added when the first importing data.
The fields can be left with their existing values. Click Next to progress to the next page of the wizard.
The last page of the wizard allows you to change the Upload Source for the samples. This is a tag that is applied as an additional field to all of the samples. Additionally, you can change when to run the import on warehouse.
Change this value to Run Immediately to import these samples to the VSWarehouse project as soon as they are uploaded. Click Upload to begin the process.
When the upload is complete you will be presented with a link which will allow you to follow the progress of the import on the VSWarehouse.
From the VSWarehouse web interface you can view the samples, variants, assessment catalogs, and reports that have been uploaded to the VSWarehouse. Each of these categories can be queried and exported from using the same Query and Result interfaces.
Open the web browser of your choice and log into the VSWarehouse. This will open the VSWarehouse homepage, which is divided into four sections. One for each category of data stored on the warehouse.
In the project section, select the Cancer Gene Panel. This will open the VSWarehouse project that corresponds to the VarSeq project was previously uploaded.
To find other rare variants in the BRAF gene opened the query interface by selecting Query at the top of the page. This will open the query interface where you can construct filters based on the fields in the data.
Next add a filter in the Allele Counts section for the Allele Frequency with an upper bound of 0.01, and uncheck include missings.
This will filter to rare variants that occur in less than 1 percent of the samples that been added to this project. Next switch to the RefSeq Genes 105v2, NCBI section to add a filter for the Gene Names equal to BRAF. Finally add a filter for the RefSeq Genes 105v2, NCBI field Effect (Combined) equal to Missense.
This should reduce the number of variants to 3. To view the variants click Results at the top of the page.
The results page will display the three records that pass the filters. Change the visible fields by selecting Change Columns. This will display the published columns that are available on the left and the current visible columns on the right.
Add the Allele Frequencies field from the Allele Counts category, as well as the Drug, Generic Name and Response Rate fields from the OncoMD Drugs Targeting Mutation category.
Next select Export at the top of the screen to save the results. Select Excel as the file type and under Select Samples click Unselect All. This will remove the sample fields from the output.
Clicking Export will start a job to perform the export. Click View Task to see the status of the job, and to download the results after it has completed. You can then open the file in Excel shown in the VSWarehouse results.
This tutorial was designed to give a taste of all the features and capabilities of VSWarehouse and how it can be integrated in a VarSeq workflow.
Additional features and capabilities are being added all the time, so if you do not see a feature you need for your workflows please do not hesitate to let us know!