feat: rank titles

R/data.R

@@ -32,6 +32,13 @@
 #'   \item{subclone}{specifies the subclone ID. (string)}
 #'   \item{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)}
 #'   }
-#' }}
+#' }
+#'     \item{\code{ranks}}{An optional data frame with ranks. Columns are:
+#'   \describe{
+#'   \item{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)}
+#'   \item{title}{specifies the title for the rank. (string)}
+#'   }
+#' }
+#' }
 #' @source <https://github.com/HautaniemiLab/jellyfish/tree/main/data>
 "jellyfisher_example_tables"

R/jellyfisher.R

@@ -34,6 +34,12 @@
 #'   \item{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)}
 #'   }
 #'     }
+#'     \item{\code{ranks}}{An optional data frame with ranks. The expected columns are:
+#'   \describe{
+#'   \item{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)}
+#'   \item{title}{specifies the title for the rank. (string)}
+#'   }
+#'     }
 #'   }
 #' @param options A named list of options to configure the plot. Available options:
 #'   \describe{
@@ -56,6 +62,7 @@
 #'   \item{phylogenyColorScheme}{Whether to use a color scheme based on phylogeny Defaults to \code{TRUE}.}
 #'   \item{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 \code{0}.}
 #'   \item{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. Defaults to \code{"text"}.}
+#'   \item{showRankTitles}{Whether to show rank titles above the samples (if provided). Defaults to \code{TRUE}.}
 #'   \item{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 \code{FALSE}.}
 #'   }
 #' @param controls An optional parameter to set the initial state of the controls. Can be "open", "closed", or "hidden".
@@ -105,6 +112,7 @@ jellyfisher <- function(tables,
     phylogenyColorScheme = TRUE,
     phylogenyHueOffset = 0,
     sampleTakenGuide = "text",
+    showRankTitles = TRUE,
     normalsAtPhylogenyRoot = FALSE
   )
 
@@ -192,6 +200,9 @@ jellyfisher <- function(tables,
   if (!is.null(options$sampleTakenGuide)) {
     if (!options$sampleTakenGuide %in% c("none", "line", "text")) stop("sampleTakenGuide must be one of: none, line, text")
   }
+  if (!is.null(options$showRankTitles)) {
+    if (!is.logical(options$showRankTitles)) stop("showRankTitles must be a boolean (TRUE or FALSE)")
+  }
   if (!is.null(options$normalsAtPhylogenyRoot)) {
     if (!is.logical(options$normalsAtPhylogenyRoot)) stop("normalsAtPhylogenyRoot must be a boolean (TRUE or FALSE)")
   }

R/utils.R

@@ -19,7 +19,8 @@ select_patients <- function(tables, patient) {
   list(
     samples = tables$samples[tables$samples$patient %in% patient, ],
     phylogeny = tables$phylogeny[tables$phylogeny$patient %in% patient, ],
-    compositions = tables$compositions[tables$compositions$patient %in% patient, ]
+    compositions = tables$compositions[tables$compositions$patient %in% patient, ],
+    ranks = tables$ranks
   )
 }
 
@@ -40,6 +41,10 @@ validate_tables <- function(tables) {
     is.data.frame(tables$compositions)
   )
 
+  if (!is.null(tables$ranks)) {
+    stopifnot(is.data.frame(tables$ranks))
+  }
+
   stopifnot(
     all(c("sample") %in% colnames(tables$samples)),
     all(c("subclone", "parent") %in% colnames(tables$phylogeny)),
@@ -90,7 +95,8 @@ set_parents <- function(tables, parents, unset_missing = FALSE) {
   list(
     samples = samples,
     phylogeny = tables$phylogeny,
-    compositions = tables$compositions
+    compositions = tables$compositions,
+    ranks = tables$ranks
   )
 }
 
@@ -138,7 +144,8 @@ set_ranks <- function(tables, ranks, default = 1) {
   list(
     samples = samples,
     phylogeny = tables$phylogeny,
-    compositions = tables$compositions
+    compositions = tables$compositions,
+    ranks = tables$ranks
   )
 }
 

inst/htmlwidgets/jellyfisher.js

@@ -15,7 +15,9 @@ HTMLWidgets.widget({
             samples: HTMLWidgets.dataframeToD3(x.tables.samples),
             phylogeny: HTMLWidgets.dataframeToD3(x.tables.phylogeny),
             compositions: HTMLWidgets.dataframeToD3(x.tables.compositions),
-            ranks: [], // TODO
+            ranks: x.tables.ranks
+              ? HTMLWidgets.dataframeToD3(x.tables.ranks)
+              : null,
           },
           x.options,
           null,

tools/generate-R-code.mjs

@@ -133,6 +133,9 @@ ${buildParamDoc("phylogeny.tsv")}
 #'     \\item{\\code{compositions}}{A data frame with subclonal compositions. The expected columns are:
 ${buildParamDoc("compositions.tsv")}
 #'     }
+#'     \\item{\\code{ranks}}{An optional data frame with ranks. The expected columns are:
+${buildParamDoc("ranks.tsv")}
+#'     }
 #'   }
 #' @param options A named list of options to configure the plot. Available options:
 #'   \\describe{

vignettes/introduction.Rmd

@@ -28,8 +28,8 @@ making it compatible with various tools and workflows.
 
 ## Input data
 
-The input data should follow specific structures for _samples_, _phylogeny_, and
-subclonal _compositions_.
+The input data should follow specific structures for _samples_, _phylogeny_, 
+subclonal _compositions_, and optional _ranks_.
 
 The Jellyfisher package includes an example data set based on the following
 publication:
@@ -86,6 +86,18 @@ represents a subclone in a sample.
 head(jellyfisher_example_tables$compositions, 25)
 ```
 
+### Ranks
+
+The ranks in the example data set are used to indicate the time points when the
+samples were acquired. 
+
+- `rank` (integer): 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.
+- `title` (string): specifies the title for the rank.
+
+```{r}
+head(jellyfisher_example_tables$compositions, 6)
+```
+
 ## Plotting
 
 ### Basic plotting 
@@ -185,6 +197,9 @@ tables <- jellyfisher_example_tables |>
 # on samples' depths in the sample tree.
 tables$samples$rank <- NA
 
+# Rank titles should be removed as well because they are no longer valid.
+tables$ranks <- NULL
+
 tables |>
   set_parents(list("EOC495_pLNL1_DNA1" = "EOC495_pLNR_DNA1",
                    "EOC495_pLNL2_DNA1" = "EOC495_pLNL1_DNA1")) |>