Update animate_join function and documentation

animate_join() now lives in animate_join.R with the other animate_join_ functions. These all use rlang::enquo() to capture their arguments so that animate_join() can print the variable name in the plot title.

R/animate_helpers.R

@@ -57,61 +57,3 @@ animate_set <- function(x, y, type, export = "gif", ...) {
     static_plot(step1, title, ...)
   }
 }
-
-#' Animates a join - wrapper function
-#'
-#' @param x left dataset
-#' @param y right dataset
-#' @param by by arguments for the join
-#' @param type type of the join, i.e., left_join, right_join, etc.
-#' @param export if the function exports a gif, the first, or last picture
-#' @param ... further arguments passed to static_plot or to add_color
-#'
-#' @return either a gif or a ggplot
-#'
-#' @name animate_join_function
-#'
-#' @examples
-#' NULL
-animate_join <- function(x, y, by, type, export = "gif", ...) {
-
-  if (!type %in% c("full_join", "inner_join", "left_join", "right_join",
-                   "semi_join", "anti_join"))
-    stop("type has to be a dplyr-join")
-
-  if (!export %in% c("gif", "first", "last"))
-    stop("export must be either gif, first, or last")
-
-  by_args <- ifelse(length(by) == 1,
-                    sprintf("\"%s\"", by),
-                    sprintf("c(\"%s\")", paste(by, collapse = "\", \""))
-                    )
-
-  title <- sprintf(paste0(type, "(%s, %s, by = %s)"),
-                   deparse(substitute(x)),
-                   deparse(substitute(y)),
-                   by_args)
-
-  if (type %in% c("semi_join", "anti_join")) {
-    # for semi and anti_joins, there is no adding of multiple rows
-    y <- dplyr::distinct(y)
-  }
-
-  ll <- process_join(x, y, by, ...)
-
-  step0 <- bind_rows(ll$x, ll$y) %>% mutate(.frame = 0, .alpha = 1)
-
-  step1 <- move_together(ll$x, ll$y, type) %>% mutate(.frame = 1)
-
-  all <- bind_rows(step0, step1)
-
-  if (export == "gif") {
-    animate_plot(all, title, ...)
-  } else if (export == "first") {
-    title <- ""
-    static_plot(step0, title, ...)
-  } else if (export == "last") {
-    static_plot(step1, title, ...)
-  }
-}
-

R/animate_joins.R

@@ -16,14 +16,8 @@
 #'
 #' @name animate_join
 #' @examples
-#' x <- data_frame(
-#'   id = 1:3,
-#'   x = paste0("x", 1:3)
-#' )
-#' y <- data_frame(
-#'   id = (1:4)[-3],
-#'   y = paste0("y", (1:4)[-3])
-#' )
+#' x <- data_frame(id = 1:3, x = paste0("x", 1:3))
+#' y <- data_frame(id = (1:4)[-3], y = paste0("y", (1:4)[-3]))
 #'
 #' # Animate the first or last state of the join
 #' animate_full_join(x, y, by = "id", export = "first")
@@ -31,72 +25,136 @@
 #'
 #' # animate the transition as a gif (default)
 #' \donttest{
-#'   animate_full_join(x, y, by = "id", export = "gif")
+#' animate_full_join(x, y, by = "id", export = "gif")
 #' }
 #'
 #' # different options include
 #' \donttest{
-#'   animate_full_join(x, y, by = "id")
-#'   animate_inner_join(x, y, by = "id")
-#'   animate_left_join(x, y, by = "id")
-#'   animate_right_join(x, y, by = "id")
-#'   animate_semi_join(x, y, by = "id")
-#'   animate_anti_join(x, y, by = "id")
+#' animate_full_join(x, y, by = "id")
+#' animate_inner_join(x, y, by = "id")
+#' animate_left_join(x, y, by = "id")
+#' animate_right_join(x, y, by = "id")
+#' animate_semi_join(x, y, by = "id")
+#' animate_anti_join(x, y, by = "id")
 #'
-#'   # further arguments can be passed to all animate_* functions
-#'   animate_full_join(
-#'     x, y, by = "id", export = "last",
-#'     text_size = 5, title_size = 25,
-#'     color_header = "black",
-#'     color_other = "lightblue",
-#'     color_fun = viridis::viridis
-#'   )
+#' # further arguments can be passed to all animate_* functions
+#' animate_full_join(
+#'   x, y, by = "id", export = "last",
+#'   text_size = 5, title_size = 25,
+#'   color_header = "black",
+#'   color_other = "lightblue",
+#'   color_fun = viridis::viridis
+#' )
 #' }
 #'
 #' # Save the results
 #' \donttest{
-#'   # to save the ggplot, use
-#'   fj <- animate_full_join(x, y, by = "id", export = "last")
-#'   ggsave("full-join.pdf", fj)
+#' # to save the ggplot, use
+#' fj <- animate_full_join(x, y, by = "id", export = "last")
+#' ggsave("full-join.pdf", fj)
 #'
-#'   # to save the gif, use
-#'   fj <- animate_full_join(x, y, by = "id", export = "gif")
-#'   anim_save(fj, "full-join.gif")
+#' # to save the gif, use
+#' fj <- animate_full_join(x, y, by = "id", export = "gif")
+#' anim_save(fj, "full-join.gif")
 #' }
-NULL
+animate_join <- function(
+  x,
+  y,
+  by,
+  type = c("full_join", "inner_join", "left_join", "right_join",
+           "semi_join", "anti_join"),
+  export = c("gif", "first", "last"),
+  ...
+) {
+  type <- match.arg(type)
+  export <- match.arg(export)
+
+  if (rlang::is_quosure(x)) {
+    x_name <- rlang::quo_name(x)
+    x <- rlang::eval_tidy(x)
+  } else {
+    x_name <- rlang::quo_name(rlang::enquo(x))
+  }
+  if (rlang::is_quosure(y)) {
+    y_name <- rlang::quo_name(y)
+    y <- rlang::eval_tidy(y)
+  } else {
+    y_name <- rlang::quo_name(rlang::enquo(y))
+  }
+
+  by_args <- if (length(by) == 1) sprintf("\"%s\"", by) else
+    sprintf("c(\"%s\")", paste(by, collapse = "\", \""))
+
+  title <- sprintf(paste0(type, "(%s, %s, by = %s)"), x_name, y_name, by_args)
+
+  if (type %in% c("semi_join", "anti_join")) {
+    # for semi and anti_joins, there is no adding of multiple rows
+    y <- dplyr::distinct(y)
+  }
+
+  ll <- process_join(x, y, by, ...)
+
+  step0 <- bind_rows(ll$x, ll$y) %>% mutate(.frame = 0, .alpha = 1)
+
+  step1 <- move_together(ll$x, ll$y, type) %>% mutate(.frame = 1)
+
+  all <- bind_rows(step0, step1)
+
+  if (export == "gif") {
+    animate_plot(all, title, ...)
+  } else if (export == "first") {
+    title <- ""
+    static_plot(step0, title, ...)
+  } else if (export == "last") {
+    static_plot(step1, title, ...)
+  }
+}
+
 
 #' @rdname animate_join
 #' @export
 animate_full_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "full_join", export = export, ...)
 }
 
 #' @rdname animate_join
 #' @export
 animate_inner_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "inner_join", export = export, ...)
 }
 
 #' @rdname animate_join
 #' @export
 animate_left_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "left_join", export = export, ...)
 }
 
 #' @rdname animate_join
 #' @export
 animate_right_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "right_join", export = export, ...)
 }
 
 #' @rdname animate_join
 #' @export
 animate_semi_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "semi_join", export = export, ...)
 }
 
 #' @rdname animate_join
 #' @export
 animate_anti_join <- function(x, y, by, export = "gif", ...) {
+  x <- rlang::enquo(x)
+  y <- rlang::enquo(y)
   animate_join(x, y, by, type = "anti_join", export = export, ...)
 }

man/animate_join.Rd

@@ -10,6 +10,10 @@
 \alias{animate_anti_join}
 \title{Animates a join operation}
 \usage{
+animate_join(x, y, by, type = c("full_join", "inner_join", "left_join",
+  "right_join", "semi_join", "anti_join"), export = c("gif", "first",
+  "last"), ...)
+
 animate_full_join(x, y, by, export = "gif", ...)
 
 animate_inner_join(x, y, by, export = "gif", ...)
@@ -42,14 +46,8 @@ Functions to visualise the join operations either static as a ggplot, or
 dynamic as a gif.
 }
 \examples{
-x <- data_frame(
-  id = 1:3,
-  x = paste0("x", 1:3)
-)
-y <- data_frame(
-  id = (1:4)[-3],
-  y = paste0("y", (1:4)[-3])
-)
+x <- data_frame(id = 1:3, x = paste0("x", 1:3))
+y <- data_frame(id = (1:4)[-3], y = paste0("y", (1:4)[-3]))
 
 # Animate the first or last state of the join
 animate_full_join(x, y, by = "id", export = "first")
@@ -57,37 +55,37 @@ animate_full_join(x, y, by = "id", export = "last")
 
 # animate the transition as a gif (default)
 \donttest{
-  animate_full_join(x, y, by = "id", export = "gif")
+animate_full_join(x, y, by = "id", export = "gif")
 }
 
 # different options include
 \donttest{
-  animate_full_join(x, y, by = "id")
-  animate_inner_join(x, y, by = "id")
-  animate_left_join(x, y, by = "id")
-  animate_right_join(x, y, by = "id")
-  animate_semi_join(x, y, by = "id")
-  animate_anti_join(x, y, by = "id")
-
-  # further arguments can be passed to all animate_* functions
-  animate_full_join(
-    x, y, by = "id", export = "last",
-    text_size = 5, title_size = 25,
-    color_header = "black",
-    color_other = "lightblue",
-    color_fun = viridis::viridis
-  )
+animate_full_join(x, y, by = "id")
+animate_inner_join(x, y, by = "id")
+animate_left_join(x, y, by = "id")
+animate_right_join(x, y, by = "id")
+animate_semi_join(x, y, by = "id")
+animate_anti_join(x, y, by = "id")
+
+# further arguments can be passed to all animate_* functions
+animate_full_join(
+  x, y, by = "id", export = "last",
+  text_size = 5, title_size = 25,
+  color_header = "black",
+  color_other = "lightblue",
+  color_fun = viridis::viridis
+)
 }
 
 # Save the results
 \donttest{
-  # to save the ggplot, use
-  fj <- animate_full_join(x, y, by = "id", export = "last")
-  ggsave("full-join.pdf", fj)
+# to save the ggplot, use
+fj <- animate_full_join(x, y, by = "id", export = "last")
+ggsave("full-join.pdf", fj)
 
-  # to save the gif, use
-  fj <- animate_full_join(x, y, by = "id", export = "gif")
-  anim_save(fj, "full-join.gif")
+# to save the gif, use
+fj <- animate_full_join(x, y, by = "id", export = "gif")
+anim_save(fj, "full-join.gif")
 }
 }
 \seealso{

man/animate_join_function.Rd

@@ -1,31 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/animate_helpers.R
-\name{animate_join_function}
-\alias{animate_join_function}
-\alias{animate_join}
-\title{Animates a join - wrapper function}
-\usage{
-animate_join(x, y, by, type, export = "gif", ...)
-}
-\arguments{
-\item{x}{left dataset}
-
-\item{y}{right dataset}
-
-\item{by}{by arguments for the join}
-
-\item{type}{type of the join, i.e., left_join, right_join, etc.}
-
-\item{export}{if the function exports a gif, the first, or last picture}
-
-\item{...}{further arguments passed to static_plot or to add_color}
-}
-\value{
-either a gif or a ggplot
-}
-\description{
-Animates a join - wrapper function
-}
-\examples{
-NULL
-}