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.The Database Record Type corresponds to the type of values that will be stored in the catalog.The supported types are:

  • Variant - Variant records are the initial records that are imported into VarSeq, and are specific to the genomic coordinates and the Ref/Alt of each input variant. Only records from this table can be added to this type of assessment catalog.
  • Region - Region records can be selected from LoH, CNV, or Coverage Regions tables. Each record is specific to the genomic coordinates of the selected record.
  • CNV - CNV records are specific to CNV tables as they use the genomic coordinates of the record as well as the type of record Gain, Loss, or CN Loh.

An optional Custom Key Field can be added to Region and CNV catalogs. When selected the records will be specific to the default record identifiers in addition to one of the following key types:

  • Sample Name - The will add the sample name of the current sample to each of the records that are added. This is a good choice for population catalogs as the records added are unique to each sample name. These records can the be used to see if a record has appeared in the past and at what frequency.
  • Text - The text type key allows for free form specification of text values to specify different sets of records. Values at a given position with different text keys will not affect one another when they are edited.
  • Choice - The choice key allows for a set of predefined values to differentiate different sets of values. The set of values must be defined at the time of catalog creation.

The nae of the Optional Custom Key field will be used to identify the field in the assessment catalog view, as well as when the catalog is used as an annotation.

New Catalog Dialog

The new catalog dialog.

Once the record type has been selected, select how the records will be stored by VarSeq. Three database backends are supported to store the catalog records, 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.

pDifferent 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.

Record Entry

The record entry form is connected to the Table type selector. The table type selector shows the different tables that exist in the current project which can be selected as inputs. The currently highlighted record in the selected table is automatically loaded into the record editor.

Record Entry Form

The record entry form

After entering any applicable information for the record 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.

If the catalog has a custom key the value can be changed by clicking the change button next to the current value in the form. This will open a dialog with the current value and a summary of the the other key values that have been used in the catalog.

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.

Additionally the “Related Assessments” table will display records at the same position, with different identifying keys.The identifying keys are the Ref/Alt field for variant assessment catalog, the Type field for cnv records, and the custom key field for the catalog if one was created. To update the current records to the values that are stored for a related record click the update link. This will fill the record entry form with the related record values and save it with the current selected key values.

Clicking the “X” icon in the toolbar “deletes” the record from the assessment catalog. This clears the entry form and prevents the record 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 records 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. This will open a drop down menu with options to Import from Table or Import from File. Select Import from Table to select one of the filtered tables from the current project as an input source. Alternatively select Import form File to import from an external file.

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 on the left, its assessment catalog attributes are displayed in addition to the mapping controls on the right. When importing from VarSeq the key field will be filled in based on the current selection, with fields mapped if the field have the same name, otherwise if importing from a file 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 Specific Value will set the value for all of the values imported into the assessment catalog.

The last page of the wizard before the import begins 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.

Local Assessment Export

All of the variants that are stored in local assessment catalogs can be exported as a VarSeq annotation file (tsf), or as a text file (tsv/txt). The annotation export allows for the creation versioned snapshots of an assessment catalog capturing it’s historical state. While assessment catalogs exported as text files allow for integration or analysis with 3rd party programs.

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.