jellyfisher: Creates a Jellyfish plot

In jellyfisher: Visualize Spatiotemporal Tumor Evolution with Jellyfish Plots

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

tables	A named list of data frames. The list must contain the following elements: samples A data frame with sample data. The expected 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. The expected 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. The expected 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. The expected 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)
options	A named list of options to configure the plot. Available options: crossingWeight Weight for tentacle bundles between two pairs of samples crossing each other. Defaults to 10. pathLengthWeight Weight for the total length of the paths (tentacle bundles) connecting samples. Defaults to 2. orderMismatchWeight Weight for the mismatch in the order of samples. The order is based on the "phylogenetic center of mass" computed from the subclonal compositions. Defaults to 2. bundleMismatchWeight Weight for the mismatch in the placement of bundles. The "optimal" placement is based on the subclonal compositions, but such placement may produce excessively long tentacle bundles. Defaults to 3. divergenceWeight Weight for the sum of divergences between adjacent samples. Defaults to 4. bellTipShape The shape of the bell tip. 0 is a sharp tip, 1 is a blunt tip. Defaults to 0.1. bellTipSpread How much to spread nested bell tips. 0 is no spread, 1 is full spread. Defaults to 0.5. bellStrokeWidth The width of strokes in the bell. Defaults to 1. bellStrokeDarkening How much the stroke color of the bells is darkened. Defaults to 0.6. bellPlateauPos Where the bell has fully appeared and the plateau starts. Defaults to 0.75. sampleHeight Height of real sample nodes Defaults to 110. sampleWidth Width of sample nodes Defaults to 90. inferredSampleHeight Height of inferred sample nodes Defaults to 120. gapHeight Height of gaps between samples. Gaps are routes for tentacle bundles. Defaults to 60. sampleSpacing Vertical space between samples Defaults to 60. columnSpacing Horizontal space between columns Defaults to 90. tentacleWidth Width of tentacles in pixels Defaults to 2. tentacleSpacing Space between tentacles in a bundle, in pixels Defaults to 5. inOutCPDistance Relative distance of tentacle control points from the edge of the sample node Defaults to 0.3. bundleCPDistance Relative distance of tentacle bundle's control points. The higher the value, the longer the individual tentacles stay together before diverging. Defaults to 0.6. sampleFontSize Font size for sample labels Defaults to 12. showLegend Whether to show the legend Defaults to TRUE. phylogenyColorScheme Whether to use a color scheme based on phylogeny Defaults to TRUE. phylogenyHueOffset Offset for the hue of the phylogeny color scheme. If the automatically generated hues are not to your liking, you can adjust the hue offset to get a different color scheme. Defaults to 0. sampleTakenGuide Type of the "sample taken" guide. "none" for no guides, "line" for a faint dashed line in all samples, "text" same as line, but with a text label in one of the samples. "text-all" same as text, but with a text label in all samples. Defaults to "text". showRankTitles Whether to show rank titles above the samples (if provided). Defaults to TRUE. normalsAtPhylogenyRoot Whether the root of the phylogenetic tree contains normal cells. If true, no tentacles will be drawn for the root clone and its color will be white if phylogenyColorScheme is used. Defaults to FALSE.
controls	An optional parameter to set the initial state of the controls. Can be "open", "closed", or "hidden".
width	The width of the widget
height	The height of the widget
elementId	An optional element ID for the widget

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

jellyfisher documentation built on April 4, 2025, 1:41 a.m.