Assessment Catalog View

The assessment catalog view provides a interface to track variants across projects. Each stored variant can be annotated with custom information input through a form. Projects can use these custom assessment catalogs as annotation sources and filter variants based upon the stored values.

The assessment catalog view can be accessed by clicking the plus sign next to any row of tabs and selecting Assessment Catalog or by right-clicking in any corner on the stash icon and selecting Create New Assessment Catalog.

Creating a New Assessment Catalog

When a new assessment catalog view is opened, you can choose to either create a new assessment catalog by clicking the Create New Assessment Catalog button or selecting a recently used assessment catalog from the Select Existing Assessment Catalog menu. If you have previously created a assessment catalog and it does not appear in the menu, you can browse for the assessment configuration file (.vardb-conf) or a SQLite database file (.variant-db).

When the Create New Assessment Catalog button is clicked a dialog will open to set up a new assessment catalog. Three database backends are supported, SQLite, PostgreSQL and MySQL.

SQLite

SQLite is a relational database that is contained within a file. It is a very convenient and portable way to store variants. No additional software or setup is required to use this backend. A single file can be shared between many users by placing the variant-db file on a shared network drive. If many people will be accessing the database at the same time, then you may want to consider one of the other backends. However, if only one person at a time will be generally using the database at once, SQLite is a good choice.

To create a new SQLite variant database click the Browse button and select a folder and enter file name for your database.

PostgreSQL

PostgreSQL is a full featured database server. It is our recommended backend if many users will be concurrently connected to the same database. The setup is more complex and may require that you contact your IT department.

Prior to connecting to the database server in VarSeq, the server must have a database provisioned on it. Additionally, a database user will need to be created with table creation privileges to this database. VarSeq will use this database and create tables to emulate the behavior of having access to multiple databases even though it only uses one database on the server.

After creating the required database and user on the PostgreSQL server, select PostgreSQL from the menu at the top of the dialog. Then enter the Host, Port, Database Name, Username, and Password into the dialog. Click Connect. If VarSeq has any problems communicating with the database, an error dialog will display helpful debugging information. Finally, enter the name of the “Assessment Catalog”. This catalog will serve as your assessment catalog.

MySQL

MySQL is a widely deployed database server. The setup is similar to PostgreSQL and may require that you contact your IT department.

Prior to connecting to the database server in VarSeq, the server must have a database provisioned on it. Additionally, a database user will need to be created with table creation privileges to this database. VarSeq will use this database and create tables to emulate the behavior of having access to multiple databases even though it only uses one database on the server.

After creating the required database and user on the MySQL server, select MySQL from the menu at the top of the dialog. Then enter the Host, Port, Database Name, Username, and Password into the dialog. Click Connect. If VarSeq has any problems communicating with the database, an error dialog will display helpful debugging information. Finally, enter the name of the “Assessment Catalog”. This catalog will serve as your assessment catalog.

Once OK is pressed in the Create Assessment Catalog dialog you will be directed to a Schema Editor.

Note

After creating a database, a configuration file will be stored in Common Data/AssessmentCatalogs folder in the Golden Helix directory created during the installation of VarSeq. These configuration files contain information about each database connection created. If you need to share configuration information between users, these files can be copied to the other users’ AssessmentCatalogs folder. In the case of SQLite, both a configuration file and a database file are created and either can be opened directly.

Editing Assessment Catalog Schemas

The fields associated with each variant are customizable through the Assessment Catalog Schema Editor. This editor will open automatically when a new assessment catalog is created or it can be accessed anytime an assessment catalog is open by clicking on “Assessment Catalog Gear” icon gearImage in the tab’s tool-bar.

Assessment Catalog Schema Editor

The schema editor

If no schema has been set, a template schema can be selected from the Combo Box in the lower right side of the schema editor. After a schema has been selected, the fields can be modified and reordered.

The name of the field can be modified by double clicking on the name in the table.

Different input widgets can be selected for the field. The available input widgets are:

  • Line Edit: Single line free-form text box
  • Multi-line Edit: Free-form text box
  • Integer Select: Text box which only accepts integers
  • Decimal Number Select: Text box which only accepts Real numbers to be entered
  • Combo Box: A menu selector
  • Radio: A radio button style selector (one and only one choice can be selected)
  • Checkbox: Single checkbox
  • Multi-Item Select: A checkbox style selector with multiple values (zero, one, or many choices can be selected)
  • Project: The project link contains a link (in the form of a file path) to the project containing the variant that was cataloged. Note that this project may not be accessible on your system if the variant was input on another computer.
  • Sample: The Sample ID is the name of the sample that was used when the VCF was imported.This ID is by default the ID that was used in the VCF, but the ID may have been overridden during import.

For selectors which require choices (Combo Box, Radio, Multi-Item Select), click the associated Set button to open a dialog which will allow a list of choices to be entered.

All widgets can have a default value. This is the value that will be used in the field if no previous assessment has been made or if the last entered assessment did not fill in a value for the field.

Each field can be set to pre-fill its value. The available options are:

  • Last Saved For Variant: If a previous assessment has been made for the variant, the last entered value for the variant will be used.
  • Last Saved For Sample: If a previous assessment has been made for any variant in this sample during the user’s session, the last used value will be used. This setting is useful for things like Phenotype which are constant for a sample.
  • Last Saved For Project: If a previous assessment has been made for any variant in the project during the current session, this value will be pre-filled into the field. This setting is useful for things that remain constant across an entire project, like lab id.
  • Always Cleared: Never pre-fill a value.

Each field can be set to be required. If this cell is checked, a user must select or enter a value for this field before saving.

Each field can have an associated hint. The hint is a short description of what the field should contain.

A field can have associated documentation. This documentation is accessible by hovering over the “i” icon in the form during variant entry.

The buttons to the right of the table control row ordering and the additional or removal of fields.

Once satisfied with the fields for your assessment catalog, click Save. The schema will be saved and you will be returned to the variant entry form. If you return to the schema editor, you will be able to modify schema and select previous schema versions.

To revert an assessment catalog to an earlier version of the schema, once the assessment catalog has been saved, and connected to a project, click on the Manage Assessment Catalog button and select the version in the history you wish to revert to and then click on Select.

To export the assessment catalog schema to apply to a new assessment catalog, click on Export.

Variant Entry

The variant entry form is connected to the variant table. The currently highlighted variant in the table is automatically loaded into the variant editor.

Variant Entry Form

The variant entry form

After entering any applicable information for the variant in the form click the save icon in the toolbar to save the assessment. The keyboard shortcut <Alt> + S can also be used to save the entry.

After saving the entry it will appear in the “Recent Assessments Using Current Schema” table. This table represents what any past assessment would look like using the the current schema. Since schemas can be changed, this will not always match what was entered at the time of assessment. To revert to a previous assessment, click the revert link. This action will fill the form with the values from that assessment. Click the save icon to save these values to the database.

Clicking the “X” icon in the toolbar “deletes” the variant from the assessment catalog. This clears the entry form and prevents the variant from being found in the assessment catalog during annotation. However, this action does not remove your previously created assessments.

Batch Assessment Import

All of the variants from a source can be imported into an assessment catalog. This is useful if you have an existing set of variant assessments that you want to work off of, or if you want to change assessment catalog backends. To open the importer click on the “Assessment Catalog Import” icon importImage in the tab’s tool-bar.

The first step is to select the input source. Note that the source must have a chromosome, genomic position, reference allele and alternate allele fields. After a source has been selected click Next >. If the file selected is a delimited text file you will be prompted to describe the format and select the chromosome and position fields from the file.

Assessment Catalog Field Mapper

Assessment Catalog Field Mapper

Next the fields in the selected input source need to be mapped to the fields in the assessment catalog. When an assessment catalog field is selected in the field table its assessment catalog attributes are displayed in addition to the mapping controls. By default each field will be Unmapped clicking Existing Source Field will allow you to choose from a list of source fields with a compatible types. Otherwise the field may be mapped to a Computed Field. Computed fields allow for the field to be specified from any combination of existing fields using the expression editor. For more information on the expression editor see the Expression Editor.

Finally the wizard will display the information for the variant source and destination catalog. Be sure to review this carefully before clicking next and starting the import.

Annotation Using the Assessment Catalog

The assessment catalog can be used for annotation and filtering just like other annotation sources.

To add the assessment catalog as an annotation source, click the Add button above the table and select Annotation.... In the selection dialog click on the Assessment Catalog folder on the left pane of the dialog. Place a check-mark next to the desired assessment catalog and click Select.

The annotation algorithm will run and a new column group with the name of the assessment catalog will be appended to the table. Each of the fields in the assessment catalog schema will be shown as a column. Filters can be created using these columns in the same manner as any other annotation source, see Table View for more information.

It is important to note that the annotation shown in the table will not be automatically updated as new assessments are added to the assessment catalog. A small infoImage will appear in the variant counter at the top of the table to signify that the source has changed. Clicking on the infoImage and subsequent message item will bring up a prompt to re-run the algorithm so that changes are reflected in the table.

Assessment Catalogs Hosted on VSWarehouse Server

VSWarehouse can host Assessment Catalogs. This makes it easy to share and iteratively collaborate on a centralized Assessment Catalog, which can then be used as an annotation source. See Warehouse Hosted Assessment Catalogs for further information.