Contents
Overview
Early Warning Alerts (EWA) are defined for a project. They are used to automatically detect for newly processed samples (query samples) samples with similar allelic cgMLST profiles (hit samples) that are already stored in the project. If similar samples within the defined thresholds are found, an EWA is triggered and stored in the database.
Defining cgMLST Early Warning Alerts
The cgMLST Early Warning Alert definitions can be created and managed by pressing the button Edit Project cgMLST Early Warning Alerts in the project editor below the task templates section. The button is only enabled if a cgMLST Task Template was added to the project. The button icon is grey if no EW-Alerts are defined, else it is colored red.
An EWA definition contains the following sections:
- Name of Early Warning Alert
- A name that can be used as a reference for this EWA definition. The name is shown in the alerts that are triggered. If only one EWA is defined for a project, the name can be left empty.
- cgMLST Task Template for Distance
- If the projects contains multiple cgMLST Task Templates the one to be used for distance calculation can be selected here.
- Allelic Profile Distance Criteria
- Defines the threshold for similar samples. By default, the cluster-alert threshold of the cgMLST Task Template is used. Alternatively a multiple of the cluster-alert threshold or an absolute allele distance can be chosen.
- By default all samples with more than 10% missing values will be excluded from the EWA search.
- Metadata Criteria
- Allows to define metadata criteria for the alert
- Limit by tags: Only query samples with the defined tag criteria will initiate the alert search, and only similar samples that fulfill the tag criteria will be reported as hit samples.
- Limit by same location: The hit sample must have the same location as the query sample. If the query or hit sample location field is empty the hits are nevertheless reported. The Country of Isolation or the City of Isolation can be selected as location field.
- Limit by date: The date of the hit sample must match within a given time period with the date of the query sample. If the query or hit sample date field is empty the hits are nevertheless reported. The Collection Date or Created for the sample entry creation date can be used as date field.
Hint: The alert searches are performed directly after a new sample is processed and stored. Therefore, the metadata (tag, location, and/or date) must be entered in advance (e.g., by spreadsheet import of metadata, pipeline tags, or spec files) if they should be used as limiting criteria in the EWA.
- Other Settings
- By default, alerts are visible for all users that can view the query sample. However, the definition dialog allows to limit the visibility of the triggered alerts to a specific user group. Users who don't belong to this group will not see the alert. The alert is always visible for the user who imported the sample that triggered the alert. If the alert is visible for certain users, all of those users can mark the alert as checked or delete the alert. This alert status applies then to all users who can view the alert.
- If merging is enabled, new alerts are merged with unchecked older alerts, if the query sample of an unchecked previous alert is among the hits of a newer alert, i.e., the new alert gets the query sample and all hit samples of the old alert assigned and the old alert is deleted. Please note that only unchecked alarms are merged into new alerts.
By pressing the OK button of the dialog the EWA definition is stored and active.
Performing cgMLST Early Warning Alert Searches
If Early Warning Alert(s) are defined for the project, the EWA search is automatically performed when a sample is processed in Pipeline Mode or when the command Process Assembled Genome Data is used to process already assembled genomes.
Evaluating Triggered cgMLST Early Warning Alerts
The three most recent and unchecked EWAs that were triggered are shown on the top of the home screen in the section 'Unchecked Early Warning Alerts". If they are opened by clicking on them, a comparison table with the involved samples is shown. The query sample, the former query samples of merged alerts, and the hit samples are grouped by colors in the comparison table.
On the bottom of the comparison table window three EWA specific buttons are available:
- Perform Recursive EWA Search
- In the original EWA search only hit samples are found, that are within the defined allelic threshold compared to the query sample. If the recursive EWA search is performed, all samples that are within the defined allelic threshold to any other hit samples are returned. This is repeated until no additional hit samples are found. The recursive EWA search also applies all limiting metadata criteria that were defined for the original EWA search recursively.
- Set Alert Checked
- Sets an unchecked alert to checked. The alert is automatically removed from the home screen but is still available in the database. The checked alert will not be merged into any newer alerts.
- Delete Alert
- Deletes the alert completely from the database.
- Hint: If it is intended to increase the discriminatory power for the EWA samples cluster the accessory genome targets could be added for distance calculation in the comparison table. First the command Columns | Add Additional Database Fields as Columns must be invoked and the appropriate Task Template must be selected. Next the command Columns | Select Genotyping Scheme for Distance Calculation must be issued and in the upcoming dialog the Accessory Task Template must be selected in addition.
Managing Triggered cgMLST Early Warning Alerts
In the Options main menu the command Browse Early Warning Alerts must be issued to list all triggered EWAs that are visible for the user in a table. By default the alerts are sorted according to the triggering date. The table can be filtered for unchecked alerts only (default) and/or for a time period. The button panel on the right (or the right-click menu) can be used to set multiple alerts as checked or to delete them. Additionally, a comparison table can be opened by pushing the button Show Samples of Alert (or by double-clicking in a row) for a selected alert containing all samples that are involved in the alert.