User Manual
+ +
+
+PhyloTrace Version 1.5.0
+Web: www.phylotrace.com
+Contact: info@phylotrace.com
+Github: https://github.com/infinity-a11y/PhyloTrace
+PhyloTrace is a platform for bacterial pathogen monitoring on a +genomic level. Its components evolve around Core-Genome Multilocus +Sequence Typing (cgMLST) and Antimicrobial Resistance Screening. Complex +analyses and computation are wrapped into an appealing and +easy-to-handle graphical user interface. Users build a local database +comprising analyzed isolates, manageable directly with the application. +The visualization of isolate relationship and genetic profile is highly +interactive, aiding to reveal patterns explaining outbreak dynamics and +events by connecting genomic information with epidemiologic variables. +PhyloTrace achieves universal compatibility by assigning unique hashes +based on sequence and allele information. This implementation enables +efficient comparison and sharing of inter-lab results.
+PhyloTrace is supposed to be used for research and +academic purposes only.
+1 Launch Application
+Install the application by following the steps disclosed in the README +document on GitHub. Launch PhyloTrace from the applications menu of your +system. The app runs in the system’s default browser. PhyloTrace is +optimized for Chrome, Chromium, Brave as well as Opera and Vivaldi. +Avoid using Firefox as some elements are distorted or not visible at +all.
+2 Loading Database
+PhyloTrace doesn’t force but encourages to build a local database and
+iteratively add new bacterial isolates together with respective allelic
+profile and meta data. Upon first launch either load an already existing
+database or create a new one.
+2.1 Creating New Database
+To start completely from scratch with no previously built database
+available, select + Create New on the start screen
+(Figure 1) and choose a path where the database should
+be built. A folder named Database will be created in the
+respective location. Make sure to select a location that has writing and
+reading permission. Since there are no entries added or schemes
+downloaded yet, the database is empty and you are immediately directed
+to the > Manage Scheme tab after
+clicking on Load. The drop down menu lists all bacterial
+species that are available in the cgMLST.org Nomenclature Server
+(h25). Selecting a species will display information about the
+scheme, such as the seed genome or the curators. Pick the species you
+want to work with and press Download. You can now proceed
+to type the first assemblies belonging to the respective bacterial
+species (see 3 Allelic Typing).
+
+2.2 Loading Existing Database
+If you or your working group / institution has already used
+PhyloTrace before, they might have saved the respective database folder
+on the internal file system. Click Browse on the start
+screen (Figure 1) and select the path of the database
+folder. PhyloTrace will automatically recognize if the selected folder
+contains compatible data.
The database is structured by folders for each bacterial species you
+have worked with (see Figure 3). Therefore, when
+loading a local database, select which species you want to work with in
+this session. For example, if the database contains entries typed with
+Bordetella pertussis, Burkholderia pseudomallei and
+Klebsiella pneumoniae schemes, you can choose between one of
+them. Proceed by clicking on the Load button. The database
+section containing data regarding the selected strain will load.
+
+If the already existing database doesn’t include the strain you want
+to work with, pick any arbitrary strain and load the database. Then head
+over to the > Manage Scheme tab and
+select your desired bacterial species from the list. Proceed to download
+the scheme files comprising gene variants and scheme info by clicking
+Download. After the download is complete you are prompted
+to load the database again (see Figure 4). Select the
+strain which was just downloaded and confirm. Proceed to start the first
+typing process for this species (see 3 Allelic
+Typing).
+2.3 Switching Database
+The currently loaded species/scheme is displayed on the top of the +sidebar below the PhyloTrace logo. If there is more than one scheme +available in the current database directory, it can be changed in the +same session. To switch, click the button next to the displayed scheme +and choose the new one. After confirmation, the database is loaded with +the newly selected scheme. If you like to switch to a scheme present on +a database located in a different directory, restart the app and select +the respective path linking to this database folder.
+3 Allelic Typing
+The typing process is the fundamental step which generates the data +(i.e. the allelic profile) for the genomic comparison. The method +applied is based on core-genome multi locus sequence typing (cgMLST). An +allelic profile is generated for selected bacterial isolates. The +allelic profile determines, which allele variants are present for each +gene in the cgMLST scheme. If the process was successful, the results, +i.e. the allelic profile of the respective isolate as well as +epidemiologic meta data, are added as entry to the local database (see +4 Database Browser). By repeating this +process with further isolates, a foundation for a library of bacterial +isolates is created. Technically there is no limit for the number of +entries in the database, although the performance might be reduced if +there are several hundred entries in the currently loaded scheme +(depends on system capacity). The variant calling and alignment steps of +the typing process are facilitated by BLAT (BLAST-like Alignment Tool) +for whole genome assemblies and KMA (k-mer alignment) algorithm +for raw reads 1,2. Allelic +typing for raw reads will be available soon.
+3.1 Single Typing
+In the sidebar of the
+> Allelic Typing tab select
+☑ Single | ☐ Multi (see Figure 5).
+Clicking on Browse will open a window so that an assembly
+file from the local system can be selected. Any of the commonly used
+FASTA file formats (.fasta, .fna or .fa) are accepted. Selecting an
+incompatible file type will inhibit the start of the typing process.
+Make sure that the assembly files contains sequence data of a bacterial
+species that matches the selected scheme. Afterwards the basic meta data
+(i.e. Assembly ID, Assembly Name,
+Isolation Date, Host, Country,
+City) can be declared. Filling out every field is not
+mandatory if you don’t wish to or don’t have the respective information.
+Note, that the Assembly ID has to be unique, proceeding is
+not possible if the same name is already present in the local database.
+Except for the Assembly ID these isolate variables can
+still be change afterwards in the
+>> Browse Entries tab. Clicking on
+Confirm will save the metadata and render the process
+executable.
+Before starting the process, select whether to save the assembly file
+to the local database. If an assembly file is not saved, screening for
+resistance and virulence genes will later not be available for the
+respective isolate (see 5 AMR Screening).
+The assembly file can not be added in retrospect. Pressing
+Start will launch the typing process. The alignment
+algorithm is now searching the selected assembly for the alleles
+contained in the scheme and checking which variant is present. The
+loading bar provided feedback on this progress. The duration varies
+depending on the capability of your system and the number of alleles and
+variants included in the scheme and can take a while. Once 100% is
+reached the typing results are evaluated and appended to the local
+database. Database changes in the tab
+>> Browse Entries are automatically
+inhibited during this finalization step to avoid issues. After this last
+step is finished you can reset to start another one. If the typing was
+successful, the addition of a new entry is indicated by a pulsating
+button in the >> Browse Entries tab.
+Click this button to load the updated database including the newly added
+entry.
3.2 Multi Typing
+Multi typing is recommended for larger collections of several
+assemblies belonging to the same species. This saves the time needed to
+start the process one by one. In the sidebar of the
+> Allelic Typing tab switch to
+☐ Single | ☑ Multi and click on Browse to
+select a folder containing the assemblies. If you plan to type just a
+subset of the selected folder, untick the unwanted assemblies in the
+table below and choose a compatible Assembly ID. The multi
+typing process is only startable if no incompatible files are ticked.
+Because all the files are seamlessly piped into the process the basic
+meta data can be only declared once for all assemblies. The values
+declared for Isolation Date, Host,
+Country and City will apply for every new
+entry that is produced in this multi typing process. The
+Assembly Name will first be identical with the
+Assembly ID, representing unique identifiers of the
+assembly. The file name of the respective assembly is automatically
+assigned to both. However all of the basic meta data values, except
+Assembly ID, can be changed in retrospect once the entry
+has been successfully added to the database. After confirming the
+metadata the Start button will be rendered. Note, that if
+the assembly file is selected not to save to the local database,
+screening for resistance and virulence genes will not be available for
+the respective isolate later (see 5 AMR
+Screening). The assembly file can also not be added in retrospect.
+Upon starting the multi typing process, a field where the progress is
+logged is displayed. The process can be monitored with this overview.
+The log of the multi typing process can be downloaded as text file.
+Notifications, providing feedback about the status of the multi typing
+process, show up for every relevant event, such as the (un-)successful
+addition of an entry or the finalization of the multi typing process. A
+pending typing process can be canceled by clicking
+Terminate. During the process is in the typing or alignment
+phase (indicated by Processing in the log), you can keep
+working with PhyloTrace, e.g. visualizing or editing the local database.
+However, just as for single typing, the app is automatically recognizing
+when the process is switching to the evaluation and addition phase
+(indicated by Attaching in the log), hence any database changes
+are prohibited. After each successful addition you can reload the
+database in the >> Browse Entries
+tab, to inspect the new entry. Unsuccessful typing attempts are captured
+in the log and in the multi typing summary once the process has been
+finalized (see Figure 6). Individual results can be
+inspected by choosing them from the selector in the right column.
+Displayed are only notable events in which e.g. a new allele variant was
+found or unsuccessful allele calling attempts. Press Reset
+to start another multi typing process.
+3.3 Variant Assignment
+After each variant from the cgMLST scheme has been searched and
+aligned to the assembly, the results are evaluated to determine which
+allele variant is present for each locus. This is conducted by a
+conditional multi-step process that ensures correctness and minimizes
+false positive assignments. The steps and the logic applied in this
+process are shown in Figure 7. If none of the variants
+from the scheme could be found in the bacterial isolate, the presence of
+a potential new gene variant is evaluated (see 3.3.1 New Variant Validation).
+
+3.3.1 New Variant Validation
+In case none of the variants from the locally available scheme match
+perfectly, the locus is checked for the existence of a new and valid
+variant. To ascertain whether this variant is valid, the locus must
+fulfill conditions such that it is likely to encode a gene. If there are
+multiple different nucleotide regions in the assembly possibly coding
+for a gene, each of them is sorted and passed through the validation
+logic (see Figure 8).
+3.4 Calculation of Allelic Distance
+Unlike the genetic distance between a pair of sequences, summing up +the number of positions in which nucleotides are different, the +calculation of allelic distance considers entire loci/alleles for the +calculation. To receive the allelic distance, algorithms based on the +distance calculation method employed by Hamming in 1950, originally +meant for information technology, are used3. The Hamming distance is a +metric that quantifies the discrepancy between two strings of equal +length. It calculates the number of positions where the characters +differ between the two strings. Essentially, it indicates the minimum +number of substitutions required to transform one string into the other. +For cgMLST with PhyloTrace, hashes, i.e. 64-bit words, organized in an +array represent the allelic profile. The positions of the array elements +correspond to the loci in the scheme and the hash represents the allele +sequence for the respective locus. This allelic profile is generated +during the typing process. Thus, for pairwise comparison of the allelic +profile of two isolates, the total number of discrepant alleles result +in the allelic distance value. Comparing a selection of isolates results +in a distance matrix (see 4.4 Distance +Matrix), which are then used to compute a tree (see 6 Visualization).
+3.4.1 Missing Value Handling
+If no variant could be assigned for some genes contained in the +scheme, NA values are be placed in the allelic profile for the +respective position of the gene/locus. This can happen either if the +corresponding gene is not found in the assembly sequence, if there are +multiple hits or when the variant in the assembly is non-coding (refer +to 3.3 Variant Assignment).
+In order to showcase how allelic distances are calculated for
+isolates with missing values, we set up an example. For simplicity
+reasons we consider just three isolates, Isolate 1,
+Isolate 2 and Isolate 3 with three loci only,
+Locus A, Locus B and Locus C. For
+Isolate 1 let Locus A have variant 1,
+Locus B a missing value NA and Locus
+C variant 1. For Isolate 2 let Locus
+A be a missing value NA, Locus B
+variant 1 and Locus C variant 1. For
+Isolate 3 let Locus A be 2, Locus
+B also 2 and Locus C 1.
allelic_profile <- data.frame(A = c(1, NA, 2), B = c(NA, 1, 2), C = c(1, 1, 1),
+ row.names = c("Isolate 1", "Isolate 2", "Isolate 3"))
+allelic_profile## A B C
+## Isolate 1 1 NA 1
+## Isolate 2 NA 1 1
+## Isolate 3 2 2 1Option 1: Ignore missing values for pairwise +comparison
+Selecting the first option as missing value handling strategy, will +have NA’s ignored in the pairwise comparison between two isolates. +Unlike Option 2, only single missing values are ignored, not the entire +locus.
+# Option 1
+
+hamming.distIgnore <- function(x, y) {
+ sum( (x != y) & !is.na(x) & !is.na(y) )
+}
+
+proxy::dist(allelic_profile, method = hamming.distIgnore)## Isolate 1 Isolate 2
+## Isolate 2 0
+## Isolate 3 1 1The pair isolate 1 & 2, each have an NA for one of the first two
+loci A and B with the third locus
+C being identical. Their allelic distance is 0,
+hence these two isolates are considered identical in their allelic
+profile. The two other pairs Isolate 1 & 3 as well as 2 & 3 both
+result in an allelic distance of 1.
Option 2: Omit loci with missing values for all +assemblies
+If the second option is selected, loci containing at least one +missing value, will be ignored for the calculation of allelic distances. +Unlike Option 1, the loci with missing values are entirely omitted for +all pairwise comparisons. Even if an isolate pair might both have valid +variant numbers for a locus, it is not included in the analysis if the +locus contains just one NA for another isolate. For the missing +value statistics shown in Figure 10 [5.5 Missing +Values], 41 loci, displayed as columns in the missing value table, would +not be considered for the distance calculation. For this option the +respective loci are filtered out from the allelic profile before +applying the distance computation. Because of the potential to skew the +whole picture with this option, choosing it is only recommended if there +are very few afflicted loci with missing values.
+# Option 2
+
+hamming.distOmit <- function(x, y) {
+ sum(x != y)
+}
+
+allelic_profile_noNA <- select(allelic_profile, -A, -B)
+
+proxy::dist(allelic_profile_noNA, method = hamming.distOmit)## Isolate 1 Isolate 2
+## Isolate 2 0
+## Isolate 3 0 0Locus A and B are omitted before
+calculating the distance. This leads to all isolates being considered
+identical with an allelic distance of 0, because they all carry
+variant 1 for the only remaining locus C.
Option 3: Treat missing values as allele variant
+The third option is rather specific and, considering the consequences +for subsequent calculation of allelic distances and analyses, should be +used with caution. Here, NA values are treated as if they were +a separate variant.
+# Option 3
+
+hamming.distCategory <- function(x, y) {
+ sum((x != y | xor(is.na(x), is.na(y))) & !(is.na(x) & is.na(y)))
+}
+
+proxy::dist(allelic_profile, method = hamming.distCategory)## Isolate 1 Isolate 2
+## Isolate 2 2
+## Isolate 3 2 2Due to both NA’s being considered a further valid variant. +All isolate pairs receive an allelic distance of 2.
+Depending on the options for NA handling applied to these two allelic +profiles, the result of the allelic distance will be different. The +results of these example calculations are summarized in the table +below.
+| +Pair + | ++Option 1 + | ++Option 2 + | ++Option 3 + | +
|---|---|---|---|
| +Isolate 1 & 2 + | ++0 + | ++0 + | ++2 + | +
| +Isolate 1 & 3 + | ++1 + | ++0 + | ++2 + | +
| +Isolate 2 & 3 + | ++1 + | ++0 + | ++2 + | +
4 Database Browser
+The > Database Browser tab allows to
+examine and manage information saved in the local database of the
+selected scheme. It is divided in the
+>> Browse Entries,
+>> Scheme Info,>> Loci Info,
+>> Distance Matrix and
+>> Missing Values tabs.
4.1 Browse Entries
+Each assembly that has been successfully typed is added to the table
+in >> Browse Entries. This overview
+allows to edit (see 4.1.1 Edit Meta Data),
+delete (see 4.1.3 Delete Entries), inspect
+(see 4.1.4 Browse the Allelic
+Profile) and add (see 4.1.2 Custom
+Variables) information connected with the entries. The table can
+also be downloaded (see 4.1.5 Download
+Entry Table). The table contains both, the meta data and the allelic
+profile for each entry. The meta data as well as custom variables (see
+4.1.2 Custom Variables) appear first on
+the left part of the table, while the allelic profile with the assigned
+variants is positioned on the right part of the table (see 4.1.4 Browse the Allelic
+Profile). The Index automatically assigns a number to
+each entry and is eventually updated if entries are deleted (see 4.1.3 Delete Entries). The
+Include status decides over the inclusion or exclusion of
+the respective entry for further analyses, such as Visualization (see 6 Visualization).
4.1.1 Edit Meta Data
+The basic meta data comprising Assembly Name,
+Isolation Date, Host, Country and
+City can be edited in the entry table by left-clicking in
+the corresponding field. As soon as changes are detected, a pulsating
+button appears, that saves the changes on click. If you decide
+otherwise, press the Undo button and go back to the
+previous state. Assembly ID is the name of the isolate in
+the Isolate directory of the local database and can’t be
+changed. The Index number as well as the assigned hashes
+representing the allele variants in the allelic profile also can’t be
+edited because it would vitiate the analysis.
+>> Browse Entries overview with
+several options and functions to manage the local database.4.1.2 Custom Variables
+There is also the option to add custom variables using the controls
+in the >> Browse Entries sidebar.
+Choose a name for the variable and press the green + button
+to add it. In the dialogue window select the variable type, categorical
+(character) or continuous (numeric). After confirmation the variable is
+ready to be filled with values. These can be changed in retrospect in
+the same way as basic meta data (see 4.1.1
+Edit Meta Data). Note, that the database needs to be saved,
+otherwise the custom variables are not permanently added. The custom
+variable type and name can’t be changed in retrospect, but they can be
+deleted by selecting them from the drop-down menu in the sidebar and
+clicking the red - button. If more than five custom
+variables are present, a table summarizing them is displayed in the
+sidebar.
4.1.3 Delete Entries
+The Delete Entries panel on the top right corner of the
+>> Browse Entries tab allows to
+delete single or multiple entries at once. Select one or multiple
+entries to be deleted according to their Index in the
+drop-down menu. Clicking the red x button will open a
+dialogue window, prompting for confirmation about the intention to
+irreversibly delete the selection. The deletion will lead to a complete
+removal of the respective entry together with all the meta data, custom
+variable values and allelic profile. However, if the database is not
+saved after the deletion, it will appear again in the next session or
+could also be undone with the Undo button in the same
+session. Note, that if you select all entries
+for deletion, confirmation will immediately and irreversibly empty the
+database for the currently selected scheme and you will
+not have the option to undo this action.
4.1.4 Browse the Allelic Profile
+Scrolling the entry table to the right will reveal the allelic
+profile. The variant numbers for each allele/locus are sorted
+column-wise for each entry. By default, only the first 20 loci are
+displayed. Its possible to manually change, which loci are shown by
+selecting or deselecting them in the Compare Loci panel on the
+right below the Delete Entries panel. The respectively assigned
+hash, representing distinct allele sequences is truncated to the first
+and last four digits. Locus columns, containing at least one entry with
+an allele variant that is different from the others, are highlighted in
+green.
+If the Only Varying Loci option is activated, only loci
+with differing variants (i.e. the columns highlighted in red) are
+displayed. For missing variant values, i.e. if no variant could be
+allocated to a locus (see 3.4.1
+Missing Value Handling), the corresponding cell appears empty.
4.1.5 Download Entry Table
+The entry table can be downloaded as CSV file. There are two options
+to control this output. As the user sometimes might choose to only
+include a subset of entries in a current analysis, there is the option
+to include only the entries of interest in the output file. Activate the
+switch Only included Entries to include only the entries
+that are checkmarked in the Include column. Control the
+Include status either by checking or unchecking the
+checkboxes in the Include column or select or unselect all
+at once by using the buttons on the top-left of the entry table. Note
+that the database has to be saved for the changes to take effect. The
+Index of the entries marked as included are highlighted in
+green and exclusively selected to be considered in visualization (see 6 Visualization). Moreover you can choose if
+and which loci should be included in the download. By default only the
+meta data and custom variables of the entries are included in the csv
+file. If you activate the switch Include Displayed Loci,
+the currently displayed loci are included as well. Use the control in
+the Compare Loci box, to decide which and how many loci are
+displayed. Upon clicking the Download button you can choose
+to which location on your system the file should be saved.
4.2 Scheme Info
+The tab >> Scheme Info allows to
+inspect the properties of the currently selected scheme. The table
+displays information regarding the cgMLST scheme downloaded from the cgMLST.org Nomenclature Server (h25).
+It comprises the name of the scheme, the version, the seed genome, genus
+and species, the number of loci included, the complex type distance and
+count parameters, the date of the most recent changes, the official
+curators, publications addressing this scheme as well as the accessory
+scheme.
+>>Scheme Info tab showing information about
+a Bordetella pertussis scheme from cgMLST.org.4.3 Loci Info
+The overview in the tab
+>> Loci Info provides information on
+the loci included in the scheme as well as the distribution of alleles
+among isolates present in the local database. The table allows to browse
+the Locus ID (e.g. BP0001, BP2483), if known the gene identifier
+(e.g. glpK, pykA), the position of the loci in the seed genome, the
+length in nucleotides (e.g. 1233), the gene product (e.g. pyruvate
+kinase, chromosome partitioning protein) as well as the number of
+variants included in the base scheme. There is the option to filter the
+table by keywords or numbers. Note, that this applies to all attributes,
+so searching for “566” would result in the display of loci having an ID
+that includes this number (e.g. “BP0056”, “BP0566”, “BP1566”, etc.), or
+position (e.g. 317566, 1255669), length (e.g. 1566) and every other
+attribute containing the keywords or numbers.
+>> Loci Info tab
+showing information on the selected locus BP0008 with allele sequences
+and frequency.Selecting a locus from the table will render alleles present in the
+database and their respective DNA sequence. Browse alleles by choosing
+them from the selector showing the respective frequency of the selected
+allele in the database. The sequence can be copied to the clipboard. A
+FASTA file comprising all hashed allele sequences from the currently
+selected locus can be exported with Save FASTA. To export
+the table with metadata of all loci included in the scheme, click the
+download button right next to the header Loci at the top.
4.4 Distance Matrix
+The tab >> Distance Matrix shows
+a heatmap matrix of the allelic distances between the entries. For
+details on how the allelic distances are derived refer to 3.4 Calculation of Allelic
+Distance. For each pair of entries, the sum of allele variants that
+are not identical, i.e. allelic distance, is displayed in the respective
+cell. Here the choice, how missing values, i.e. entries having
+unsucessfull variant allocations for some loci, can have both small and
+big impact for the values and depends on different parameters (see 3.4.1 Missing Value Handling). In
+addition to the visualization with tree plots, changes in the missing
+value handling strategy can be directly observed in this overview. The
+readability of the matrix is enhanced by a heatmap. The values contained
+are normalized resulting in a color gradient from light green to dark
+red. The lowest value, which is always 0 in the diagonal (allelic
+distance of the same entry logically is zero), is highlighted in light
+green. The highest value (dark red) varies and depends on the highest
+allelic distance value in the matrix.
+There is the option to change the appearance of the matrix. Choose
+whether Assembly Name, Assembly ID or
+Index is displayed as column or row headers. As sometimes
+the focus might be centered on the subset of entries that are marked as
+included ion the entry table, the switch
+Only Included Entries can be toggled to show only this
+selection. Also the display of the diagonal line and the upper triangle
+can be activated or deactivated using the switches
+Show Diagonal and Show Upper Triangle
+respectively. The distance matrix can be downloaded as CSV file. Note,
+that the matrix is downloaded as currently displayed, including all the
+changes made to the appearance (e.g. with or without diagonal or
+Index instead of Assembly Name as header).
4.5 Missing Values
+Missing values occur if a locus can not be found in the assembly or
+if the present allele contains mutations leading to a dysfunctional
+gene. As long as no entry in the local database has any missing values,
+the >> Missing Values tab is not
+displayed. When adding a new entry with NA value(s) to the
+local database, containing no missing values so far, reloading the
+database will automatically have the
+>> Missing Values tab render, to
+call attention on the newly occurring missing values. This tab provides
+statistical information about the occurrence of missing values, and most
+importantly: control buttons for the user, to select the strategy how
+missing values are treated for subsequent analyses. The selection how
+these values should be handled directly impacts the calculation of the
+allelic distances between the bacterial isolates. The options to choose
+from are detailed in 3.4.1 Missing
+Value Handling. Due to the importance of missing values and how they
+are treated, upon loading local databases containing at least one
+missing value, the >> Missing Values
+tab will always be rendered first.
+Figure 14 shows statistics about the missing values +of the entries in this database. There are 1069 unsuccessful allele +allocations in total, i.e. the global sum of NA values of all +entries and loci. There are 2983 loci in total in the selected +Bordetella pertussis scheme and 217 of these have one or more +missing values, which makes up about 7.3 %. Isolates for which more than +5% of loci contain missing values are highlighted in orange. These +should be included in further analyses with caution because a +significant share of alleles couldn’t be determined.
+Each row in the table on the right shows an entry that contains at
+least one missing value. The next column, Errors,
+respectively includes the sum of missing values for that isolate. The
+following columns are loci including at least one missing value (denoted
+by NA).
5 AMR Screening
+Screening for species-specific genes of interest, e.g. antibiotics
+resistance, virulence or stress genes, can be performed using the
+integrated NCBI/AMRFinder
+tool. The tab > Resistance Profile
+provides the interface for this feature and lets users inspect the
+screening results in
+>> Browse Entries and perform the
+screening from the tab >> Screrning.
+Note, that not every species is available for screening with AMRFinder.
+The availability for the currently selected scheme is automatically
+checked.
5.1 Perform Screening
+Use the tab >> Screening to run
+AMRFinder. Selecting one or multiple isolates and clicking
+Start initiates the process. The runtime is estimated less
+than a minute per isolate. Only isolates for which the respective
+assembly file is present in the local database can be applied to gene
+screening. The results can be inspected in parallel using the selector
+on the right, appearing once at least one isolate finalized the
+screening. Feedback on unsuccessful typing attempts is displayed as
+well.
+5.2 Resistance Profile
+There are two viewing modes available to browse the resistance
+profile, resulting from gene screening. Selecting the view mode
+☑ Picker | ☐ Table renders the option to select isolates
+from a simple selector. The table showing the resistance profile
+(including also virulence genes, stress genes, etc.) for the selected
+isolate will appear below . The view mode
+☐ Picker | ☑ Table, shows the isolate entry table above the
+resistance profile instead of the selector and therefore, next to
+providing a good overview, enables filtering and sorting. Select an
+entry from the table to render the respective resistance profile for
+this isolate. The currently selected table can be exported as CSV with
+Profile Table.
+6 Visualization
+Based on the allelic distances in the distance matrix (see 4.4 Distance Matrix), different tree plots
+can be created. PhyloTrace allows to choose between three different tree
+construction algorithms, Minimum-Spanning,
+Neighbour-Joining and UPGMA. This tree type
+can be selected in the sidebar of the
+> Visualization tab (see Figure
+17). On click of the Create Tree button, a tree
+plot of the currently selected tree type will be computed and displayed.
+You can switch to a different tree type and create another tree without
+losing the tree created before. If you switch back to the previous tree
+type, you will still have the previously created tree. Unless you create
+a new tree for the same tree type, the plot will be conserved in the
+current session. Switching between different tree types enables to
+seamlessly compare trees created with the same data set, but different
+tree construction algorithms. Changes for the entry table in the
+>> Browse Entries tab, such as
+inclusion of additional isolates (via ticking Include) or
+edited variables, will only take effect in the tree plot, if you save
+the database with the changes and click Create Tree again.
+Once a tree has been created, it can be modified and customized without
+having to reload it again.
+6.1 Minimum-Spanning-Tree
+The minimum-spanning-tree (MST) algorithm constructs a tree by +connecting the closest points or nodes of the distance matrix without +forming cycles. It focuses on finding the shortest path to connect all +the nodes, resulting in a tree that minimizes the total edge length. +Refer to 6.1.1 MST Modification to find +out, how the tree appearance can be modified. The nodes represent single +bacterial isolates. Isolates with identical allelic profile, i.e. a +distance value of 0, are summarized in a single node. If the allelic +distance between isolates lies within a certain threshold, clusters are +drawn.
+6.1.1 MST Modification
+Figure 18 shows the modification panels for MST
+plots. These are divided into Layout (see 6.1.1.1 Layout), Nodes (see 6.1.1.2 Nodes) and Edges (see 6.1.1.3 Edges). There are several options to customize
+MST graphs, e.g. colors, forms, sizes, titles, labels, and more. Note,
+that due to the nature of the generation of MST plots, the plot is reset
+to its initial position, when changing one of the modification
+parameters. MST graphs can be enriched with information by mapping
+variables. to the plot.
+6.1.1.1 Layout
+The Layout control panel allows to add title, subtitle and
+footer to the graph by typing them in the text fields. Individually
+change the color for them using the color button below the text fields.
+Also the overall background color can be modified. Toggle the
+Transparent switch, to make the background transparent.
6.1.1.2 Nodes
+The Nodes control panel allows to control the appearance of +the nodes and related elements such as the label. The upper left +controls are related to the label, i.e. which isolates are represented +by the respective node. Using the drop-down menu, the label can be +changed to any variable present for the respective isolates according to +the entry table. The color of the node labels can be modified using the +color button and their sizes by clicking on the blue menu button right +next to it. The color of the nodes themselves can be changed using the +color button from the control panels on the upper right. Clicking the +menu buttons allows to change the opacity.
+Node colors can also be used to map a variable to the graph. Nodes +are colored according to the value present for the respective isolates +and transformed in a pie chart to show the distribution of values if +there are several clonal isolates summarized in a single node. Currently +only variables of categorical type can be used in this feature.
+The node size can be controlled from the bottom left controls. The
+size of nodes containing multiple isolates with identical allelic
+profiles, can be scaled by the number of isolates contained in them.
+Toggle the Scale by Duplicates switch to activate this
+feature. Consequently, the slider to set the node size changes to a
+range selection instead of distinct values. In this way, the size of the
+smallest nodes, i.e. containing just one isolate, the size of the nodes
+containing most isolates as well as the overall range can be
+controlled.
The form of the nodes can be customized using the control panels on
+the bottom right. Activate the switch Show Shadows to
+display shadows for the nodes. The shape of the nodes can be changed
+here as well. Choose between shapes that render the node labels below
+(Diamond, Hexagon, Dot,
+Square) or inside them (Circle,
+Box, Text). If a variable is mapped, the form
+Pie Chart is locked in and can not be changed.
6.1.1.3 Edges
+The Edges control panel allows to control the appearance of the edges
+and related elements. Each edge is labelled by the value of the allelic
+distance that the isolates from connecting nodes have to each other.
+Except its appearace, this label currently can’t be changed. The color
+and size can be modified using the upper left controls Label.
+The color of the edges themselves can be controlled by Color in
+the upper right controls. Click the menu button to see the control for
+the transparency of the edges. On the bottom left, there is the option
+to scale the edge lengths by the allelic distance they represent. Toggle
+the Scale Edge Length switch to activate this effect. The
+multiplier of this effect can be customized using the slider below.
+Activating this option when the subset of isolates displayed in the MST
+graph has very different allelic distances, e.g. for a maximum of 200
+and a minimum of 10, can lead to an untidy look of the plot. Drag the
+slider to lower values to minimize this issue.
6.1.1.4 Clustering
+The clustering controls are to be found in the Edges panel at the +bottom right. By default the “Complex Type Distance” value disclosed for +each scheme available on the cgMLST.org Nomenclature Server is selected +as the current cluster threshold. The threshold value can be modified to +any desired value. Nodes with distances that lie withing the selected +threshold are accordingly engulfed by cluster shapes. These are +differently colored in order to distinguish between the cluster groups. +Choose between the Rainbow and Viridis scales to +modify the coloring. There are two types of cluster shapes available: +Area and Skeleton. The cluster type Area +renders an area surrounding nodes that are part of a cluster. Skeleton +instead uses the edges to visualize clusters. This can be particularly +useful if the selection of isolates is complex, which can potentially +lead to overlapping clusters with the Area cluster type.
+6.2 Neighbour-Joining-Tree
+The Neighbour-Joining (NJ) method constructs a tree by iteratively +joining pairs of nodes based on their pairwise distances. It aims to +minimize the total branch length in the tree and is commonly used for +constructing phylogenetic trees from distance matrices. Refer to 6.4 NJ and UPGMA Modification for +information on how the tree appearance can be modified.
+6.3 UPGMA-Tree
+The Unweighted Pair Group Method with Arithmetic Mean (UPGMA) +computes tree plots by grouping the most similar sequences or taxa +together at each step and then averaging their distances. It produces a +tree with equal branch lengths and is often used for hierarchical +clustering of data. Refer to 6.4 NJ +and UPGMA Modification for information on how the tree appearance +can be modified.
+6.4 NJ and UPGMA Modification
+The tree elements can be customized in great detail and supplemented
+with additional information such as variables (see 6.4.4 Variable Mapping). However the basic
+appearance, e.g. text and element sizes, are automatically adjusted to
+the qualities and quantities of the entries that were selected to be
+included for the tree. Due to the variable nature of different data
+sets, it is sometimes required to manually readjust some elements to
+receive a balanced look. While Minimum-Spanning trees have slightly
+different modification features and control inputs, NJ and UPGMA trees
+share the same control inputs. This is due to the different
+visualization technique used for the creation and display of MST plots.
+The controls to modify the tree are arranged in panels and divided in
+Layout, Label, Elements and
+Variables. In some panels you will find small menu buttons
+(highlighted in light blue). They allow to further modify the elements
+addressed by the respective panel in more detail (e.g. position or
+font-style).
6.4.1 Layout
+The appearance of the general layout can be modified in detail. There
+is a range of different options, e.g. for controlling theme, colors,
+title & subtitle, size, legend and other elements. To switch to
+these controls navigate to the
+>> Visualization tab and click the
+Layout button from the menu left to the control panels.
+
+6.4.1.1 Theme
+Layout themes allow to change the geometrical appearance. You can +choose from a selection of themes that are further categorized in linear +and circular layouts. While the visual look changes when switching +between linear and circular theme, the quality, i.e. the order and +arrangement, of the hierarchical NJ and UPGMA trees, stays the same.
+Linear: Rectangular,
+Roundrect, Slanted and
+Ellipse
Circular: Circular,
+Inward
Moreover, a Rootedge can be added by turning on the
+switch. The root of the tree can be considered as starting point,
+representing a theoretical “common ancestor” with an initial allelic
+profile, from which all other isolates developed. Next to aesthetics,
+displaying this element can help to distinguish “normal” branches,
+representing actual allelic distance between the isolates, from the
+root. The root menu lets you further modify it’s length and line
+type.
The Ladderize switch is turned on by default. It sorts
+the tree branches by their length.
+6.4.1.2 Color
+The color of lines, text as well as background, can be modified in
+the Color panel. The colored buttons show the color currently
+displayed as well as the respective HEXA code. Clicking them opens the
+color menu. You can either select a color by choosing it directly from
+the gradient field or by providing a HEXA or RGBA code. Note, that the
+Lines/Text color applies to the tree branches, legend text and
+title, but not to the tip labels. Their color can be modified in the
+respective Label menu (see 6.4.2.1
+Tips).
+6.4.1.3 Title
+Add title and subtitle in the Title panel. Their color +changes in accordance to the selected Lines/Text color, but can be +separately modified. The title menu allows to customize the font +size.
+6.4.1.4 Sizing
+The Sizing panel provides control of plot dimensions and
+position. For the aspect ratio, you can choose from 16:10,
+16:9 and 4:3. The overall size can be scaled
+with the slider below. If some elements are cut off you can zoom out
+using the slider at the bottom. Especially trees having a circular
+layout can sometimes appear small with too much white space around. In
+this case zooming in might be beneficial. The Sizing menu
+allows to horizontally and vertically position the content.
6.4.1.5 Tree Scale
+Legend and tree scale controls share the same panel. The tree scale +helps to estimate the actual allelic distance, represented by the branch +length. In case you prefer not to show this element you can hide it by +toggling the switch. It’s length can be changed in the tree scale menu +and proportionally scales with the branch length. If the scale +superimposes other elements, adjust its position by dragging the sliders +in the menu.
+6.4.1.6 Legend
+If variables are mapped to the plot, a legend will appear. For the
+orientation, the options are either horizontal or vertical (see
+Figure 22). The legend menu allows to also adjust
+position and size.
+6.4.2 Label
+The Label menu allows to control whether and how certain
+labels are displayed. There are three different kinds of labels:
+Tips, Branches and Custom Labels. They can be
+modified in many different ways, e.g. in color, size or position.
+
+6.4.2.1 Tips
+The label at the tips represent the actual entries with their allelic
+profile that determined their position in the tree. By default, the
+Assembly Name is displayed as tip label. However it is
+possible to select other basic variables, e.g. Host,
+Country, City or Isolation Date,
+from the drop down menu, or even choose not to show tip labels at all by
+toggling the Show switch. Instead of the tip labels being positioned
+right next to the tips, they can be aligned to the right by activating
+the Align switch. UPGMA trees always have the tip labels
+aligned and NJ trees only have this activated by default for circular
+layouts. The menu on the right provides further customization options.
+The Opacity slider can be used to change the transparency.
+The Position parameter modifies the offset of the labels
+from the tip. Angle, size and font face can be changed as well.
+Customize the color of the label text with the color button and the
+color of the panel with the color button below. The panels envelope the
+tip label and are not shown by default. The controls in the panel menu
+allow to modify size of the panels (not the text itself) and to smooth
+the form.
+6.4.2.2 Branches
+Branch labels allow to supplement the tree with additional
+information by labelling the branch leading to the final tips with
+variables that are connected to the respective isolate. To show this
+element toggle the Show switch in the Branches
+panel. The drop down lets you choose which variable or meta data to
+annotate. The color of the panel surrounding the branch label can be
+changed with the color button below. The menu button includes further
+controls, e.g. opacity, size, horizontal and vertical position, font
+face as well as edge smoothing. Note, that having branch labels doesn’t
+work for trees with circular layout. Also more complex linear trees with
+many isolates included mostly have too confined space for adding branch
+labels. Instead, consider mapping a variable to other tree elements such
+as tip points (see 6.4.4 Variable
+Mapping).
+6.4.2.3 Custom Label
+If there is a need for labels somewhere other than tips or branches,
+there is the option to create customized ones. The panel
+Custom Labels lets you define the label. Click the green
++ button too add it. The label will be positioned at plot
+center. Create more labels by giving them a name and adding them again.
+To change the size and position, select the respective label from the
+drop down and open the menu next to the + button. Do the
+desired changes and click the Apply button for them to come
+into effect. Figure 25 shows a tree with two
+highlighted clades (see 6.4.3.5 Clade
+Highlight). The custom label function was used to annotate them.
+
+6.4.3 Elements
+The Elements menu provides control over several special
+elements such as tip and node points or a heatmap. These are not
+essential but can amplify the explanatory power of the tree. Elements
+can be deactivated or activated and their appearance can be changed.
+
+6.4.3.1 Tip Points
+Tip points are located at the end of the tree branches and correspond
+to the isolates displayed. They can be modified in color or size to
+bring the ends of the tree into prominence. Alternatively this element
+can be used to map a variable (see 6.4.4
+Variable Mapping).
+6.4.3.2 Node Points
+Node points, in contrast to tip points, solely represent theoretical +predecessors and relatives with respect to the isolates and their +allelic profile. Despite the option to map a variable, their look can be +customized in the same way like tip points. Mapping variables is not +possible because they connect several isolates which may potentially +have discrepant values for a chosen variable.
+6.4.3.3 Tiles
+Tiles are supplementary elements that can be used to map variables to
+the plot. They work with both circular and linear layouts. Up to five
+different tiles can be added by activating them in the
+Variables menu (see 6.4.4
+Variable Mapping). To modify opacity, width or position, select the
+respective tiles that you wish to change with the selector at the top
+left corner of the panel. Any modifications will apply only for the
+selected tile. Opacity defines the transparency of the tile, enabling
+overlaying it e.g. over the tree. The width slider controls the width.
+Changing the position of the tiles for linear layouts, they are moved
+horizontally, while in circular layouts they are moved inwards or
+outwards in relation to the center of the circle.
+6.4.3.4 Heatmap
+Heatmaps can be a powerful tool to visualize related variables of the
+same type (either categorical or continuous). For more details refer to
+6.4.4 Variable Mapping. If the heatmap
+is activated in the Variables menu it can be modified using
+the respective control panel in the Elements menu. Width
+changes apply to the heatmap overall, not to single columns. Just as
+with tiles, the position control is moving the heatmap horizontally for
+linear layouts and inwards or outwards for circular layouts. In some
+situations, e.g. for long variable names or in circular layouts, it
+might make sense to modify the angle and/or position of the column
+headers. This can be done by using the controls in the heatmap menu.
+
+6.4.3.5 Clade Highlight
+Isolates are grouped in distinct hierarchical clades, which are
+defined by nodes that comprise several isolates or other daughter nodes
+and their respective isolates. In order to emphasize one or several
+clades toggle the Node View switch and inspect the respective node index
+of the clades you wish to highlight. Select the nodes in the drop-down
+menu below and deactivate the Node View again to see the highlighted
+clades. If only one clade is highlighted there is the option to
+customize its color with the color button below. If there is more than
+one clade selected, you choose from a color scale instead. Also use the
+menu in the Clade Highlight control panel to control the
+alignment of the clade highlights to each other. The borders of the
+colored squares can be modified to round or rectangular appearance.
+
+Clades, which are located within another clade that is higher in the
+hierarchy can also be highlighted (see Figure 31).
+
+6.4.4 Variable Mapping
+Mapping variables, representing epidemiologic metadata or other
+properties of the isolates displayed, is a powerful way of enriching the
+plot with information. The Variables menu provides full
+control which variables are mapped, the elements they are mapped to and
+the color scale that represents the different values of the selected
+variable. The control panel is ordered into Element, Variable and Color
+Scale columns (see Figure 32). The switches in the
+Element column can be turned on or off to activate or deactivate the
+display of a variable with the respective element. Select the variable
+to be mapped from the drop-down menu right of the element switch. It
+contains the basic meta data (Isolation Date,
+Host, City, Country) as well as
+the manually added custom variables (see 4.1.2 Custom Variables). The currently
+selected variable is checked for its number of distinct values and
+variable type (categorical or continuous). As this information is
+relevant for selecting the color scale, it is displayed directly next to
+the color scale selection menus. For categorical variables, the
+selectable color scales automatically change depending on the number of
+distinct values. If the number of distinct values is 7 or less you can
+select from qualitative color scales. As there is a limited number of
+distinct colors available in the qualitative color scales, they are not
+selectable if the variable exceeds 7 distinct values. Instead, gradient
+color scales can be selected from. Continuous variables have continuous
+and divergent color scales available. Using the colorblind friendly
+gradients Viridis and Cividis is recommended.
+Divergent color scales are useful for visualizing data where there’s a
+clear central point of interest to highlight positive and negative
+deviations from a central value like 0. An example for a use case are
+gene expression variables. E.g. fold change values, with colors
+indicating whether the change is positive (upregulation) or negative
+(downregulation) relative to a baseline expression level of 0 (no
+change).
+In Figure 33 the Isolation Date
+variable is mapped to the tip label color (see 6.4.2.1
+Tips). Hence the tip labels indicate both the
+Assembly Name and the Isolation Date, with the
+Greys color scale highlighting more recently added isolates in
+darker shades. The tip point color is assigned to display the
+categorical City variable in which the sample was acquired.
+In this example with two values only, the cities Graz and
+Vienna. The qualitative scale Set2 is chosen to
+distinguish the variable as well as possible from other variables. The
+tip point shapes circle and triangle represent the host from which the
+bacterial sample was taken. As the variable values are represented by
+shapes instead of colors, there is no color scale for this option.
+Continuous values can’t be represented by shapes. There are six
+different shapes available, hence selecting the tip point shape to
+represent categorical variables is only possible if there are 6 or less
+distinct values. The custom variables Patient Age and
+ftsA, which stands for expression values of the
+ftsA gene, are mapped to Tile 1 and 2 respectively. Except
+color values which are assign by the variable mapping, the appearance of
+the elements, such as tip point sizes, can still be modified (e.g. 6.4.3.1 Tip Points).
+Figure 35 shows an example for gene expression fold
+changes mapped on a heatmap. While white/yellow colors indicates
+baseline expression levels around 0, green colors indicate upregulation
+and red colors downregulation. When a diverging scale is selected, you
+can choose the midpoint of the scale (Zero,
+Mean or Median) using the drop down menu that
+appears right to the color scale selector. Zero assigns the
+middle color of the diverging color scale to the value 0. The choices
+Mean and Median assign the middle color to the
+arithmetic mean and median of the respective value range. The appearance
+of the heatmap, such as width and position, can be modified using the
+respective control panel from the Elements menu (see 6.4.3.4 Heatmap).
+7 Reporting Results
+7.1 Download Plots
+Neighbour-Joining and UPGMA trees can be downloaded in PNG, JPEG, BMP
+and SVG format. Minimum-Spanning trees can be downloaded in PNG, JPEG
+and BMP format. In addition they can be downloaded as HTML to preserve
+the interactivity of dragging, zooming and moving the MST graph. To
+initiate the download head to the
+> Visualization tab. In the sidebar,
+below the Create Tree button, you find the drop down to
+select the file type as well as the download button right next to it.
+Note: In order for the download to work, the plots have to be created
+first.
7.2 Generating Report Document
+A report of HTML format can be created by clicking the button
+Print Report, located in the sidebar of the
+> Visualization tab. There are several
+options to control which information is included in the report. The
+elements are categorized in Entry Table,
+General , Analysis and
+Attach Plot (see 7.2.1 Report
+Elements). Note that the report requires prior creation of a tree
+plot. The entry table in the report, the attached plot as well as some
+analysis parameter, such as the tree algorithm, are all settled in the
+moment a tree is created. Therefore a proper report can only be
+generated after tree creation. For the entry table, instead of the
+entire local database for the respective scheme, only isolates of
+interest, i.e. the ones that have been used to generate the currently
+displayed tree are listed in the report. The download will be directed
+to the system location set in your browser download settings.
+
+7.2.1 Report Elements
+The sub-elements belonging to General are
+Date, Operator, Institute and
+Comment. If you wish to include only a selection of these
+elements, tick or untick them accordingly. Unticking the
+General element will deactivate the display of any
+sub-elements as well.
+Ticking the Isolate Table prints the entry table,
+comprising the isolate names as well as the selected metadata columns on
+the report. Note, that only entries that are marked as
+Included in the database
+(>> Browse Entries) are printed.
+Hence only isolates that are shown in the current tree are included.
The sub-elements belonging to the Analysis parameters
+are Scheme, Tree, Distance,
+NA Handling and Version. These parameters are
+automatically derived from the session as well as the created tree and
+can only be selected to be shown or hidden. As with the
+General parameters, unticking
+Analysis Parameter will hide all sub-elements.
+