Visualizing Tumor Evolution with Jellyfish Plots in R • jellyfisher

Jellyfisher is an R package for visualizing tumor evolution and subclonal compositions using Jellyfish plots, which display both spatial and temporal dimensions in a single unified figure.

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.

Jellyfisher Example Plot

Installation

# Install Devtools
install.packages("devtools")

# Install Jellyfisher
devtools::install_github("HautaniemiLab/jellyfisher", build_vignettes = TRUE)

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 jellyfisher function’s documentation.

Example

library(jellyfisher)

# Plot the bundled example data
jellyfisher(jellyfisher_example_tables)

Plotting ClonEvol Results

Jellyfisher provides a straightforward way to visualize ClonEvol results using the extract_tables_from_clonevol function. 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.

Example

library(clonevol)
library(jellyfisher)

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

# Plot the results
extract_tables_from_clonevol(y, model = 1)) |>
  jellyfisher()

Setting Parent-Child Relationships of Samples

By default, all samples that have no explicit parent are children of the inferred root sample. You can customize the parent-child relationships by modifying the parent column in the samples data frame before plotting.

You can also modify the relationships using the set_parents function.

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:

tables |>
  set_parents(list(
    # The parent of C is B
    C = "B"
  ) |>
  jellyfisher()

    Root
   /  \
  A    B
        \
         C

Contributing

Jellyfisher is a thin wrapper for the Jellyfish visualization tool. Jellyfish is included as a git submodule in the tools/jellyfish/ directory.

To build the Jellyfish JavaScript dependency, run the update-and-build.sh script in the tools/ directory. Most of the R code is autogenerated from the Jellyfish JavaScript code using the generate-R-code.mjs script, which should be run after building the Jellyfish dependency.

About

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