Merge pull request #22 from nrennie/doc-node-style-vignette

Doc node style vignette

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ggflowchart
 Title: Flowcharts with 'ggplot2'
-Version: 1.0.0.9000
+Version: 1.0.0.9001
 Authors@R: 
     person(given = "Nicola",
            family = "Rennie",
@@ -17,15 +17,18 @@ Imports:
   dplyr,
   igraph,
   ggplot2,
+  purrr,
   rlang,
   tibble, 
   tidyr
 Suggests: 
-  knitr,
-  rcartocolor,
-  rmarkdown
+    knitr,
+    rcartocolor,
+    rmarkdown,
+    testthat (>= 3.0.0)
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
 VignetteBuilder: knitr
 Config/Needs/website: nrennie/nrenniepkgdown
 URL: https://nrennie.github.io/ggflowchart/
+Config/testthat/edition: 3

NEWS.md

@@ -1,3 +1,9 @@
+## ggflowchart 1.0.0.9001 2023_05_20
+
+* Add vignette on how to style nodes
+* Add initial unit testing
+* Add utils function to determine arrow type
+
 ## ggflowchart 1.0.0.9000 2023_05_19
 
 * Add ability to add arrow labels (issue #15)

R/arrow_direction.R

@@ -0,0 +1,56 @@
+#' Single arrow direction
+#'
+#' Define the direction of a single arrow
+#'
+#' @param plot_nodes Tibble of node coordinates output from \code{get_nodes()}.
+#' @param from Character name of starting node.
+#' @param to Character name of end node.
+#' @importFrom rlang .data
+#' @return A tibble.
+#' @noRd
+
+single_arrow_direction <- function(plot_nodes,
+                                   from,
+                                   to) {
+  # calculate slope
+  from_coords <- unlist(dplyr::filter(plot_nodes, .data$name == from)[, c("x", "y")])
+  to_coords <- unlist(dplyr::filter(plot_nodes, .data$name == to)[, c("x", "y")])
+  x_diff <- to_coords["x"] - from_coords["x"]
+  y_diff <- (to_coords["y"] - from_coords["y"])
+  # arrow type
+  if (y_diff == 0 && x_diff > 0) {
+    return("lr")
+  } else if (y_diff == 0 && x_diff < 0) {
+    return("rl")
+  } else if (y_diff > 0) {
+    return("bt")
+  } else {
+    return("tb")
+  }
+}
+
+#' Arrow direction
+#'
+#' Define the direction of each arrow
+#' @param data Data frame or tibble of edges. Must have two columns, first
+#' column are "from" node names, second column is "to" node names.
+#' Node names must be unique.
+#' @param plot_nodes Tibble of node coordinates output from \code{get_nodes()}.
+#' @param node_layout Data frame of node layout returned by \code{get_layout()}
+#' @importFrom rlang .data
+#' @return A tibble.
+#' @noRd
+
+arrow_direction <- function(data,
+                            plot_nodes,
+                            node_layout) {
+  data %>%
+    dplyr::mutate(
+      arrow_direction = purrr::map2(
+        .x = data$from,
+        .y = data$to,
+        .f = ~ single_arrow_direction(node_layout, .x, .y)
+      ) %>%
+        unlist()
+    )
+}

tests/testthat.R

@@ -0,0 +1,12 @@
+# This file is part of the standard setup for testthat.
+# It is recommended that you do not modify it.
+#
+# Where should you do additional test configuration?
+# Learn more about the roles of various files in:
+# * https://r-pkgs.org/tests.html
+# * https://testthat.r-lib.org/reference/test_package.html#special-files
+
+library(testthat)
+library(ggflowchart)
+
+test_check("ggflowchart")

tests/testthat/test-column-tests.R

@@ -0,0 +1,3 @@
+test_that("Single column fails", {
+  expect_error(ggflowchart(data = data.frame(from = c(1, 2, 3))))
+})

vignettes/style-nodes.Rmd

@@ -0,0 +1,79 @@
+---
+title: "Styling Flowchart Nodes"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{style-nodes}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup, warning=FALSE}
+library(ggflowchart)
+```
+
+Create a tibble (or data frame) with each row representing an edge.
+
+```{r data}
+data <- tibble::tribble(
+  ~from, ~to,
+  "A", "B",
+  "B", "C"
+)
+```
+
+Vary the widths of the nodes by adding a column called `x_nudge` to the `node_data`:
+
+```{r node-width}
+node_data <- tibble::tribble(
+  ~name, ~x_nudge,
+  "A", 0.3,
+  "B", 0.4,
+  "C", 0.5
+)
+ggflowchart(data, node_data)
+```
+
+Similarly, the height of the boxes can vary by adding a column called `y_nudge`. If neither `x_nudge` or `y_nudge` columns are present in `node_data`, then the values specified in the `x_nudge` or `y_nudge` arguments of `ggflowchart()` are used for all boxes.
+
+Vary the fill colours of the nodes by specifying a column in `node_data` to colour by:
+
+```{r node-fill}
+node_data <- tibble::tribble(
+  ~name, ~type,
+  "A", "Yes",
+  "B", "Yes",
+  "C", "No"
+)
+ggflowchart(data, node_data, fill = type)
+```
+
+You can use existing `scale_fill_*` functions to change the colours:
+
+```{r node-fill-change}
+ggflowchart(data, node_data, fill = type) +
+  ggplot2::scale_fill_brewer(palette = "Dark2")
+```
+
+Alternatively, if you want them all to be the same colour you can specify a single colour instead:
+
+```{r node-fill-one}
+ggflowchart(data, node_data, fill = "lightblue")
+```
+
+Note that quoting column names also works, e.g. `ggflowchart(data, node_data, fill = "type")` gives the same output as `ggflowchart(data, node_data, fill = type)`. This means that if you have a column in `node_data` called `"lightblue"` and you want to colour all of the nodes light blue instead of using the values in the `"lightblue"` column, you would need to rename the column.
+
+You can do something very similar to change the colour of the text in the nodes:
+
+```{r node-text}
+ggflowchart(data, node_data, text_colour = type) +
+  ggplot2::theme(legend.position = "none")
+```
+
+You will soon also be able to change the shape of nodes - keep an eye on the development version for this feature!