feat: set_ranks function

NAMESPACE

@@ -6,6 +6,7 @@ export(jellyfisherOutput)
 export(renderJellyfisher)
 export(select_patients)
 export(set_parents)
+export(set_ranks)
 import(dplyr)
 import(htmlwidgets)
 import(stringr)

R/utils.R

@@ -95,6 +95,50 @@ set_parents <- function(tables, parents, unset_missing = FALSE) {
   )
 }
 
+#' Set ranks for samples
+#'
+#' Given a list of jellyfish input tables and a named list of ranks for each
+#' sample, set the rank for each sample.
+#'
+#' @param tables A list of tables (samples, phylogeny, compositions)
+#' @param ranks A named list of ranks for each sample
+#' @param default The default rank to use when a sample is not in the rank list
+#'   (default: 1)
+#'
+#' @return A list of tables with ranks set for each sample
+#'
+#' @examples
+#' jellyfisher_example_tables |>
+#'   select_patients("EOC809") |>
+#'   set_ranks(list("EOC809_r1Bow1_DNA1" = 1, "EOC809_p2Per1_cO_DNA2" = 2)) |>
+#'   jellyfisher()
+#'
+#' @export
+#'
+set_ranks <- function(tables, ranks, default = 1) {
+  validate_tables(tables)
+
+  samples <- tables$samples
+
+  # Check that all samples in the rank list are in the samples table
+  stopifnot(all(names(ranks) %in% samples$sample))
+
+  for (i in seq_len(nrow(samples))) {
+    rank <- ranks[[samples$sample[[i]]]]
+    if (!is.null(rank)) {
+      samples$rank[[i]] <- rank
+    } else {
+      samples$rank[[i]] <- default
+    }
+  }
+
+  list(
+    samples = samples,
+    phylogeny = tables$phylogeny,
+    compositions = tables$compositions
+  )
+}
+
 #' Shiny bindings for jellyfisher
 #'
 #' Output and render functions for using jellyfisher within Shiny

README.md

@@ -1,16 +1,16 @@
-# <img src="man/figures/logo.webp" alt="Jellyfisher hexagon" align="right" height="138" style="margin-left: 0.5em" /> Jellyfisher: Visualizing Tumor Evolution with Jellyfish Plots in R
+# <img src="man/figures/logo.webp" alt="Jellyfisher hexagon" align="right" height="138" style="margin-left: 0.5em" /> Jellyfisher
 
 **Jellyfisher** is an R package for visualizing tumor evolution and subclonal
-compositions using Jellyfish plots. The package is based on the
+compositions using Jellyfish plots, which display both spatial and temporal
+dimensions in a single unified figure.
+
+The package is based on the
 [Jellyfish](https://github.com/HautaniemiLab/jellyfish) visualization tool,
 bringing its functionality to R users. Jellyfisher supports both
 [ClonEvol](https://github.com/hdng/clonevol) results and plain data frames,
 making it compatible with various tools and workflows.
 
-![Jellyfisher Example](https://raw.githubusercontent.com/HautaniemiLab/jellyfish/refs/heads/main/docs/example.svg)
-
-The package is still under development and the API may change in the future.
-Stay tuned!
+![Jellyfisher Example Plot](https://raw.githubusercontent.com/HautaniemiLab/jellyfish/refs/heads/main/docs/example.svg)
 
 ## Installation
 
@@ -29,9 +29,9 @@ 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 [Jellyfish
-documentation](https://github.com/HautaniemiLab/jellyfish?tab=readme-ov-file#input-data),
-vignette, and the `jellyfisher` function's documentation.
+subclonal _compositions_, which are described in the
+[`jellyfisher`](https://hautaniemilab.github.io/jellyfisher/reference/jellyfisher.html)
+function's documentation.
 
 #### Example
 

vignettes/introduction.Rmd

@@ -126,7 +126,7 @@ jellyfisher_example_tables |>
   jellyfisher(width = "100%", height = 500)
 ```
 
-### Adjusting the sample tree structures
+## Adjusting the sample tree structures
 
 The sample trees in the example data set were constructed as follows:
 
@@ -136,7 +136,7 @@ assigned as the parent; otherwise, the inferred root was used as the parent."*
 
 However, this mechanistic approach may not always produce credible sample trees.
 
-#### Changing parent
+### Changing parent
 
 The *r1Bow1* (bowel) sample in the following jellyfish plot is derived
 from an earlier bowel sample *p2Bow1_c*, which has no traces of the subclone 12.
@@ -159,7 +159,7 @@ jellyfisher_example_tables |>
   jellyfisher(width = "100%", height = 600)
 ```
 
-#### Changing topology
+### Changing topology
 
 While ranks (the columns) can indicate the time points when the samples were
 acquired, they can also be used to simply show the sample's depth in the sample
@@ -181,8 +181,8 @@ let Jellyfisher assign the ranks based on the sample tree depth.
 tables <- jellyfisher_example_tables |>
   select_patients("EOC495")
 
-# Remove existing ranks. The rank will be assigned automatically based
-# on samples depth in the sample tree.
+# Remove existing ranks. The ranks will be assigned automatically based
+# on samples' depths in the sample tree.
 tables$samples$rank <- NA
 
 tables |>
@@ -191,6 +191,21 @@ tables |>
   jellyfisher(width = "100%", height = 500)
 ```
 
+If we think that the lymph node samples represent even later development,
+we can manually assign ranks to the samples. The `set_ranks` function provides
+an easy way to do this.
+
+```{r}
+tables |>
+  set_parents(list("EOC495_pLNL1_DNA1" = "EOC495_pLNR_DNA1",
+                   "EOC495_pLNL2_DNA1" = "EOC495_pLNL1_DNA1")) |>
+  set_ranks(list("EOC495_pLNR_DNA1" = 2,
+                 "EOC495_pLNL1_DNA1" = 3,
+                 "EOC495_pLNL2_DNA1" = 4),
+            default = 1) |>
+  jellyfisher(width = "100%", height = 400)
+```
+
 ```{r echo=F}
 rm(tables)
 ```