Title:	Visualize Spatiotemporal Tumor Evolution with Jellyfish Plots
Version:	1.0.4
Description:	Generates interactive Jellyfish plots to visualize spatiotemporal tumor evolution by integrating sample and phylogenetic trees into a unified plot. This approach provides an intuitive way to analyze tumor heterogeneity and evolution over time and across anatomical locations. The Jellyfish plot visualization design was first introduced by Lahtinen, Lavikka, et al. (2023, <doi:10.1016/j.ccell.2023.04.017>). This package also supports visualizing ClonEvol results, a tool developed by Dang, et al. (2017, <doi:10.1093/annonc/mdx517>), for analyzing clonal evolution from multi-sample sequencing data. The 'clonevol' package is not available on CRAN but can be installed from its GitHub repository (https://github.com/hdng/clonevol).
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
LazyData:	true
URL:	https://github.com/HautaniemiLab/jellyfisher, https://hautaniemilab.github.io/jellyfisher/
BugReports:	https://github.com/HautaniemiLab/jellyfisher/issues
Imports:	htmlwidgets, dplyr, stringr
Suggests:	knitr, rmarkdown, clonevol
Depends:	R (≥ 4.1.0)
VignetteBuilder:	knitr
biocViews:	Visualization, Phylogenetics, Software, Spatial
NeedsCompilation:	no
Packaged:	2025-02-05 12:40:36 UTC; klavikka
Author:	Kari Lavikka [cph, aut, cre]
Maintainer:	Kari Lavikka <kari.lavikka@helsinki.fi>
Repository:	CRAN
Date/Publication:	2025-02-06 19:30:02 UTC

Extract Data for Jellyfisher from ClonEvol Results

Description

ClonEvol infers clonal evolution from multi-sample cancer sequencing data and generates phylogenetic models of tumor evolution. This function extracts data frames from a ClonEvol object that can be used to create a Jellyfish plot.

Usage

extract_tables_from_clonevol(y, model = 1)

Arguments

Details

Note: ClonEvol reports clonal prevalences as confidence intervals. This function extracts the mean values and uses them as the prevalence values.

For more details about ClonEvol, including the installation instructions, visit its GitHub repository or read the publication by Dang et al. (2017, doi:10.1093/annonc/mdx517).

Value

A named list with three data frames: samples, phylogeny, and compositions

Examples

if (requireNamespace("clonevol", quietly = TRUE)) {
  # Run ClonEvol with its example data
  # (refer to ClonEvol documentation for details)
  data <- clonevol::aml1
  y <- clonevol::infer.clonal.models(
    variants = data$variants,
    cluster.col.name = "cluster",
    vaf.col.names = data$params$vaf.col.names,
    subclonal.test = "bootstrap",
    subclonal.test.model = "non-parametric",
    num.boots = 1000,
    founding.cluster = 1,
    cluster.center = "mean",
    ignore.clusters = NULL,
    min.cluster.vaf = 0.01,
    sum.p = 0.05,
    alpha = 0.05
  )
  # Make branch lengths available
  y <- clonevol::convert.consensus.tree.clone.to.branch(y)

  # Extract data and plot the results
  extract_tables_from_clonevol(y, model = 1) |>
    jellyfisher()
} else {
  message(
    "Please install the clonevol package from GitHub: devtools::install_github('hdng/clonevol')"
  )
}

Creates a Jellyfish plot

Description

Creates a Jellyfish plot from samples, a phylogeny, and subclonal compositions.

Usage

jellyfisher(
  tables,
  options = list(),
  controls = "closed",
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

Details

The format of the data frames is described with examples in Jellyfish documentation: https://github.com/HautaniemiLab/jellyfish?tab=readme-ov-file#input-data

Value

A Jellyfish plot HTML widget

Examples

# Plot the bundled example data
jellyfisher(jellyfisher_example_tables,
            options = list(
              sampleHeight = 70,
              sampleTakenGuide = "none",
              showLegend = FALSE
            ))

Shiny bindings for jellyfisher

Description

Output and render functions for using jellyfisher within Shiny applications and interactive Rmd documents.

Usage

jellyfisherOutput(outputId, width = "100%", height = "400px")

renderJellyfisher(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

jellyfisherOutput()

A shiny.tag object that can be included in a Shiny UI definition.

renderJellyfisher()

A shiny.render.function that returns an htmlwidget object for use in a Shiny server function.

Jellyfisher example data

Description

Example data based on the following publication: Lahtinen A, Lavikka K, Virtanen A, et al. Evolutionary states and trajectories characterized by distinct pathways stratify patients with ovarian high grade serous carcinoma. Cancer Cell. 2023;41(6):1103-1117.e12. doi:10.1016/j.ccell.2023.04.017

Format

jellyfisher_example_tables

A named list of data frames containing the following tables:

samples

A data frame with sample data. Columns are:

sample

specifies the unique identifier for each sample. (string)

displayName

allows for specifying a custom name for each sample. If the column is omitted, the sample column is used as the display name. (string, optional)

rank

specifies the position of each sample in the Jellyfish plot. For example, different stages of a disease can be ranked in chronological order: diagnosis (1), interval (2), and relapse (3). The zeroth rank is reserved for the root of the sample tree. Ranks can be any integer, and unused ranks are automatically excluded from the plot. If the rank column is (integer)

parent

identifies the parent sample for each entry. Samples without a specified parent are treated as children of an imaginary root sample. (string)

phylogeny

A data frame with phylogeny data. Columns are:

subclone

specifies subclone IDs, which can be any string. (string)

parent

designates the parent subclone. The subclone without a parent is considered the root of the phylogeny. (string)

color

specifies the color for the subclone. If the column is omitted, colors will be generated automatically. (string, optional)

branchLength

specifies the length of the branch leading to the subclone. The length may be based on, for example, the number of unique mutations in the subclone. The branch length is shown in the Jellyfish plot's legend as a bar chart. It is also used when generating a phylogeny-aware color scheme. (number)

compositions

A data frame with subclonal compositions. Columns are:

sample

specifies the sample ID. (string)

subclone

specifies the subclone ID. (string)

clonalPrevalence

specifies the clonal prevalence of the subclone in the sample. The clonal prevalence is the proportion of the subclone in the sample. The clonal prevalences in a sample must sum to 1. (number)

ranks

An optional data frame with ranks. Columns are:

rank

specifies the rank number. The zeroth rank is reserved for the inferred root of the sample tree. However, you are free to define a title for it. (integer)

title

specifies the title for the rank. (string)

Source

https://github.com/HautaniemiLab/jellyfish/tree/main/data

Filter Jellyfish tables by patient

Description

Given a list of tables, filter them by patient.

Usage

select_patients(tables, patient)

Arguments

Value

A list of tables filtered by patient

Examples

jellyfisher_example_tables |>
  select_patients("EOC809")

Set parents for samples

Description

Given a list of jellyfish input tables and a named list of parents for each sample, set the parent for each sample.

Usage

set_parents(tables, parents, unset_missing = FALSE)

Arguments

Details

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

Value

A list of tables with parents set for each sample

Examples

jellyfisher_example_tables |>
  select_patients("EOC809") |>
  set_parents(list("EOC809_r1Bow1_DNA1" = "EOC809_p2Per1_cO_DNA2")) |>
  jellyfisher()

Set ranks for samples

Description

Given a list of jellyfish input tables and a named list of ranks for each sample, set the rank for each sample.

Usage

set_ranks(tables, ranks, default = 1)

Arguments

Value

A list of tables with ranks set for each sample

Examples

jellyfisher_example_tables |>
  select_patients("EOC809") |>
  set_ranks(list("EOC809_r1Bow1_DNA1" = 2, "EOC809_p2Per1_cO_DNA2" = 2),
    default = 1
  ) |>
  jellyfisher()

Validate Jellyfish tables

Description

Superficially validate that the tables are in the correct format.

Usage

validate_tables(tables)

Arguments