Jellyfisher: Visualizing Tumor Evolution with Jellyfish Plots in R

Jellyfisher is an R package for visualizing tumor evolution and subclonal compositions using Jellyfish plots. The package is based on the Jellyfish visualization tool, bringing its functionality to R users. Jellyfisher supports both ClonEvol results and plain data frames, making it compatible with various tools and workflows.

The package is still under development and the API may change in the future. Stay tuned!

Installation

# Install Devtools
install.packages("devtools")

# Install Jellyfisher
devtools::install_github("HautaniemiLab/jellyfisher")

Usage

Jellyfisher is designed to work with data frames or ClonEvol results.

Plotting Data Frames

The input data should follow specific structures for samples, phylogeny, and subclonal compositions, which are described in the Jellyfish documentation.

Example

library(jellyfisher)

# Plot the bundled example data
jellyfisher(samples = samples.example,
            phylogeny = phylogeny.example,
            compositions = compositions.example)

Plotting ClonEvol Results

Jellyfisher provides a straightforward way to visualize ClonEvol results using the jellyfisher_clonevol function. The function takes the ClonEvol results as input and generates a Jellyfish plot.

Example

library(clonevol)
library(jellyfisher)

# Run ClonEvol. Check the ClonEvol documentation for details.
y <- infer.clonal.models(...)

# Plot the results
jellyfisher_clonevol(y, model = 1, explicit_parents = list())

Extracting Data Frames from ClonEvol Results

If you need to process ClonEvol output further or plot it in different ways, Jellyfisher includes a helper function to extract the relevant data frames:

extract_tables_from_clonevol(y, model = 1, explicit_parents = list())

The function returns a list of data frames that you can pass to the jellyfisher function. N.B., ClonEvol reports clonal prevalences as confidence intervals. The function extracts the mean values and uses them as the prevalence values.

Setting Parent-Child Relationships of Samples

By default, all samples that have no explicit parent are children of the inferred root sample. To define custom parent-child relationships, you can pass a list of explicit relationships to the explicit_parents argument.

For example, if you have three samples, A, B, and C, they will have the following relationships by default:

    Root
   / | \
  A  B  C

With the explicit parents, you can customize the relationships:

explicit_parents = list(
  # The parent of C is B
  C = "B"
)

    Root
   /  \
  A    B
        \
         C

You can alternatively define the relationships by mutating the samples data frame generated by extract_tables_from_clonevol before plotting.

About

Copyright (c) 2024 Kari Lavikka. MIT license, see LICENSE for details.

Jellyfish Plotter is developed in The Systems Biology of Drug Resistance in Cancer group at the University of Helsinki.

This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 965193 (DECIDER) and No. 847912 (RESCUER).