User Manual
PhyloTrace Version 1.5.0
Web: www.phylotrace.com
Contact: info@phylotrace.com
Github: https://github.com/liora-bioinformatics/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.