Overview

Comparison Table. The column that is used for coloring the samples has a red background in the header (ST). The columns that are used for distance calculation have a dark green background in the header.

The Comparison Table of SeqSphere+ is used to compare and visualize Sample data. Each row of the table represents one Sample and each column represents a metadata field. Color groups can be used to group and highlight Samples according to values of a column.

A selection of multiple columns can be used for distance calculation (e.g., allele type columns). The calculated distances can be used for various analysis functions (via Analysis menu or toolbar button):

  • a Mst.png minimum spanning tree (MST) can be calculated and opened in a new window
  • a DrawTree.png neighbor-joining or UPGMA tree can be calculated and opened in a new window
  • a Distancematrix.png distance matrix can calculated and opened
  • a neighbor-joining or UPGMA can be calculated and included as first column in the table. Thereby the table can be ordered by position of Samples in the phylogenetic tree
  • a SetComparisonSample.gif comparison Sample can be set. Distances to this comparison Sample are then calculated for all other Samples, and the differing values are highlighted in orange

The functions SNV.png Find SNVs and SNV groupspec.png Find Group Specific SNVs in Distance Columns can be used to find SNVs in Samples or group of Samples.

The place and time information of Samples can be visualized with a Showmap.png geographical map and an Epicurve16.png epi curve.

Comparison table and minimum spanning tree content and layout (including coloring) can be stored in snapshots for later reuse. The Sample search criteria, epi and procedure metadata column layout, and used genotyping schemes can be stored in retrievals for later reuse.

Opening Comparison Tables

Select Button16-ComparisonTable.png Tools | Comparison Table from the menu to open the Comparison Table dialog with three different tabs, that allow to open comparison tables using three different ways:

  • Create New
This tab panel can be used to create and open a new comparison table with Samples from a whole Project, a selection of Samples from database (e.g., from multiple Projects or by using other advanced search criteria), or from Samples that are currently loaded. In addition Epi and Procedure Metadata Fields and Genotyping Schemes that should be included in a Comparison Table can be chosen here. When the newly created comparison table is opened, it retrieves the Sample data from the database. If not stored as a snapshot the comparison table is not permanently preserved.
  • Stored Snapshots
This tab panel shows all stored Comparison Table Snapshots that are visible for a specific user (by default stored snapshots are only visible for the user storing the snapshot) and allows to open a comparison table from a stored snapshot. A comparison table that is opened from a snapshot contains not necessarily the current data of the database but shows instead the data as they existed when the snapshot was stored. Therefore, a snapshot may even contain Samples that were in the meantime deleted from the database. The panel can also be used to export, edit properties, or delete snapshots. Furthermore, snapshot favorites that should be shown permanently on the SeqSphere+ home screen can be defined here.
  • Stored Retrievals
This tab panel shows a drop-down list with all stored Comparison Table Retrievals that are visible for a specific user (by default stored retrievals are only visible for the primary group of the user storing the retrieval) and allows to open a comparison table from the stored Sample search criteria, epi and procedure metadata column layout, and used genotyping schemes of a retrieval. A comparison table that is opened from a retrieval contains the current data from the database. Therefore, no Sample data are stored in a retrieval but only the search criteria for Samples and the selection of metadata fields. The panel can also be be used to create new retrievals or to manage (edit, delete, access control, etc.) retrievals.

A Comparison Table can also be opened from the 'Search Samples' in database dialog after selecting samples in the result table.

By default a comparison table contains the following columns in the listed order:

  • #Missing values in Distance Columns
  • Per. Good Targets (if a cgMLST task template is available in the Project)
  • Average Coverage (Assembled)
  • Sample ID
  • ST (if a MLST task template is available in the Project)
  • Cluster Type (if a public cgMLST task template is available in the Project)
  • Epi Info
  • Cluster/Outbreak
  • Collection Date
  • Country of Isolation
  • City of Isolation
  • ZIP of Isolation
  • Lat/Long of Isolation
  • Lat/Long of Resolution
  • all cgMLST allele types for distance calculation (if a cgMLST task template is available in the Project and selected in the Genotypings section)

Color Groups

Color Groups are used to highlight Samples in different colors. The menu command Button16-GroupByValues.png Set Color Groups by Column Values can be used to create and assign color groups based on the values of a specific column. By default, the Samples are colored according to the values in the MLST 'ST' column. If this columns is not present, Samples are color by the 'Epi Info' column if it exists, or else by the cgMLST 'Cluster Type' column values.

The column that is currently used for coloring is highlighted with a red column header in the table.

To edit, export, and import color groups select the command Manage Color Groups from the Data menu. A new dialog will open that contains an editable list of all existing groups. Each color group is defined by a name and a color.

A color group can also be manually assigned to Samples, by selecting Samples in the Comparison Table, and choosing the menu command Data | Set Color Group for Selected Samples (or via the comparison table entry context menu).

Distance Calculation

Some functions (e.g., trees) require that one or more columns are selected for distance calculation. The columns that are currently selected for distance calculation are highlighted with a green column header.

By default, all target columns (i.e., allele types) of the chosen genotyping schemes are used for distance calculation.

The selection of columns for distance calculation can be modified in three ways:

  • by using CheckSomeDistance.png Select Genotyping Schemes for Distance Calcuation (via Column menu or toolbar button) to select or unselect genotyping schemes,
  • by clicking the right mouse button on the column header and selecting or unselecting the chekbox Use in Distance Calculation,
  • or by using ModifyColumnSettings.png Modify Column Settings (via Column menu) to open a dialog for managing the columns.

The selection of columns for distance calculation may also be modified by the missing values dialog. This dialog appears if missing values were found during distance calculation. If the option to exclude columns is selected in this dialog, then the columns are removed from distance calculation, until they are manually selected again.

Data Types

Each column has a data type. Usually, the predefined data types are adequate. The data types can be changed in two ways:

  • by using the ModifyColumnSettings.png Modify Column Settings (via Column menu) or
  • by clicking the right mouse button on the column header. This opens a context menu, that allows choosing the data type for a column.

Menu

File

  • Button16-Snapshot.png Save Comparison Table Snapshot (including open MST)
  • Export Comparison Table Snapshot to File
  • Export.gif Export Table Data (csv/xlsx): Exports the table in various formats
    • MS Excel (.xlsx): exports the table data including the table cell colors
    • MS Excel 97-2003 (.xls): exports the table data only
    • CSV-file: exports the table data as comma separated values file
    • HTML-file: exports the table data including the table cell colors as HTML table that can be viewed in a web browser
    • PNG-file: exports the complete table including if used a tree in the table as image
  • Button16-Import.gif Add Table Rows from File: Adds data to the current table from a MS Excel files (.xlsx, .xls) or CSV file
  • Refresh Comparison Table from Sample database content: Closes the table, reloads the data for all Samples of the table from the database, and opens a new table with these data
  • Close: Close the Comparison Table window and all dependent windows (e.g., MST)

Edit

  • Select All: Selects all displayed Samples
  • Select None: De-selects all displayed Samples
  • Invert Selection: Inverts the current selection. All unselected Samples are selected, and all selected Samples are unselected
  • Select Samples with Missing Values: Allows to select Samples that contain missing values in more than a specified percentage of columns for distance calculation
  • Select Samples By Color Group: Allows to select Samples that belong to a specific color group
  • Find.png Find: Searches for values in the complete table or in specific columns. The search ignores upper/lower-case
  • Undo.gif Undo: Undoes the last command (only available for some commands like remove)
  • Redo.gif Redo: Does the last undone command again (only available for some commands like remove)
Restore from Exclude List
Set Sample Filter
Modify Column Settings
Merge Columns

Data

  • Add Additional Samples to Table: Chooses additional Samples from the database and add them to the table
  • RemoveFromTable.png Remove Selected Rows from Table: Removes selected Samples from the table
  • Remove All Unselected Rows from Table: Removes all but the selected Samples from the table
  • AddToExclude.png Moves Selected Rows to Exclude List: Moves selected Samples to the exclude list. The Samples on this list are not used in calculation anymore, but can be restored easily using the command Restore from Exclude List
  • Move All Unselected Rows to Exclude List: Moves all but the selected Samples to the exclude list. The Samples on this list are not used in calculation anymore, but can be restored easily using the command Restore from Exclude List
  • RestoreExcludeList.png Restore from Exclude List: Opens a window with all Samples in the exclude list and the option to remove Sample(s) from this. Those Sample(s) are re-added to the comparison table. Hint: Use CTRL to select multiple Samples.
  • Hide in Geo Map and Epi Curve: Hides selected Samples from geographical map and epi curve
  • SampleFilter.png Set Sample Filter: Opens a window to select a filter. Only Samples that match the filter criteria (e.g., coverage, etc.) are displayed in the table and used in distance calculations. Clear filter to reconstitute all Samples again
  • Manage Color Groups: Opens a window for managing all existing color groups. Color groups can be added or removed, and the names and colors of existing groups can be modified
  • Set Color Groups: If one or more Samples are selected, this sub-menu can be used to assign groups to the Samples. Select No Group to remove the Samples from a color group. Create New Group creates a new color group
  • Button16-GroupByValues.png Set Color Groups by Column Values: Automatically creates groups based on the values that are present in a column and assigns Samples to these groups according to these values

Columns

  • ModifyColumnSettings.png Modify Column Settings: Opens a window to select the Data Types for each column and to choose which columns should be used for distance calculation
  • Select Genotyping Schemes for Distance Calculation: Allows to select one or multiple genotyping schemes for distance calculation
  • Merge Columns: Creates a new column from two given columns. A separator can be specified that is used to separate the content of the two columns
  • Button16-DB.png Add Additional Database Fields as Columns: Allows to add additional fields from the database to the comparison table
  • Remove Dist. Columns where Any Value Is Missing: Removes all distance columns that contain at least one missing value in a cell
  • Remove Dist. Columns Where All Values Are Missing: Removes all distance columns that contain missing values in all cells (ignoring missing values)
  • Remove Dist. Columns with Identical Values: Removes all distance columns that contain the same value in all cells
  • Show Column with Count of Missing Values: When selected, the number of missing values in distance columns is the first column for each Sample
  • Highlight Missing Values in Distance Columns: Highlights all missing values in distance column cells

Analysis

  • SetComparisonSample.gif Set as Comparison Sample: Only available if exactly one Sample is selected. The selected Sample is used as Comparison Sample, and distances to all other Samples are calculated. Note that at least one column must be selected for distance calculation.
  • RemoveComparisonSample.gif Remove Comparison Sample: Only available if a Sample was selected as Comparison Sample. Removes the Comparison Sample and the distance column.
  • Distancematrix.png Distance Matrix: Shows a distance matrix based on the columns that are currently selected for distance calculation.
  • Tree in Table: Select either UpgmaTree.png UPGMA-Tree in Table or NjTree.png NJ-Tree in Table to draw such a tree in the table. The tree is based on the columns that are selected for distance calculation. The Samples in the table are ordered according to their position in the tree. Choose NoTree.png No Tree in Table to remove the tree from the table
  • DrawTree.png Neighbor-Joining Tree: Opens a Neighbor-Joining Tree window to display either a NJ- or UPGMA-tree
  • Mst.png Minimum Spanning Tree: Opens a Minimum Spanning Tree window to display a MST-tree

Tools

  • Copy Distance Column Names to Clipboard: Copies the names of the distance columns to the clipboard for further usage (e.g., only not identical targets, etc.)
  • Show Target Information for Distance Columns: Opens a window with all available target information of the distance columns (e.g., gene names)
  • SNV.png Find SNVs in Distance Columns: Opens the Find SNVs dialog
  • SNV groupspec.png Find Group Specific SNVs in Distance Columns: Opens the Find Group Specific SNVs dialog
  • Calculate Discriminatory Index
  • Calculate Typing System Concordance
  • Calculate Color Groups Statistic
  • Epicurve16.png Show Epi Curve: Opens a window with an Epi Curve
  • Geocoding.png Do Geocoding: Opens a Geocoding window that allows to assign Latitude and longitude coordinates to zip codes, city-, state- and/or country-names
  • Showmap.png Show Geographical Map: Opens the Map window that displays the Samples on a map
  • Show Four Dimensions: Opens all 'four dimensions' at once: place (geo map), time (epi curve), 'person' (comparison table), and type (minimum spanning tree)

Context menu

Clicking in a row of the comparison table with the right mouse button opens a context menu which contains a subset of the commands described above.

Toolbar

The comparison table toolbar contains a subset of the commands described above.