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:
samplesA 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
samplecolumn 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
rankcolumn 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)
phylogenyA 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)
compositionsA 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)
ranksAn 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
Examples
# Plot the bundled example data
jellyfisher(jellyfisher_example_tables,
options = list(
sampleHeight = 70,
sampleTakenGuide = "none",
showLegend = FALSE
))