Plotting direction

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: CancerEvolutionVisualization
 Title: Publication Quality Phylogenetic Tree Plots
 Version: 3.0.0
-Date: 2025-03-12
+Date: 2025-04-09
 Authors@R: c(
 	person("Paul Boutros", role = "cre", email = "PBoutros@mednet.ucla.edu"),
 	person("Adriana Salcedo", role = "aut"),

NEWS.md

@@ -1,4 +1,4 @@
-# CancerEvolutionVisualization 3.0.0 (2025-03-12)
+# CancerEvolutionVisualization 3.0.0 (2025-04-09)
 
 ## Added
 * Dendrogram mode
@@ -12,6 +12,7 @@
 * Add option to use scale bars instead of y-axes.
 * Wrapper function for `SRCgrob` to automatically save plots to file
 * Add option to annotate the CCF summary heatmap with the cell values.
+* `plotting.direction` argument to `SRCGrob` to support arbitrary direction of tree "flow". Can be one of 'down' (default), 'right', 'up', 'left' or any number (in degrees).
 * Function to generate single-sample density plot
 * Add support for 1xn and 1x1 heatmaps.
 * Add `get.colours.in.order` function to get a list of colours and corresponding clone ID order.

R/SRCGrob.R

@@ -2,6 +2,7 @@ SRCGrob <- function(
     tree,
     node.text = NULL,
     main = NULL,
+    plotting.direction = 'down',
     horizontal.padding = 0.1,
     scale1 = 1,
     scale2 = 1,
@@ -33,6 +34,12 @@ SRCGrob <- function(
     scale.size.2 = NA,
     scale.padding = 1
     ) {
+    if ('CP' %in% colnames(tree) && !(plotting.direction %in% c('down', 0))) {
+        warning(paste(
+            '"plotting.direction" is not yet supported with "CP" polygon column.',
+            '"plotting.direction" will be ignored.'
+            ));
+        }
 
     add.node.text <- !is.null(node.text);
     add.polygons <- !is.null(tree$CP) && !disable.polygons;
@@ -58,6 +65,10 @@ SRCGrob <- function(
         default.node.colour = node.col
         );
 
+    start.angle <- prep.plotting.direction(
+        plotting.direction,
+        radians = use.radians
+        );
     fixed.angle <- pi / 6;
     min.width <- get.plot.width(horizontal.padding);
     spread <- 1;
@@ -95,6 +106,7 @@ SRCGrob <- function(
         default.branch.width = 4,
         add.polygons = add.polygons,
         spread = spread,
+        start.angle = start.angle,
         fixed.angle = fixed.angle,
         add.node.text = add.node.text,
         text.on.nodes = text.on.nodes,

R/angles.R

@@ -1,4 +1,10 @@
-calculate.angles.radial <- function(v, tree, spread, total.angle) {
+calculate.angles.radial <- function(
+    v,
+    tree,
+    spread,
+    total.angle,
+    start.angle
+    ) {
     root.node.id <- v$id[[1]];
     node.ids <- c(root.node.id);
 
@@ -13,7 +19,7 @@ calculate.angles.radial <- function(v, tree, spread, total.angle) {
         parent.id <- tree$parent[tree$tip == current.node.id];
 
         if (parent.id == -1) {
-            tree$angle[tree$tip == current.node.id] <- 0;
+            tree$angle[tree$tip == current.node.id] <- start.angle;
             }
 
         child.ids <- as.numeric(
@@ -24,7 +30,7 @@ calculate.angles.radial <- function(v, tree, spread, total.angle) {
         if (num.children > 0) {
             parent.angle <- angles[tree$tip == current.node.id];
             if (is.na(parent.angle) || length(parent.angle) == 0) {
-                parent.angle <- 0;
+                parent.angle <- start.angle;
                 angles[tree$tip == current.node.id] <- parent.angle;
                 }
 
@@ -140,7 +146,12 @@ split.equal.x.dist <- function(
     return(angles);
     }
 
-calculate.angles.fixed <- function(v, tree, fixed.angle) {
+calculate.angles.fixed <- function(
+    v,
+    tree,
+    fixed.angle,
+    start.angle
+    ) {
     angles <- v$angle;
     node.ids <- c(v$id[[1]]);
 
@@ -151,7 +162,7 @@ calculate.angles.fixed <- function(v, tree, fixed.angle) {
 
         parent.angle <- angles[current.node.id];
         if (is.na(parent.angle) || length(parent.angle) == 0) {
-            parent.angle <- 0;
+            parent.angle <- start.angle;
             angles[current.node.id] <- parent.angle;
             }
 

R/calculate.clone.polygons.R

@@ -315,6 +315,7 @@ compute.clones <- function(
     wid = 1.2,
     extra.len = 1,
     tree = NULL,
+    start.angle = 0,
     fixed.angle = NULL,
     beta.in = 3,
     branching = TRUE,
@@ -331,9 +332,20 @@ compute.clones <- function(
 	    tree$angle <- if ((is.null(fixed.angle) && nrow(v) > 6) || any(table(v$parent) > 2) || any(v$mode == 'dendrogram')) {
 			tau <- -(pi / 2.5);
     		vi <- v[v$parent == -1, ];
-    		calculate.angles.radial(v, tree, spread, abs(tau));
+    		calculate.angles.radial(
+    		    v,
+    		    tree,
+    		    spread,
+    		    abs(tau),
+    		    start.angle = start.angle
+    		    );
 	    } else {
-	        calculate.angles.fixed(v, tree, fixed.angle);
+	        calculate.angles.fixed(
+	            v,
+	            tree,
+	            fixed.angle,
+	            start.angle = start.angle
+	            );
 	        }
 	    tmp <- position.nodes(v, tree, extra.len);
 

R/make.clone.polygons.R

@@ -6,6 +6,7 @@ make.clone.polygons <- function(
     scale2,
     extra.len,
     node.col,
+    start.angle,
     spread = 1,
     fixed.angle = NULL,
     beta.in = 3,
@@ -32,6 +33,7 @@ make.clone.polygons <- function(
 	    extra.len = extra.len,
 	    x = 0,
 	    y = tree$length[tree$parent == -1],
+	    start.angle = start.angle,
 	    fixed.angle = fixed.angle,
 	    beta.in = beta.in,
 	    branching = branching,

R/make.clone.tree.grobs.R

@@ -13,6 +13,7 @@ make.clone.tree.grobs <- function(
     cluster.list,
     add.polygons,
     spread,
+    start.angle,
     fixed.angle,
     add.node.text,
     text.df,
@@ -75,7 +76,7 @@ make.clone.tree.grobs <- function(
 
     #initializing line segment dataframe and adjusting lengths to accomodate the node circles
     tree$angle <- numeric(length = nrow(tree));
-    tree$angle[tree$parent == -1] <- 0;
+    tree$angle[tree$parent == -1] <- start.angle;
     if ('length2' %in% colnames(tree)) {
         tree$length2.c <- tree$length2 / scale1 * scale2;
 
@@ -105,6 +106,7 @@ make.clone.tree.grobs <- function(
         extra.len,
         node.col,
         spread = spread,
+        start.angle = start.angle,
         fixed.angle = fixed.angle,
         add.polygons = add.polygons,
         no.ccf = no.ccf

R/position.nodes.radial.R

@@ -56,8 +56,8 @@ position.nodes <- function(v, tree, extra.len) {
 			v$x[v$id == vi$id] <<- v$x[v$id == vi$parent] + dx;
 			v$y[v$id == vi$id] <<- v$y[v$id == vi$parent] + dy;
 		} else {
-		    v$x[v$id == vi$id] <<- 0;
-			v$y[v$id == vi$id] <<- distance;
+		    v$x[v$id == vi$id] <<- dx;
+			v$y[v$id == vi$id] <<- dy;
 		    }
 
 		for (child in v$id[v$parent == vi$id]) {

R/prep.tree.R

@@ -654,6 +654,34 @@ prep.node.size <- function(tree.df) {
     return(node.size);
     }
 
+prep.plotting.direction <- function(direction, radians = TRUE) {
+    if (length(direction) > 1) {
+        stop('"plotting.direction" must be a scalar value.');
+        }
+
+    if (is.character(direction)) {
+        direction <- switch(
+            direction,
+            'down' = 0,
+            'up' = pi,
+            'left' = -pi / 2,
+            'right' = pi / 2,
+            NA
+            );
+        if (is.na(direction)) {
+            stop('A character value for "plotting.direction" must be one of "down", "up", "left", or "right".')
+            }
+    } else if (is.numeric(direction)) {
+        if (!radians) {
+            direction <- degrees.to.radians(direction);
+            }
+        direction <- direction %% (2 * pi);
+    } else {
+        stop('"plotting.direction" must be numeric or one of "down", "up", "left", or "right".');
+        }
+    return(direction);
+    }
+
 # default.values must be either a scalar or matching length of column.values.
 # A scalar will be applied to all NAs.
 # Otherwise, the corresponding value from default.values will be used.

man/SRCGrob.Rd

@@ -10,6 +10,7 @@ SRCGrob(
     tree,
     node.text = NULL,
     main = NULL,
+    plotting.direction = 'down',
     horizontal.padding = 0.1,
     scale1 = 1,
     scale2 = 1,
@@ -46,6 +47,11 @@ SRCGrob(
     \item{tree}{Tree structure data.frame}
     \item{node.text}{Dataframe for text labels to be displayed next to nodes}
     \item{main}{Main plot title}
+    \item{plotting.direction}{
+    Sets the direction of flow for the tree.
+    Can be one of 'down', 'right', 'up', 'left', or a number in degrees.
+    (Default is 0, downward).
+    }
     \item{horizontal.padding}{
     Increase/reduce the plot's horizontal padding proportionally.
     A positive value will expand the padding, and a negative value will reduce it.

tests/testthat/test-angles.R

@@ -1,5 +1,5 @@
 test_that(
-    'calculate.angles.fixed orders nodes correctly', {
+    'calculate.angles.radial orders nodes correctly', {
         num.children <- 4;
         test.tree <- data.frame(
             parent = c(-1, rep(1, num.children))
@@ -19,7 +19,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = total.angle
+            total.angle = total.angle,
+            start.angle = 0
             );
         result.order <- order(result);
         child.ids <- as.numeric(test.tree$tip[test.tree$parent == 1]);
@@ -50,7 +51,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = total.angle
+            total.angle = total.angle,
+            start.angle = 0
             );
 
         num.digits <- 6;
@@ -93,7 +95,8 @@ test_that(
             test.v,
             test.tree,
             spread = spread,
-            total.angle = total.angle
+            total.angle = total.angle,
+            start.angle = 0
             );
 
         result.range <- range(result);
@@ -127,7 +130,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = pi / 2.5
+            total.angle = pi / 2.5,
+            start.angle = 0
             );
 
         expect_equal(result[angles.to.override], override.values);
@@ -156,7 +160,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = pi / 2.5
+            total.angle = pi / 2.5,
+            start.angle = 0
             );
 
         expect_equal(mean(result[-1]), new.angle);
@@ -190,7 +195,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = total.angle
+            total.angle = total.angle,
+            start.angle = 0
             );
         result.angle.increments <- c(
             result[3] - result[2],
@@ -233,7 +239,8 @@ test_that(
             test.v,
             test.tree,
             spread = 1,
-            total.angle = total.angle
+            total.angle = total.angle,
+            start.angle = 0
             );
         result.angle.increments <- c(
             result[3] - result[2],
@@ -268,7 +275,8 @@ test_that(
         result <- calculate.angles.fixed(
             test.v,
             test.tree,
-            fixed.angle = angle
+            fixed.angle = angle,
+            start.angle = 0
             );
         expected.result <- c(0, -(angle), angle);
 
@@ -298,7 +306,8 @@ test_that(
         result <- calculate.angles.fixed(
             test.v,
             test.tree,
-            fixed.angle = pi / 4
+            fixed.angle = pi / 4,
+            start.angle = 0
             );
 
         expect_equal(result[angles.to.override], override.values);
@@ -327,7 +336,8 @@ test_that(
         result <- calculate.angles.fixed(
             test.v,
             test.tree,
-            fixed.angle = fixed.angle
+            fixed.angle = fixed.angle,
+            start.angle = 0
             );
         result.angle.range <- result[3] - result[2];
         expected.angle.range <- fixed.angle * 2 * spread;