Merge pull request #19 from gadenbuie/pkg-add-anim-opts-fixed

Add framework for animation options (fixed)

NAMESPACE

@@ -1,6 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,anim_opts)
 export("%>%")
+export(anim_options)
+export(anim_options_set)
 export(animate_anti_join)
 export(animate_full_join)
 export(animate_gather)
@@ -13,6 +16,8 @@ export(animate_setdiff)
 export(animate_spread)
 export(animate_union)
 export(animate_union_all)
+export(get_font_size)
+export(is.anim_opts)
 export(set_font_size)
 importFrom(dplyr,anti_join)
 importFrom(dplyr,arrange)

R/animate_options.R

@@ -0,0 +1,213 @@
+#' Animation Options
+#'
+#' Helper function to set animation and plotting options to be passed to
+#' [animate_plot()] and [static_plot()].
+#'
+#' @param text_family Font family for the plot text, default is "Fira Mono". Use
+#'   [set_font_size()] to set global default font sizes.
+#' @param title_family Font family for the plot title, default is "Fira Mono".
+#'   Use [set_font_size()] to set global default font sizes.
+#' @param text_size Font size of the plot text, default is 5.
+#' @param title_size Font size of the plot title, default is 17.
+#' @param ease_default Default aes easing function. See [tweenr::display_ease()]
+#'   for more options. The tidyexplain default value is `sine-in-out`.
+#' @param ease_other Additional aes easing options, specified as a named list.
+#'   List entries are named with the aesthetic to which the easeing should be
+#'   applied, consistent with [gganimate::ease_aes()]. E.g. `list(color =
+#'   "sine")`.
+#' @param enter Enter fading function applied to objects in the animation. See
+#'   [gganimate::enter_exit] for a complete list of options. The tidyexplain
+#'   default is [gganimate::enter_fade()].
+#' @param exit Exit fading function applied to objects in the animation. See
+#'   [gganimate::enter_exit] for a complete list of options. The tidyexplain
+#'   default is [gganimate::exit_fade()].
+#' @inheritParams gganimate::transition_states
+#' @export
+anim_options <- function(
+  transition_length = NULL,
+  state_length = NULL,
+  ease_default = NULL,
+  ease_other   = NULL,
+  enter        = NULL,
+  exit         = NULL,
+  text_family  = NULL,
+  title_family = NULL,
+  text_size    = NULL,
+  title_size   = NULL,
+  ...
+){
+  enter_name <- if (!missing(enter)) rlang::quo_name(rlang::enquo(enter))
+  exit_name <- if (!missing(exit))   rlang::quo_name(rlang::enquo(exit))
+  ao <- list(
+    transition_length = transition_length,
+    state_length = state_length,
+    ease_default = ease_default,
+    ease_other   = ease_other,
+    enter        = if (!is.null(enter)) setNames(list(enter), enter_name),
+    exit         = if (!is.null(exit))  setNames(list(exit), exit_name),
+    text_family  = text_family,
+    text_size    = text_size,
+    title_family = title_family,
+    title_size   = title_size,
+    ...
+  )
+  ao <- purrr::compact(ao)
+  structure(ao, class = "anim_opts")
+}
+
+
+# Global Animation Options Setters and Getters ----------------------------
+
+#' @describeIn anim_options Set default animation options for the current session.
+#' @param anim_opts An [anim_options()] options list.
+#' @export
+anim_options_set <- function(anim_opts = anim_options()) {
+  stopifnot(is.anim_opts(anim_opts))
+  ao_old <- plot_settings$anim_opts
+  plot_settings$anim_opts <- merge(anim_opts, plot_settings$anim_opts)
+  invisible(ao_old)
+}
+
+get_anim_opt <- function(anim_opt = NULL) {
+  if (is.null(anim_opt)) return(plot_settings$anim_opts)
+  if (anim_opt %in% c("text_size", "title_size")) rlang::abort(
+    "Use get_text_size() or get_title_size()"
+  )
+  plot_settings$anim_opts[[anim_opt]] %||% plot_settings$default[[anim_opt]]
+}
+
+
+# Animation Options Methods -----------------------------------------------
+
+#' @export
+print.anim_opts <- function(x) {
+  # Replace ggproto (enter/exit functions) with their names
+  if ("enter" %in% names(x)) x$enter <- paste("ggproto:", names(x$enter))
+  if ("exit"  %in% names(x)) x$exit  <- paste("ggproto:", names(x$exit))
+  anim_opts <- capture.output(str(x, no.list = TRUE))
+  cat(
+    paste0("<anim_options: ", length(x), " options>"),
+    anim_opts, sep = "\n"
+  )
+}
+
+#' @export
+is.anim_opts <- function(ao) inherits(ao, "anim_opts")
+
+
+# Fill, Validate, Merge Animation Options ---------------------------------
+
+# Fills in default animation options
+fill_anim_opts <- function(ao) {
+  ao$transition_length <- ao$transition_length %||% get_anim_opt("transition_length")
+  ao$state_length <- ao$state_length %||% get_anim_opt("state_length")
+  ao$ease_default <- ao$ease_default %||% get_anim_opt("ease_default")
+  ao$ease_other   <- ao$ease_other   %||% get_anim_opt("ease_other")
+  ao$enter        <- ao$enter        %||% get_anim_opt("enter")
+  ao$exit         <- ao$exit         %||% get_anim_opt("exit")
+  ao$text_family  <- ao$text_family  %||% get_anim_opt("text_family")
+  ao$title_family <- ao$title_family %||% get_anim_opt("title_family")
+  ao
+}
+
+validate_anim_opts <- function(ao, quiet = FALSE, strict = getOption("tidyexplain.strict_dots", FALSE)) {
+  if (!inherits(ao, "anim_opts")) {
+    rlang::warn("Use `anim_options()` to set `anim_opts`")
+  }
+  ao <- fill_anim_opts(ao)
+  stopifnot(is.ggproto(ao$enter[[1]]), is.ggproto(ao$exit[[1]]))
+  extra_names <- setdiff(names(ao), names(formals(anim_options)))
+  if (!quiet && length(extra_names)) {
+    extra_names <- paste0(sprintf("`%s`", extra_names), collapse = ", ")
+    msg <- paste("Unknown animation options will be ignored:", extra_names)
+    if (isTrue(strict)) rlang::abort(msg) else rlang::warn(msg)
+  }
+  invisible(ao)
+}
+
+merge.anim_opts <- function(ao_new, ao_base = anim_options()) {
+  ao_new  <- purrr::discard(ao_new, is.null)
+  ao_base <- purrr::discard(ao_base, is.null)
+  unique_base <- setdiff(names(ao_base), names(ao_new))
+  ao <- append(ao_new, ao_base[unique_base])
+  ao <- ao[names(formals(anim_options))]
+  ao <- purrr::discard(ao, is.null)
+  class(ao) <- "anim_opts"
+  ao
+}
+
+
+# Default Animation Options for Verb Families -----------------------------
+
+default_anim_opts <- function(family, ao_custom = NULL) {
+  family_options <- c("join", "set", "gather", "spread")
+  family <- match.arg(family, family_options, several.ok = FALSE)
+  ao_default <- switch(
+    family,
+    "gather" = anim_options(enter = enter_fade(), exit = exit_fade(),
+                            ease_default = "sine-in-out",
+                            ease_other = list(y = "cubic-out", x = "cubic-in")),
+    "spread" = anim_options(enter = enter_fade(), exit = exit_fade(),
+                            ease_default = "sine-in-out",
+                            ease_other = list(y = "cubic-out", x = "cubic-in")),
+    anim_options()
+  )
+  if (is.null(ao_custom)) {
+    # User set globals override defaults
+    ao_custom <- get_anim_opt()
+  } else {
+    # Opts from function call override user-set globals
+    ao_custom <- merge(ao_custom, get_anim_opt())
+  }
+  # function > user-set global > default (> global default)
+  if (!is.null(ao_custom)) merge(ao_custom, ao_default) else ao_default
+}
+
+# Font Size Setters and Getters -------------------------------------------
+
+#' Set Default Text Sizes for Animation Plots
+#'
+#' Sets the default text sizes for the animated and static plots produced by
+#' this package during the current session.
+#'
+#' @param text_size Font size of value labels inside the data frame squares
+#' @param title_size Font size of the function call or plot title
+#' @export
+set_font_size <- function(text_size = NULL, title_size = NULL) {
+  old <- list()
+  if (!is.null(text_size)) old$text_size <- set_text_size(text_size)
+  if (!is.null(title_size)) old$title_size <- set_title_size(title_size)
+  invisible(old)
+}
+
+#' @describeIn set_font_size Get current global font sizes
+#' @export
+get_font_size <- function() {
+  list("text_size"  = get_text_size(), "title_size" = get_title_size())
+}
+
+set_text_size <- function(size) {
+  old <- plot_settings$text_size
+  anim_options_set(anim_options(text_size = size))
+  invisible(old)
+}
+
+set_title_size <- function(size) {
+  old <- plot_settings$title_size
+  anim_options_set(anim_options(title_size = size))
+  invisible(old)
+}
+
+get_text_size <- function(x = NULL) {
+  if (!is.null(x)) return(x)
+  plot_settings$anim_opts$text_size %||%
+    getFromNamespace("theme_env", "ggplot2")$current$text$size %||%
+    plot_settings$default$text_size
+}
+
+get_title_size <- function(x = NULL) {
+  if (!is.null(x)) return(x)
+  plot_settings$anim_opts$title_size %||%
+    getFromNamespace("theme_env", "ggplot2")$current$plot.title$size %||%
+    plot_settings$default$title_size
+}

R/animate_tidyr.R

@@ -1,14 +1,14 @@
-
 #' Animates the gather function
 #'
 #' @param w a data_frame in the wide format
 #' @param key the key
 #' @param value the value
-#' @param ... further arguments passed to gather, static_plot, or animate_plot
-#' @param export the export type, either gif, first or last. The latter two
-#'          export ggplots of the first/last state of the gather function
+#' @param ... further arguments passed to [tidyr::gather()], [process_wide()],
+#'   or [process_long()]
 #' @param detailed boolean value if the animation should show one step for each
-#'              key value
+#'   key value
+#' @inheritParams animate_join
+#' @inheritParams anim_options
 #'
 #' @return a gif or a ggplot
 #' @export
@@ -28,7 +28,8 @@
 #'   # if you want to have a less detailed animation, you can also use
 #'   animate_gather(wide, "person", "sales", -year, export = "gif", detailed = FALSE)
 #' }
-animate_gather <- function(w, key, value, ..., export = "gif", detailed = TRUE) {
+animate_gather <- function(w, key, value, ..., export = "gif", detailed = TRUE, anim_opts = anim_options()) {
+  anim_opts <- default_anim_opts("gather", anim_opts)
   lhs <- w
   rhs <- tidyr::gather(w, !!key, !!value, ...)
 
@@ -58,20 +59,17 @@ animate_gather <- function(w, key, value, ..., export = "gif", detailed = TRUE)
   rhs_proc <- process_long(rhs, ids, key, value, ...)
 
   gather_spread(lhs_proc, rhs_proc, sequence = sequence, key_values = key_values,
-                export = export, detailed = detailed, ...)
+                export = export, detailed = detailed, ..., anim_opts = anim_opts)
 }
 
 
 #' Animates the spread function
 #'
 #' @param l a data_frame in the long/tidy format
-#' @param key the key
-#' @param value the values
-#' @param export the export type, either gif, first or last. The latter two
-#'              export ggplots of the first/last state of the spread function
-#' @param detailed boolean value if the animation should show one step for each
-#'              key value
-#' @param ... further arguments passed to static_plot
+#' @param ... further arguments passed to [process_long] or [process_wide]
+#' @inheritParams animate_gather
+#' @inheritParams animate_join
+#' @inheritParams anim_options
 #'
 #' @return a ggplot or a gif
 #' @export
@@ -90,7 +88,8 @@ animate_gather <- function(w, key, value, ..., export = "gif", detailed = TRUE)
 #'   # if you want to have a less detailed animation, you can also use
 #'   animate_spread(long, key = "person", value = "sales", export = "gif", detailed = FALSE)
 #' }
-animate_spread <- function(l, key, value, export = "gif", detailed = TRUE, ...) {
+animate_spread <- function(l, key, value, export = "gif", detailed = TRUE, ..., anim_opts = anim_options()) {
+  anim_opts <- default_anim_opts("spread", anim_opts)
 
   lhs <- l
   rhs <- tidyr::spread(l, key = key, value = value)
@@ -120,5 +119,5 @@ animate_spread <- function(l, key, value, export = "gif", detailed = TRUE, ...)
   rhs_proc <- process_wide(rhs, ids, key, value, ...)
 
   key_values <- lhs %>% pull(key) %>% unique()
-  gather_spread(lhs_proc, rhs_proc, sequence, key_values, export, detailed, ...)
+  gather_spread(lhs_proc, rhs_proc, sequence, key_values, export, detailed, ..., anim_opts = anim_opts)
 }

R/plot_helpers.R

@@ -1,33 +1,37 @@
-#' Animates a plot
-#'
-#' @param d a preprocessed dataset
-#' @param title the plot title
-#' @param transition_length see transition_states
-#' @param state_length see transition_states
-#' @param ... further arguments passed to static_plot
-#'
-#' @return a gif
+#' Animate a Plot
 #'
+#' @param d a processed dataset
+#' @param title the title of the plot
+#' @param anim_opts Animation options generated with [anim_options()]. Overrides
+#'   any options set in `...`.
+#' @return a `gganim` object
 #' @examples
 #' NULL
-animate_plot <- function(d, title = "", transition_length = 2, state_length = 1, ...) {
-  static_plot(d, title, ...) +
-    transition_states(.frame, transition_length, state_length) +
-    enter_fade() +
-    exit_fade() +
-    ease_aes("sine-in-out")
+animate_plot <- function(
+  d,
+  title = "",
+  ...,
+  anim_opts = anim_options(...)
+) {
+  ao <- validate_anim_opts(anim_opts)
+  ease_opts <- if (!is.null(ao$ease_other)) {
+    ao$ease_other$default <- ao$ease_default
+    ao$ease_other
+    } else list(default = ao$ease_default)
+  ao_ease_aes <- do.call(ease_aes, ease_opts)
+
+  static_plot(d, title, anim_opts = ao) +
+    transition_states(.frame, ao$transition_length, ao$state_length) +
+    ao$enter[[1]] +
+    ao$exit[[1]] +
+    ao_ease_aes
 }
 
 
 #' Prints the tiles for a processed dataset statically
 #'
-#' @param d a processed dataset
-#' @param title the title of the plot
-#' @param text_family the font for the text
-#' @param title_family the font for the title
-#' @param text_size the size of the text
-#' @param title_size the size of the title
-#' @param ... further arguments
+#' @inheritParams animate_plot
+#' @inheritDotParams anim_options
 #'
 #' @return a ggplot
 #'
@@ -36,12 +40,12 @@ animate_plot <- function(d, title = "", transition_length = 2, state_length = 1,
 static_plot <- function(
   d,
   title = "",
-  text_family = "Fira Sans", title_family = "Fira Mono",
-  text_size = NULL, title_size = NULL,
-  ...
+  ...,
+  anim_opts = anim_options(...)
 ) {
-  text_size <- get_text_size(text_size, default = 5)
-  title_size <- get_title_size(title_size, default = 17)
+  ao <- validate_anim_opts(anim_opts)
+  text_size <- get_text_size(ao$text_size)
+  title_size <- get_title_size(ao$title_size)
 
   if (!".alpha" %in% names(d)) d <- d %>% mutate(.alpha = 1)
   if (!".textcolor" %in% names(d))
@@ -58,53 +62,11 @@ static_plot <- function(
     geom_tile(width = 0.9, height = 0.9) +
     coord_equal() +
     geom_text(data = d %>% filter(!is.na(.val)), aes(label = .val, color = .textcolor),
-              family = text_family, size = text_size) +
+              family = ao$text_family, size = text_size) +
     scale_fill_identity() +
     scale_color_identity() +
     scale_alpha_identity() +
     labs(title = title) +
     theme_void() +
-    theme(plot.title = element_text(family = title_family, hjust = 0.5, size = title_size))
+    theme(plot.title = element_text(family = ao$title_family, hjust = 0.5, size = title_size))
 }
-
-#' Set Default Text Sizes for Animation Plots
-#'
-#' Sets the default text sizes for the animated and static plots produced by
-#' this package during the current session.
-#'
-#' @param text_size Font size of value labels inside the data frame squares
-#' @param title_size Font size of the function call or plot title
-#' @export
-set_font_size <- function(text_size = NULL, title_size = NULL) {
-  old <- list()
-  if (!is.null(text_size)) old$text_size <- set_text_size(text_size)
-  if (!is.null(title_size)) old$title_size <- set_title_size(title_size)
-  invisible(old)
-}
-
-set_text_size <- function(size) {
-  old <- plot_settings$text_size
-  plot_settings$text_size <- size
-  invisible(old)
-}
-
-set_title_size <- function(size) {
-  old <- plot_settings$title_size
-  plot_settings$title_size <- size
-  invisible(old)
-}
-
-get_text_size <- function(x = NULL, default = 5) {
-  if (!is.null(x)) return(x)
-  plot_settings$text_size %||%
-    getFromNamespace("theme_env", "ggplot2")$current$text$size %||%
-    default
-}
-
-get_title_size <- function(x = NULL, default = 17) {
-  if (!is.null(x)) return(x)
-  plot_settings$title_size %||%
-    getFromNamespace("theme_env", "ggplot2")$current$plot.title$size %||%
-    default
-}
-

R/tidyr_helpers.R

@@ -253,7 +253,7 @@ process_long <- function(x, ids, key, value, ...) {
 #'
 #' @examples
 #' NULL
-gather_spread <- function(lhs, rhs, sequence, key_values, export, detailed, ...) {
+gather_spread <- function(lhs, rhs, sequence, key_values, export, detailed, ..., anim_opts = anim_options()) {
   # lhs is the one state of the df
   # rhs is the target state
 
@@ -342,11 +342,11 @@ gather_spread <- function(lhs, rhs, sequence, key_values, export, detailed, ...)
                            labels = frame_labels))
 
   if (export == "gif") {
-    animate_plot(anim_df, title = title_string, transition_length = tl, state_length = sl) #, ...)
+    animate_plot(anim_df, title = title_string, anim_opts = anim_opts)
   } else if (export == "first") {
-    static_plot(state_start) #....
+    static_plot(state_start, anim_opts = anim_opts) #....
   } else if (export == "last") {
-    static_plot(state_end) #....
+    static_plot(state_end, anim_opts = anim_opts) #....
   }
 
   # open issues: ... doesnt work properly.

R/zzzz-package.R

@@ -5,3 +5,16 @@
 "_PACKAGE"
 
 plot_settings <- new.env(parent = emptyenv())
+plot_settings$default <- list(
+  transition_length = 2,
+  state_length      = 1,
+  ease_default      = "sine-in-out",
+  ease_other        = NULL,
+  enter             = setNames(list(enter_fade()), "enter_fade()"),
+  exit              = setNames(list(exit_fade()), "exit_fade()"),
+  text_family       = "Fira Mono",
+  title_family      = "Fira Mono",
+  text_size         = 5,
+  title_size        = 17
+)
+

README.Rmd

@@ -119,7 +119,8 @@ dplyr::left_join(x, y, by = "id")
 y_extra <- dplyr::bind_rows(y, dplyr::data_frame(id = 2, y = "y5"))
 y_extra # has multiple rows with the key from `x`
 
-animate_left_join(x, y_extra, by = "id")
+animate_left_join(x, y_extra, by = "id", 
+  anim_opts = anim_options(title_size = 22))
 ```
 
 ```{r}

README.md

@@ -145,7 +145,8 @@ y_extra # has multiple rows with the key from `x`
 #> 3     4 y4   
 #> 4     2 y5
 
-animate_left_join(x, y_extra, by = "id")
+animate_left_join(x, y_extra, by = "id", 
+  anim_opts = anim_options(title_size = 22))
 ```
 
 ![](man/figures/tidyexplain-left-join-extra-1.gif)<!-- -->

man/anim_options.Rd

@@ -0,0 +1,57 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/animate_options.R
+\name{anim_options}
+\alias{anim_options}
+\alias{anim_options_set}
+\title{Animation Options}
+\usage{
+anim_options(transition_length = NULL, state_length = NULL,
+  ease_default = NULL, ease_other = NULL, enter = NULL,
+  exit = NULL, text_family = NULL, title_family = NULL,
+  text_size = NULL, title_size = NULL, ...)
+
+anim_options_set(anim_opts = anim_options())
+}
+\arguments{
+\item{transition_length}{The relative length of the transition. Will be
+recycled to match the number of states in the data}
+
+\item{state_length}{The relative length of the pause at the states. Will be
+recycled to match the number of states in the data}
+
+\item{ease_default}{Default aes easing function. See \code{\link[tweenr:display_ease]{tweenr::display_ease()}}
+for more options. The tidyexplain default value is \code{sine-in-out}.}
+
+\item{ease_other}{Additional aes easing options, specified as a named list.
+List entries are named with the aesthetic to which the easeing should be
+applied, consistent with \code{\link[gganimate:ease_aes]{gganimate::ease_aes()}}. E.g. \code{list(color = "sine")}.}
+
+\item{enter}{Enter fading function applied to objects in the animation. See
+\link[gganimate:enter_exit]{gganimate::enter_exit} for a complete list of options. The tidyexplain
+default is \code{\link[gganimate:enter_fade]{gganimate::enter_fade()}}.}
+
+\item{exit}{Exit fading function applied to objects in the animation. See
+\link[gganimate:enter_exit]{gganimate::enter_exit} for a complete list of options. The tidyexplain
+default is \code{\link[gganimate:exit_fade]{gganimate::exit_fade()}}.}
+
+\item{text_family}{Font family for the plot text, default is "Fira Mono". Use
+\code{\link[=set_font_size]{set_font_size()}} to set global default font sizes.}
+
+\item{title_family}{Font family for the plot title, default is "Fira Mono".
+Use \code{\link[=set_font_size]{set_font_size()}} to set global default font sizes.}
+
+\item{text_size}{Font size of the plot text, default is 5.}
+
+\item{title_size}{Font size of the plot title, default is 17.}
+
+\item{anim_opts}{An \code{\link[=anim_options]{anim_options()}} options list.}
+}
+\description{
+Helper function to set animation and plotting options to be passed to
+\code{\link[=animate_plot]{animate_plot()}} and \code{\link[=static_plot]{static_plot()}}.
+}
+\section{Functions}{
+\itemize{
+\item \code{anim_options_set}: Set default animation options for the current session.
+}}
+

man/animate_gather.Rd

@@ -4,7 +4,8 @@
 \alias{animate_gather}
 \title{Animates the gather function}
 \usage{
-animate_gather(w, key, value, ..., export = "gif", detailed = TRUE)
+animate_gather(w, key, value, ..., export = "gif", detailed = TRUE,
+  anim_opts = anim_options())
 }
 \arguments{
 \item{w}{a data_frame in the wide format}
@@ -13,13 +14,16 @@ animate_gather(w, key, value, ..., export = "gif", detailed = TRUE)
 
 \item{value}{the value}
 
-\item{...}{further arguments passed to gather, static_plot, or animate_plot}
+\item{...}{further arguments passed to \code{\link[tidyr:gather]{tidyr::gather()}}, \code{\link[=process_wide]{process_wide()}},
+or \code{\link[=process_long]{process_long()}}}
 
 \item{export}{the export type, either gif, first or last. The latter two
-export ggplots of the first/last state of the gather function}
+export ggplots of the first/last state of the join}
 
 \item{detailed}{boolean value if the animation should show one step for each
 key value}
+
+\item{anim_opts}{An \code{\link[=anim_options]{anim_options()}} options list.}
 }
 \value{
 a gif or a ggplot

man/animate_plot.Rd

@@ -2,27 +2,23 @@
 % Please edit documentation in R/plot_helpers.R
 \name{animate_plot}
 \alias{animate_plot}
-\title{Animates a plot}
+\title{Animate a Plot}
 \usage{
-animate_plot(d, title = "", transition_length = 2, state_length = 1,
-  ...)
+animate_plot(d, title = "", ..., anim_opts = anim_options(...))
 }
 \arguments{
-\item{d}{a preprocessed dataset}
+\item{d}{a processed dataset}
 
-\item{title}{the plot title}
+\item{title}{the title of the plot}
 
-\item{transition_length}{see transition_states}
-
-\item{state_length}{see transition_states}
-
-\item{...}{further arguments passed to static_plot}
+\item{anim_opts}{Animation options generated with \code{\link[=anim_options]{anim_options()}}. Overrides
+any options set in \code{...}.}
 }
 \value{
-a gif
+a \code{gganim} object
 }
 \description{
-Animates a plot
+Animate a Plot
 }
 \examples{
 NULL

man/animate_spread.Rd

@@ -4,22 +4,25 @@
 \alias{animate_spread}
 \title{Animates the spread function}
 \usage{
-animate_spread(l, key, value, export = "gif", detailed = TRUE, ...)
+animate_spread(l, key, value, export = "gif", detailed = TRUE, ...,
+  anim_opts = anim_options())
 }
 \arguments{
 \item{l}{a data_frame in the long/tidy format}
 
 \item{key}{the key}
 
-\item{value}{the values}
+\item{value}{the value}
 
 \item{export}{the export type, either gif, first or last. The latter two
-export ggplots of the first/last state of the spread function}
+export ggplots of the first/last state of the join}
 
 \item{detailed}{boolean value if the animation should show one step for each
 key value}
 
-\item{...}{further arguments passed to static_plot}
+\item{...}{further arguments passed to \link{process_long} or \link{process_wide}}
+
+\item{anim_opts}{An \code{\link[=anim_options]{anim_options()}} options list.}
 }
 \value{
 a ggplot or a gif

man/gather_spread.Rd

@@ -4,7 +4,8 @@
 \alias{gather_spread}
 \title{Animates a gather or spread function}
 \usage{
-gather_spread(lhs, rhs, sequence, key_values, export, detailed, ...)
+gather_spread(lhs, rhs, sequence, key_values, export, detailed, ...,
+  anim_opts = anim_options())
 }
 \arguments{
 \item{lhs}{the (processed) dataset on the left-side}

man/set_font_size.Rd

@@ -1,10 +1,13 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/plot_helpers.R
+% Please edit documentation in R/animate_options.R
 \name{set_font_size}
 \alias{set_font_size}
+\alias{get_font_size}
 \title{Set Default Text Sizes for Animation Plots}
 \usage{
 set_font_size(text_size = NULL, title_size = NULL)
+
+get_font_size()
 }
 \arguments{
 \item{text_size}{Font size of value labels inside the data frame squares}
@@ -15,3 +18,8 @@ set_font_size(text_size = NULL, title_size = NULL)
 Sets the default text sizes for the animated and static plots produced by
 this package during the current session.
 }
+\section{Functions}{
+\itemize{
+\item \code{get_font_size}: Get current global font sizes
+}}
+

man/static_plot.Rd

@@ -4,24 +4,40 @@
 \alias{static_plot}
 \title{Prints the tiles for a processed dataset statically}
 \usage{
-static_plot(d, title = "", text_family = "Fira Sans",
-  title_family = "Fira Mono", text_size = NULL, title_size = NULL,
-  ...)
+static_plot(d, title = "", ..., anim_opts = anim_options(...))
 }
 \arguments{
 \item{d}{a processed dataset}
 
 \item{title}{the title of the plot}
 
-\item{text_family}{the font for the text}
+\item{...}{Arguments passed on to \code{anim_options}
+\describe{
+  \item{text_family}{Font family for the plot text, default is "Fira Mono". Use
+\code{\link[=set_font_size]{set_font_size()}} to set global default font sizes.}
+  \item{title_family}{Font family for the plot title, default is "Fira Mono".
+Use \code{\link[=set_font_size]{set_font_size()}} to set global default font sizes.}
+  \item{text_size}{Font size of the plot text, default is 5.}
+  \item{title_size}{Font size of the plot title, default is 17.}
+  \item{ease_default}{Default aes easing function. See \code{\link[tweenr:display_ease]{tweenr::display_ease()}}
+for more options. The tidyexplain default value is \code{sine-in-out}.}
+  \item{ease_other}{Additional aes easing options, specified as a named list.
+List entries are named with the aesthetic to which the easeing should be
+applied, consistent with \code{\link[gganimate:ease_aes]{gganimate::ease_aes()}}. E.g. \code{list(color = "sine")}.}
+  \item{enter}{Enter fading function applied to objects in the animation. See
+\link[gganimate:enter_exit]{gganimate::enter_exit} for a complete list of options. The tidyexplain
+default is \code{\link[gganimate:enter_fade]{gganimate::enter_fade()}}.}
+  \item{exit}{Exit fading function applied to objects in the animation. See
+\link[gganimate:enter_exit]{gganimate::enter_exit} for a complete list of options. The tidyexplain
+default is \code{\link[gganimate:exit_fade]{gganimate::exit_fade()}}.}
+  \item{transition_length}{The relative length of the transition. Will be
+recycled to match the number of states in the data}
+  \item{state_length}{The relative length of the pause at the states. Will be
+recycled to match the number of states in the data}
+}}
 
-\item{title_family}{the font for the title}
-
-\item{text_size}{the size of the text}
-
-\item{title_size}{the size of the title}
-
-\item{...}{further arguments}
+\item{anim_opts}{Animation options generated with \code{\link[=anim_options]{anim_options()}}. Overrides
+any options set in \code{...}.}
 }
 \value{
 a ggplot

tests/testthat/test-anim_options.R

@@ -0,0 +1,49 @@
+context("test-anim_options")
+
+test_that("merging of animation options works", {
+  ao_new <- anim_options(5, 3, text_size = 9, title_size = 13)
+  ao_old <- anim_options(ease_default = "cubic-in", text_family = "Times New Roman")
+  ao_merged <- anim_options(5, 3, "cubic-in", text_size = 9, title_size = 13, text_family = "Times New Roman")
+  expect_equal(merge(ao_new, ao_old), ao_merged)
+})
+
+test_that("setting and getting animation options works", {
+  set_font_size(5, 10)
+  expect_equal(get_anim_opt(), anim_options(text_size = 5, title_size = 10))
+  expect_error(get_anim_opt("text_size"))
+  expect_equal(get_text_size(), get_anim_opt()$text_size)
+  expect_equal(get_title_size(), get_anim_opt()$title_size)
+
+  anim_options_set(anim_options(2, 1))
+  expect_equal(get_anim_opt("transition_length"), 2)
+  expect_equal(get_anim_opt("state_length"), 1)
+  expect_equal(get_anim_opt(), anim_options(2, 1, text_size = 5, title_size = 10))
+
+  anim_options_set()
+  expect_equal(get_anim_opt("transition_length"), plot_settings$default$transition_length)
+
+  anim_options_set(anim_options(enter = enter_appear(early = TRUE)))
+  expect_equal(names(get_anim_opt("enter")), "enter_appear(early = TRUE)")
+  expect_s3_class(get_anim_opt("enter")[[1]], "ggproto")
+
+  anim_options_set()
+})
+
+test_that("precedence: function > user-set global > default (> global default)", {
+  ao_function <- anim_options(ease_default = "linear")
+  ao_global <- anim_options(ease_default = "cubic", text_family = "Arial")
+  expect_equal(default_anim_opts("gather", ao_function)$ease_default, "linear")
+
+  anim_options_set(ao_global)
+  expect_equal(default_anim_opts("gather")$ease_default, "cubic")
+  expect_equal(default_anim_opts("gather", ao_function)$ease_default, "linear")
+
+  ao_default <- default_anim_opts("gather", ao_function) # inside animate_ function
+  ao_final <- validate_anim_opts(ao_default)             # just before animate_plot() or static_plot()
+  expect_equal(ao_final$ease_default, "linear")
+  expect_equal(ao_final$text_family, "Arial")
+  expect_equivalent(names(ao_final$ease_other), c("y", "x"))
+  expect_equal(ao_final$title_family, plot_settings$default$title_family)
+
+  anim_options_set()
+})