# clevRvis

An Interactive App for the visualization of Clonal Evolution

Section 1 | Introduction to clevRvis
- What is clevRvis?
- What can clevRvis do?

1. Alternative trees exploration
2. Automatic time points interpolation
3. Therapy effect estimation
4. Shark plot
5. Dolphin plot
6. Plaice plot

Section 2 | Tutorial: Visualization of the clonal evolution with a real example

1. Necessary Inputs
2. Generating the seaObject
3. Visualizing the clonal evolution

- Shark and Dolphin plots
- Plaice plot
- Annotations

## Section 1 |Introduction to clevRvis

### What is clevRvis?

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.

### What can clevRvis do?

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.

#### Alternative trees exploration

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:

- Possible parents are determined. If clone 1 has at any measured time point a lower CCF compared to clone 2, then clone 1 cannot be clone 2's parent.
- Possible branched dependent evolution is investigated. If clone 2 can only develope from clone 1, the difference in CCFs for clone 1 and clone 2 is calculated. Every remaining clone with a CCF larger than the difference cannot develop from clone 1.
- All remaining, possible parental relations are determined. An extensive validity check is performed using clevRvis (validity check when creating a seaObject). A maximum of 20,000 parental relations is investigated.

#### Automatic time points interpolation

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.

- When having less time points than clones, or many new clones emerging in one single measured time point, the extra time point interpolation is strongly recommended to visualize the clonal evolution properly.

- If there is only one measured time point, time point interpolation is <bold>needed</bold> and the time point of origin must be <bold>manually specified</bold>, as there is no way of calculating it.

#### Therapy effect estimation

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

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

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 plot

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.

<bold>How does the clone coloring work?</bold>

- An uncolored clone indicates that at least one copy of a healthy allele is present for all genes.
- A colored clone indicates that a bi-allelic event took place. As a consequence, no healthy allele of the gene(s) affected by the bi-allelic event remains.

1. If clone 1 carries a point mutation in TP53 and clone 2 carries an additional del17p (affecting the remaining healthy allele), clone 2 in the lower plaice should be colored in the same hue as clone 1 in the upper plaice, which is originally charaterized by mutation in TP53, indicating that the double-hit event affected TP53.
2. If clone 1 carries a deletion of 17p and clone 2 carries an additional point mutation in TP53 (affecting the remaining healthy allele), clone 2 in the lower plaice should be colored in the same hue as clone 2 in the upper plaice, which is originally charaterized by mutation in TP53, indicating that the double-hit event affected TP53.
3. If clone 2 carries two point mutations in TP53 affecting different alleles, clone 2 in the lower plaice should be colored in the same hue as clone 2 in the upper plaice, indicating that the double-hit event affected TP53.
4. If clone 2 carries a variant affecting the X chromosome of a male subject, leading to a loss of the only available healthy allele, clone 2 in the lower plaice should be colored in the same hue as clone 2 in the upper plaice, indicating he hemizygous variant affecting a gene on the X chromosome.

## Section 2 |Tutorial: Visualization of the clonal evolution with an example

### 1. Necessary inputs

- Cancer Cell Fractions (CCFs) input table:

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.

- Time points:

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).

- Clone Labels:

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).

- Parental relations:

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).

- Explore alternative trees:

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.

#### Example:

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.

### 2. Generating the seaObject

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.

- Extra time point interpolation:

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.

- Therapy effect estimation:

Two options are available to estimate the effect of therapy:

1. User-defined specific time point. The specific time point must be between two measured time points and will stay the same even if extra time points are estimated.
2. Between two measured time points. The therapy time point will be defined as the middle time point between the two selected time points but if there is also extra time points interpolation the therapy time point will be recalculated to ensure equidistant development of the clones.

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.

### 3. Visualizing the clonal evolution

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.

#### Shark and Dolphin plots

The shark and dolphin plots can be visualized inside the “Outputs -> Plots -> Shark & Dolphin plots” tab.

- Shark plot:

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:

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

- Dolphin plot:

When Show Dolphin plot is selected, dolphin plot visualization options will appear below.

1. Show legend will plot the color legend on the left side of the dolphin plot.
2. Separate independent clones will leave a blank space between different families of clones emerging from normal cells.
3. A main title can be written in the input Main text box, and it will be automatically updated after any change.
4. For layout center visualization shows the clonal evolution starting from the middle and expanding to both sides of the y axis. Bottom visualization shows the clonal evolution “laying” on the x axis, only expanding to the top.
5. For Dolphin plot shape, spline shape is smoother and allows the user to define a pad left (how much to extend the start of the development of each clone). Polygon shape is edgy and uses only the x positions of the time points in the seaObject.
6. Axis labels shows a line on the y axis indicating the 100% of CCF. Also allows the user to define manual labels for the x and y axis.
7. Clones border color defines de color of the clones border from a wide palette of colors, including transparency properties.
8. Vertical lines x position allows the user to select where to plot vertical lines, by default only measured time points is selected, but estimated time points and custom positions are also an option. To define custom positions the user must define the x values where to plot the vertical lines separated by commas (e.g 10,13,14)
9. Vertical lines color defines the color of the vertical lines from a wide palette of colors.
10. Vertical lines labels allow the user to select which labels to plot on top of the vertical lines. Vertical lines without labels can be plotted, but it is not allowed to give labels to just some lines. To plot the labels there must be as many as vertical lines. Same way as with the custom vertical lines, custom vertical lines labels must be defined with comma separated values (e.g day10,day13,day14)
11. Size of vertical lines labels allows the user to change the vertical lines labels size from a range of numbers.
12. Show symbol underneath works the same way as vertical lines x position. It allows the user to select which positions to show a filled triangle underneath the dolphin plot. This option is mostly used to mark which of all the time points are the measured ones.

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.

- Shark+dolphin plots:

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 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:

- Axis labels automatically shows the y axis labels and there is no option for custom labels.
- Mark biallelic events is added: when switched on, a dropdown list for each clone will appear. For each clone the user must select which color to use to fill in the bottom half of the plot.

1. To not paint the clone, select “Empty”. A not colored clone means there is at least one copy of a healthy allele.
2. To paint the clone with another clone’s color, select the label of the clone which color to use. A clone (e.g Clone 2) colored with the color of another clone (e.g Clone 1) means a new variant (in Clone 2) is causing a biallelic event on the same gene that was affected by the clone which color you are using (Clone 1).
3. To paint a clone with its own color, select the same clone’s label. A clone colored with its own color means it implies on itself a biallelic event, or that it affects the only available X- or Y- chromosome in male subjects.

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

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.