added first_plot arg to afex_plot()

singmann · Apr 7, 2024 · cb8289e · cb8289e
1 parent e3f5d6b
commit cb8289e
Show file tree

Hide file tree

Showing 12 changed files with 683 additions and 3 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -76,6 +76,6 @@ Authors@R: c(person(given="Henrik", family="Singmann", role=c("aut", "cre"),
          person(given="Jonathon", family="Love", role=c("ctb")), 
          person(given="Russell", family="Lenth", role=c("ctb")), 
          person(given="Rune", family="Haubo Bojesen Christensen", role=c("ctb")))
-Version: 1.3-1
+Version: 1.4-0
 RoxygenNote: 7.3.1
 LazyData: true
diff --git a/NEWS b/NEWS
@@ -1,3 +1,11 @@
+Changes in afex Version 1.4-x (2024-xx-xx)
+
+Significant User Visible Changes and New Features
+ o  Added plot_first argument to afex_plot(), which allows passing ggplot2 geom's which will be plotted first, before any other graphical elements. This allows plotting reference lines in the background of the plot, e.g. using geom_hline().
+
+Bugfixes
+ o 
+
 Changes in afex Version 1.3-1 (2024-02-25)
 
 Bugfixes

diff --git a/R/afex_plot.R b/R/afex_plot.R
@@ -108,6 +108,10 @@
 #'   emits a \code{message} with \code{old -> new} factor levels.
 #' @param legend_title A scalar \code{character} vector with a new title for the
 #'   legend.
+#' @param plot_first A \code{ggplot2} geom (or a list of geoms) that will be
+#'   added to the returned plot as a first element (i.e., before any of the
+#'   other graphical elements). Useful for adding reference lines or similar
+#'   (e.g., using \code{\link[ggplot2]{geom_hline}}).
 #' @param data For the \code{afex_plot.default} method, an optional
 #'   \code{data.frame} containing the raw data used for fitting the model and
 #'   which will be used as basis for the data points in the background. If
@@ -118,7 +122,7 @@
 #' @param within_vars,between_vars For the \code{afex_plot.default} method, an
 #'   optional \code{character} vector specifying which variables should be
 #'   treated as within-subjects (or repeated-measures) factors and which as
-#'   between-subjects (or independen-sampels) factors. If one of the two
+#'   between-subjects (or independent-samples) factors. If one of the two
 #'   arguments is given, all other factors are assumed to fall into the other
 #'   category.
 #' @param means \code{data.frame}s used for plotting of the plotting
@@ -307,6 +311,7 @@ afex_plot.afex_aov <- function(object,
                                dodge = 0.5,
                                return = "plot",
                                factor_levels = list(),
+                               plot_first = NULL,
                                legend_title,
                                ...) {
 
@@ -404,6 +409,7 @@ afex_plot.afex_aov <- function(object,
                             line_arg = line_arg,
                             mapping = mapping,
                             legend_title =  legend_title,
+                            plot_first = plot_first,
                             return = return
   ))
 }
@@ -434,6 +440,7 @@ afex_plot.mixed <- function(object,
                             dodge = 0.5,
                             return = "plot",
                             factor_levels = list(),
+                            plot_first = NULL,
                             legend_title,
                             ...) {
 
@@ -537,6 +544,7 @@ afex_plot.mixed <- function(object,
                             line_arg = line_arg,
                             mapping = mapping,
                             legend_title =  legend_title,
+                            plot_first = plot_first,
                             return = return
   ))
 }
@@ -566,6 +574,7 @@ afex_plot.merMod <- function(object,
                             dodge = 0.5,
                             return = "plot",
                             factor_levels = list(),
+                            plot_first = NULL,
                             legend_title,
                             ...) {
 
@@ -668,6 +677,7 @@ afex_plot.merMod <- function(object,
                             line_arg = line_arg,
                             mapping = mapping,
                             legend_title =  legend_title,
+                            plot_first = plot_first,
                             return = return
   ))
 }
@@ -699,6 +709,7 @@ afex_plot.default <- function(object,
                               dodge = 0.5,
                               return = "plot",
                               factor_levels = list(),
+                              plot_first = NULL,
                               legend_title,
                               ...) {
 
@@ -829,6 +840,7 @@ afex_plot.default <- function(object,
                             line_arg = line_arg,
                             mapping = mapping,
                             legend_title =  legend_title,
+                            plot_first = plot_first,
                             return = return
   ))
 }

diff --git a/R/afex_plot_plotting_functions.R b/R/afex_plot_plotting_functions.R
@@ -14,6 +14,7 @@ interaction_plot <- function(means,
                              point_arg = list(),
                              line_arg = list(),
                              dodge = 0.5, 
+                             plot_first = NULL,
                              legend_title,
                              col_x = "x",
                              col_y = "y",
@@ -46,6 +47,15 @@ interaction_plot <- function(means,
                                   x = col_x, 
                                   group = col_trace),
                                   tmp_list)))
+  if (!is.null(plot_first)) {
+    if (is.list(plot_first)) {
+      for (i in seq_along(plot_first)) {
+        plot_out <- plot_out + plot_first[[i]]
+      }
+    } else {
+      plot_out <- plot_out + plot_first
+    }
+  }
 
   if (data_plot) {
     if (missing(data_geom)) {
@@ -232,6 +242,7 @@ oneway_plot <- function(means,
                         data_color = "darkgrey",
                         data_arg = list(),
                         point_arg = list(),
+                        plot_first = NULL,
                         legend_title,
                         col_x = "x",
                         col_y = "y",
@@ -267,6 +278,16 @@ oneway_plot <- function(means,
                                   group = col_x),
                                   tmp_list)))
 
+  if (!is.null(plot_first)) {
+    if (is.list(plot_first)) {
+      for (i in seq_along(plot_first)) {
+        plot_out <- plot_out + plot_first[[i]]
+      }
+    } else {
+      plot_out <- plot_out + plot_first
+    }
+  }
+
 
   if (data_plot) {
     if (missing(data_geom)) {

diff --git a/R/afex_plot_utils.R b/R/afex_plot_utils.R
@@ -16,6 +16,7 @@ afex_plot_internal <- function(x,
                                line_arg,
                                mapping,
                                legend_title,
+                               plot_first,
                                return) {
 
   if (length(trace) > 0) {
@@ -38,6 +39,7 @@ afex_plot_internal <- function(x,
                               point_arg = point_arg,
                               line_arg = line_arg,
                               mapping = mapping,
+                              plot_first = plot_first,
                               legend_title =  if (missing(legend_title)) 
                                 paste(trace, sep = "\n") else
                                   legend_title
@@ -58,6 +60,7 @@ afex_plot_internal <- function(x,
                          data_arg = data_arg,
                          point_arg = point_arg,
                          mapping = mapping,
+                         plot_first = plot_first,
                          legend_title = if (missing(legend_title)) 
                            paste(x, sep = "\n") else
                              legend_title

diff --git a/examples/examples.afex_plot.R b/examples/examples.afex_plot.R
@@ -232,6 +232,11 @@ afex_plot(aw, x = "noise", trace = "angle",
 afex_plot(aw, x = "noise", trace = "angle", 
           legend_title = "Noise Condition")
 
+## Add reference line in the background
+afex_plot(aw, x = "noise", trace = "angle", 
+          plot_first = ggplot2::geom_hline(yintercept = 450, 
+                                            colour = "darkgrey"))
+
 ## for plots with few factor levels, smaller dodge might be better:
 afex_plot(aw, x = "angle", trace = "noise", dodge = 0.25) 
 

diff --git a/man/afex_plot.Rd b/man/afex_plot.Rd