An Interactive App for the visualization of Clonal Evolution
clevRvis is a tool for interactive clonal evolution visualization. The graphical user interface eases the use for scientists, physicians and biologists without knowledge in bioinformatics or computer science.
clevRvis can generate three different types of plots: 1) shark plots (basic tree representation of clonal evolution), 2) dolphin plots (a more detailed fish plot-like representation) and 3) plaice plots (which allow the easy visualizaiton on biallelic events).
Moreover, the plots generated contain a phylogeny-aware color coding of the clones for an optimal visualization.
To create a seaObject, the basis for all plotting functions in clevRvis, a fracTable, a timepoints vector and a parents vector are required. clevRvis provides an approach to determine all valid parental relations on the basis of the information provided in fracTable and the timepoints vector. Thereby, alternative trees can be explored.
To optimize run-time, the analysis is devided into 3 step procedure:
A central challenge in studying clonal evolution is the difficulty of collecting multiple samples along time from cancer patients, for this reason we implemented an automatic interpolation for extra time points. This automatic time point interpolation allows for a visualization with an equidistant development of clones using as few as one measured time point.
The extra time points interpolation can be activated when creating the seaObject. The time point of origin (time point where the first clone emerges) can be manually specified although, by default, it is assumed to be the difference in time between the first and second measured time point. (e.g if time point 1 is day 0 and time point 2 is day 30 the origin time point will be day -30).
When to use time point interpolation?
time point interpolation will always help to visualize an equidistant development of the clones. Nevertheless, when there are many measured time points it might not be necessary.
time point interpolation doesn't show a decrease the tumor load at any point, as it is expected in the absence of therapy. To visualize the effect of therapy on the clones' Cancer Cell Fractions (CCFs), extra time points interpolation is not enough.
In clevRvis, we implemented an updated, fully automatic approach for therapy effect estimation. When creating the seaObject a specific time point can be defined (between two measured time points) or two measured time points can be selected (new therapy effect time point will be in the middle) for the estimation of the therapy effect.
Shark plot is the basic approach for visualization: common trees, with nodes representing clones and edges indicating their evolutionary relation. Phylogeny can be directly deduced from these plots.
Shark plot also offers an extension to visualize the changes in CCF along time for each clone. CCFs of each clone (rows) at each time point (columns) are shown as point size next to the basic shark plot.
Dolphin plot displays detailed information on clonal evolution, showing the development of all clones over time (x-axis) and their clonal prevalence (y-axis). Information on phylogeny, CCFs and time course characterizing a clonal evolution are jointly visualized in this single plot.
Several basic options for customizing dolphin plots are available, e.g. switching between spline and polygon shape, bottom or central visualization, annotations, separating independent clones, adding vertical lines and labels, changing border and vertical lines colors, etc.
If dolphin plots are chosen to be plotted along with basic shark plots, both plots are internally connected. By hovering on one of the clones, it is automatically highlighted in both, shark and dolphin plot. Nevertheless, shark plots with the extension and solphin plots can NOT be visualized together.
Plaice plots are based on the bottom visualization of dolphin plots ("flatfish" = plaice), mirrored above and below the x-axis. They have been developed to improve the visualization of biallelic events. Plaice plots provide an allele-aware visualization of clonal evolution. Plots show the development of all clones over time (x axis) and their clonal prevalences (y axis), and the ratio of remaining healthy alleles (lower plaice).
Clonal evolution can be visualized in the upper half of the plaice plot. Several options similar to the ones for dolphin plot are available as well for plaice plot: switching between spline and polygon shape, annotations, separating independent clones (recommended), adding vertical lines and labels, etc.
On the bottom half of the plot, a (by default) not colored mirrored representation of clonal evolution is plotted. The user may choose which clones and with which clones' color to paint in order to show which clones caused biallelic events.
The file must be an Excel or CSV containing a table with the CCFs of each clone at each time point. Each row in the table must correspond to a clone and each column to a time point. Optionally, time point values can be set on the first row, clone labels on the first column and parental relations can be specified in a column called "parents". Using the switches in the app the user must specify what does the input table contain.
If the first row of the input table corresponds to the time points it should be indicated in the input tab. Otherwise, automatic time points (going from 1 to number of columns in the file) can be used. time points can also be defined manually by writing the time points values in the text box separated by commas (e.g 0,30,100).
If Clone Labels are written in the first column of the input table it should be indicated. Otherwise, automatic clone labels (Clone 1, Clone 2 … ) can be used. Clone labels can also be manually defined by writing them separated by commas in the text box (e.g A,B,C).
If the input table contains a column called "parents", defining the parental relations, it should be indicated by selecting Column "parents" included In the case that the input table does not contain the parental relations, the user must select Define parental relations interactively. Once the input table has been correctly uploaded and the Clone Labels defined, a selector for each clone will appear. The parent of each clone should be selected from the options in the dropdown list. Once all clones have a parent selected, the submit button must be clicked to run a validation and to define the parental relations.
To define the time points, clone labels and parental relations from the app the input file must not contain them (must only contain CCFs).
In the inputs tab we find a switch to explore alternative trees. When switched on, a dropdown list will appear with the possible vectors for defining the parental relations. When "Explore alternative trees" is activated, the parental relations selected in the dropdown will be the ones used to generate the seaObject afterwards. Any other parental relations defined before (in the input table or interactively through the app) will be ignored.
The Input file contains a table with seven columns and six rows. The first row corresponds to the time points (0,2,5,8,12), the first column corresponds to the clone labels (Clone A, Clone B, Clone C, Clone D, Clone E) and the last column corresponds to the parental relations vector (0,1,2,3,2) therefore the file contains the CCFs of five clones on five time points. The evolution of the clones is branched as(Clone C and Clone E) share the same parent (Clone B).
After clicking submit inputs, the validation will run. Once the validation has run, a pop-up message will appear confirming the parental relations have been successfully defined or showing a message with the error that has been found. If there is any error it must be fixed, and the validation must run again before going to the next step.
The seaObject is an R object containing all the necessary information for the visualization of clonal evolution. When creating the seaObject, extra time points or therapy effect can be estimated if desired. Both time point interpolation and therapy effect estimation will be shown in the further plots.
The interpolation of extra time points is highly recommended and absolutely needed if the input data contains only one time point. Switching the time point interpolation on will show the option for manually defining a custom time point of origin. This custom time point of origin must be lower than the first measured time point and to define it the numeric input must be used.
Two options are available to estimate the effect of therapy:
After all the desired options have been selected, the submit button must be clicked to run another validation. If there are no errors, a success message will show up and the seaObject table will be shown in the outputs section.
There are two options for visualizing the clone's CCFs. The default option is the CCF_clone, meaning it includes the fraction specific of the clone plus the children's CCFs. The second option is the CCF_clone - sum(CCF_children), which substracts the children's CCF to the clone's CCF, therefore we see the fraction of cells corresponding only to that clone specifically.
Extra time points interpolation is selected for a better visualization and the origin time point is calculated by default. Therapy was applied between the second and thrid time point, therefore therapy effect estimation is selected, and the option of estimation is between two measured time points (selecting the second and third one). The seaObject table shows the CCFs of each clone at each time point (estimated and measured) and on the last column the parental relations.
On the left menu, inside the Plots item, we find three options for visualization: shark, dolphin and plaice plots. All plots can be downloaded as .png using the button on the top right corner of the plot.
The shark and dolphin plots can be visualized inside the “Outputs -> Plots -> Shark & Dolphin plots” tab.
When Show Shark plot is selected, shark plot visualization options will appear. Show legend plots the color legend on the right side of the shark plot. A main title can be written in the input Main text box, and it will be automatically updated after any change.
Show legend is selected and “Shark Plot Example data” was written in the Main text box.
Extended shark plot shows the CCF of each clone at each time point as point size. When it is selected, the basic shark plot and the extended part are linked, when hovering on a clone in the basic shark plot it will show the clone name and the clone's row on the extended side will be highlighted. When hovering over a point on the extended side, the CCF value will be shown, and the corresponding clone will be highlighted in both sides of the plot.
Show legend was selected, “Extended Shark Plot Example Data” was written in the Main text box Extended shark plot is selected and the Shown time points are both, measured and estimated
When Show Dolphin plot is selected, dolphin plot visualization options will appear below.
To generate this plot show legend is activated. “Dolphin Plot Example Data” was written in the Main text box. Layout position is “center” and dolphin plot shape is “spline”. The axis labels switch is activated, “Cancer cell fractions (CCFs)” was written in the y axis label text box and “time points” was written in the x axis label text box. Clone’s border and vertical lines colors are the default ones. Vertical lines and labels selected are only measured time points, and finally, for show symbol underneath only estimated time points is selected.
To plot shark and dolphin plots together both have to be activated and extended shark plot must be deactivated. Options and annotations of each plot work the same way as if they were plotted individually, except for show legend as if it is selected either in shark or dolphin plot options it will be plotted on the right side of the shark plot.
Plaice plots can be visualized inside the “Outputs -> Plots -> Plaice plot” tab. When Show Plaice plot is selected in the left menu, plaice plot visualization options will appear below. The visualization options are the same as for Dolphin plot except for two:
To generate this plot show legend is activated. “Plaice Plot Example Data” was written in the Main text box. The shape is “spline” and the axis labels switch is activated. Vertical lines and labels selected are measured time points and for show symbol underneath also only estimated time points is selected. Annotations were written as described in the following section. And finally, to show that the deletion on the chromosome 17 (in Clone C) affected the remaining healthy copy of TP53 (one copy was affected by a mutation in Clone A), Clone C, and its children (Clone D) are painted with Clone A color in the bottom half of the plot. To do this, “Clone A” was selected from the dropdown list of Clone C in the Mark biallelic events input.
Annotations for each clone can be added on the dolphin and plaice plots. On the left menu, inside the annotations tab, if the Add annotations switch is turned on, a tab for each clone will appear. Inside each tab there is a text box where to write the clone’s annotation, a switch to select black or white color of the text and two sliders to select the x and y position interactively. The plot will be automatically updated after any change.
Using the same options as before for the plaice plot, by turning on the switch for annotations we can add text to the plot in order to add important comments about the clones. In this case TP53 and del17 were added to the corresponding clones where the variants took place.