Contents

1 Introduction

Clonal evolution describes the development of a tumor over time, considering the principle of ‘survival of the fittest’ on a cellular level. The development of cellular heterogeneity is of special interest with respect to cancer as it can be associated with therapy response, prognosis and survival of a patient. For example, relapse may be caused by an aggressive subclone.

The study of clonal evolution is based on mutations detected in a tumor sample. Ideally, data on mutations being present or absent is available for more than one time point in the cause of a patient’s disease. In a first analysis step, mutations have to be clustered to define clones. Every clone is commonly characterized by the cancer cell fraction (CCF) for every time point. The clones can, subsequently, be arranged as phylogenetic trees to represent the tumor’s evolution. A final, but essential step in the analysis of clonal evolution, significantly contributing to interpretation of the results, is its visualization.

clevRvis provides an extensive set of visualization techniques for clonal evolution. Three types of plots are available: 1) shark plots (basic trees, showing the phylogeny and optionally the cancer cell fraction CCF); 2) dolphin plots (advanced visualization, showing the phylogeny and the development of CCFs over time); 3) plaice plots (novel visualization, showing the phylogeny, the development of CCFs and the development of remaining healthy alleles, influenced by bi-allelic events, over time). Moreover, the tool provides algorithms for fully automatic interpolation of time points and estimation of therapy effect to approximate a tumor’s development in the presence of few measured time points, as well as exploring alternative trees.

clevRvis provides all common features for visualization also available in established R-packages like ‘timescape’. These features have been revised from scratch and optimized (e.g. supporting branched independent evolution, supporting visualization of a single clone, extensive validity check of the input, switch between bottom- and centered-layout). Furthermore, a wide set of additional features is available (e.g. automatic phylogeny-aware color-coding, algorithms for time point interpolation and therapy effect estimation, graphical user interface).

1.1 Requirements

To run clevRvis, you need R (Version 4.1.0 or higher).

1.2 Installation

To install clevRvis, type the following commands in R:

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("clevRvis")

1.3 Running clevRvis

After installation, the package can be loaded into R by typing

library(clevRvis)
## 
## Attaching package: 'clevRvis'
## The following object is masked from 'package:base':
## 
##     col

clevRvis is available as a shiny GUI. You can run the shiny version either by RStudio executing the function clevRvisShiny(). Additionally, all functions for classical use in R are available:

  1. createSeaObject(): Create a seaObject

  2. sharkPlot(): Generate a basic graph visualization of clonal evolution

  3. extSharkplot(): Generate an extended graph visualization of clonal evolution

  4. dolphinPlot(): Generate a detailed visualization of clonal evolution

  5. combinedPlot(): Generate a combined basic graph and detailed visualization of clonal evolution

  6. plaicePlot(): Generate an allele-aware visualization of clonal evolution

  7. exploreTrees(): Generate alternative parental relations to explore alternative trees

2 Examplary use of clevRvis

2.1 createSeaObject()

clevRvis needs a seaObject for the visualization of clonal evolution by means of any available plot. When generating the seaObject extra time points may be interpolated and/or therapy effect estimated.

2.1.1 Usage

createSeaObject(fracTable,parents,timepoints,col=NULL,cloneLabels=NULL,
                originTimepoint=NULL,timepointInterpolation=TRUE,
                therapyEffect=NULL)
  • fracTable A numeric matrix containing tumor fraction estimates for all clones at all time points.
  • parents An integer vector specifying parental relationships between clones.
  • timepoints A numeric vector specifying the time points for each column of the matrix.
  • col (optional) A vector of colors to use when plotting each clone.
  • cloneLabels (optional) A character vector of names to assign to each clone when plotting a legend.
  • originTimepoint (optional) Time point when the first clone emerges (must be before the first measured time point).
  • timepointInterpolation When set to true extra time points will be interpolated between measured time points and before the first measure timepoint to improve the visualization (default: TRUE).
  • therapyEffect (optional) A single numeric value indicating the time point when to estimate the effect of therapy or a numeric vector containing two consecutive measured time points, therapy effect timepoint will be in the middle.

2.1.2 Details

The basis for all plotting functions included in clevRvis is a seaObject. It contains information on the CCFs for all clones, at all measured time points. Additionally, parental information on the clones is included.

Additional time points may be interpolated, therapy effect estimated when generating seaObjects.

Time point interpolation is generally recommended to improve visualization of clonal evolution. 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 needed and the time point of origin must be manually specified, as there is no way of calculating it.

To visualize the effect of therapy on the clones’ CCFs in case of missing measured data, a fully automatic approach for therapy effect estimation is available. 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.

A seaObject with all relevant slots filled is returned.

2.1.2.1 Time point interpolation

For an improved visualization of clonal evolution, enabling time point interpolation is recommended.

2.1.2.2 Therapy effect estimation

When generating the seaObject, the effect of therapy can also be estimated. There’s two options to define the therapy effect time point:

  • The therapyEffect is defined as a single numeric value in between measured time points -> the therapy effect will be estimated at the given time point

  • The therapyEffect is defined as a vector containing two measured time points -> the therapy effect will be estimated at the midpoint between them

2.1.3 Examples

##Example data
timepoints <- c(0,50,100)
parents <- c(0,1,1,3,0,5,6)
fracTable <- matrix(c(20,10,0,0,0,0,0,
                    40,20,15,0,30,10,0,
                    50,25,15,10,40,20,15),
                    ncol = length(timepoints))
seaObject <- createSeaObject(fracTable, parents, timepoints,
                            timepointInterpolation = FALSE)
##seaObject with enabled time point estimation
seaObject_tp <- createSeaObject(fracTable, parents, timepoints,
                                timepointInterpolation = TRUE)
##seaObject with enabled time point estimation and therapy effect 
##estimation between time point 50 and 100
seaObject_te <- createSeaObject(fracTable, parents, timepoints,
                            timepointInterpolation = TRUE,
                            therapyEffect = c(50,100))
##seaObject with manually defined colors
seaObject_col <- createSeaObject(fracTable, parents, timepoints,
                                timepointInterpolation = TRUE,
                                col = rainbow(7))

2.2 sharkPlot()

A shark plot shows the basic graph visualization of clonal evolution with nodes representing clones and edges indicating their evolutionary relations.

2.2.1 Usage

sharkPlot(seaObject, showLegend, main)
  • seaObject A seaObject.
  • showLegend A boolean indicating whether to show the legend or not (default: FALSE).
  • main A string corresponding to the plot’’s main title.

2.2.2 Details

A 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 plots also offer 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 points next to the basic shark plot (see extSharkPlot).

2.2.3 Examples

#Basic shark plot showing legend and title
sharkPlot(seaObject_tp, showLegend = TRUE, main = 'Example Shark plot')

#Basic shark plot showing legend and title with manually defined color coding
sharkPlot(seaObject_col, showLegend = TRUE, main = 'Example Shark plot')

2.3 extSharkPlot()

An extended shark plot shows the basic graph visualization of clonal evolution with nodes representing clones and edges indicating their evolutionary relations and additional visualization of CCFs.

2.3.1 Usage

extSharkPlot(seaObject, showLegend, main, timepoints, width, interactivePlot)
  • seaObject A seaObject.
  • showLegend A boolean indicating whether to show the legend or not (default: FALSE).
  • main A string corresponding to the plot’s main title (default: NULL).
  • timepoints By default, all time points available in the seaObject are visualized. Optionally, a selected set of available time points can be chosen.
  • width An integer value indicating the width of the widget plot (default: 10).
  • interactivePlot A boolean defining whether the plot should be interactive (default: TRUE; if using this function to export the extended shark plot, e.g. by png(), define interactivePlot = FALSE).

2.3.2 Details

An extended shark plots consists of two elements:

  1. A basic shark plot: common trees, with nodes representing clones and edges indicating their evolutionary relation. Phylogeny can be directly deduced from these plots.

  2. Additionally, CCFs of each clone (rows) at each time point (columns) are shown as points next to the basic shark plot. The size of each point correlates with the CCF at the corresponding clone and time point.

Both plots are linked in an interactive widget.

2.3.3 Examples

##extended shark plot, showing CCF as point size only for measured 
###time points, legend and title
extSharkPlot(seaObject_tp, timepoints = timepoints, showLegend = TRUE, 
            main = 'Example Extended Shark plot')