Bug fixes to page_fill across cyto_plot() function family.

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: CytoExploreR
 Type: Package
 Title: Interactive Analysis of Cytometry Data
-Version: 2.0.6
-Date: 2024-04-10
+Version: 2.0.7
+Date: 2024-06-04
 Authors@R: c(
   person("Dillon", "Hammill", role = c("aut", "cre"), email = "[email protected]"),
   person("Greg", "Finak", role = "ctb", email = "[email protected]"),
@@ -58,7 +58,7 @@ biocViews:
 License: GPL-2
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 VignetteBuilder: knitr
 Language: en-GB
 Config/testthat/edition: 3

NEWS.md

@@ -1,7 +1,11 @@
-# CytoExploreR 2.0.7 (pre-release)
+# CytoExploreR 2.0.8 (pre-release)
 
 * The behavior of `cyto_merge_by()` when `merge_by = NA` has changed from collapsing all samples to instead split samples individually. This is because splitting by `name` may not always work in cases where multiple samples share the same file names. This change requires updates to openCyto which should be re-installed when updating to the new version of CytoExploreR.
 
+# CytoExploreR 2.0.7
+
+* Bug fixes to handling of `page_fill` and `page_fill_alpha` within the `cyto_plot()` family of functions.
+
 # CytoExploreR 2.0.6
 
 * `cyto_plot_calibrate()` can now use the full instrument ranges for calibration through `type = "instrument"`.

R/cyto_plot.R

@@ -864,11 +864,11 @@ cyto_plot <- function(x,
     }
   }
 
-  # HEADER ARGUMENTS - REPEAT PER PAGE
-  header_args <- args[grepl("^header", names(args))]
-  for(i in names(header_args)) {
-    header_args[[i]] <- rep(
-      header_args[[i]], 
+  # PAGE ARGUMENTS - HEADER
+  page_args <- args[grepl("^header|^page_fill", names(args))]
+  for(i in names(page_args)) {
+    page_args[[i]] <- rep(
+      page_args[[i]], 
       length.out = if(!is.null(dim(args$layout))) {
         max(unique(unlist(args$layout)))
       }else {
@@ -879,10 +879,10 @@ cyto_plot <- function(x,
   }
 
   # UPDATE HEADER ARGUMENTS
-  .args_update(header_args)
+  .args_update(page_args)
 
   # REMOVE HEADER ARGUMENTS - CANNOT SPLIT LATER
-  args <- args[!names(args) %in% names(header_args)]
+  args <- args[!names(args) %in% names(page_args)]
 
   # KEY_SCALE 
   args$key_scale <- .cyto_plot_key_scale(
@@ -924,11 +924,15 @@ cyto_plot <- function(x,
     layout = args$layout,
     oma = oma,
     bg = adjustcolor(
-      args$page_fill,
-      args$page_fill_alpha
+      page_fill[1],
+      page_fill_alpha[1]
     )
   )
 
+  # DROP FIRST PAGE FILL ARGUMENTS
+  page_fill <- page_fill[-1]
+  page_fill_alpha <- page_fill_alpha[-1]
+
   # RESET LABEL MEMORY
   if(cyto_option("cyto_plot_method") == "cytoset" & 
      !cyto_option("cyto_plot_save") & !memory) {
@@ -1096,7 +1100,15 @@ cyto_plot <- function(x,
         p <- cyto_plot_record()
         # NEW DEVICE
         if(z < length(args)) {
-          cyto_plot_new() # USE GLOBAL SETTINGS
+          # TODO: which page is it on?
+          cyto_plot_new(
+            bg = adjustcolor(
+              page_fill[1],
+              page_fill_alpha[1]
+            )
+          ) # USE GLOBAL SETTINGS
+          page_fill <<- page_fill[-1]
+          page_fill_alpha <<- page_fill_alpha[-1]
         }
       } else {
         p <- NULL

R/cyto_plot_argument-handlers.R

@@ -139,6 +139,8 @@
       "header_text_size",
       "header_text_col",
       "key_scale", # prepared manually
+      "page_fill",
+      "page_fill_alpha",
       "..."
     )]
 
@@ -193,14 +195,12 @@
 
   layer_args <- c(
     arg_names[grepl("contour", arg_names)], # contour arguments
-    arg_names[grepl("hist_fill", arg_names)], # hist_fill arguments
+    arg_names[grepl("hist_fill",                               arg_names)], # hist_fill arguments
     arg_names[grepl("hist_line", arg_names)], # hist_line arguments
     arg_names[grepl("legend_", arg_names)], # legend aes arguments
     arg_names[grepl("point_", arg_names)], # point args
     "spectra_col",
-    "spectra_col_alpha",
-    "page_fill",
-    "page_fill_alpha"
+    "spectra_col_alpha"
   )
 
   # UPDATE ARG_NAMES

R/cyto_plot_compensation.R

@@ -76,6 +76,10 @@
 #'   to 1 by default.
 #' @param header_text_col colour to use for the header text, set to "black" by
 #'   default.
+#' @param page_fill colour to use to fill the page prior to adding plot panels,
+#'   set to \code{"white"} by default.
+#' @param page_fill_alpha numeric [0,1] to control the transparency of the page
+#'   colour, set to 1 by default to remove transparency.
 #' @param ... additional arguments passed to \code{\link{cyto_plot}}.
 #'
 #' @importFrom flowWorkspace cytoset
@@ -121,6 +125,8 @@ cyto_plot_compensation <- function(x,
                                    header_text_font = 2,
                                    header_text_size = 1,
                                    header_text_col = "black",
+                                   page_fill = "white",
+                                   page_fill_alpha = 1,
                                    ...) {
 
   # CYTO_PLOT_COMPLETE ---------------------------------------------------------
@@ -364,6 +370,10 @@ cyto_plot_compensation <- function(x,
   # TOTAL PLOTS
   tp <- n * length(channels)
 
+  # PAGE FILL
+  page_fill <- rep(page_fill, length.out = tpg)
+  page_fill_alpha <- rep(page_fill_alpha, length.out = tpg)
+
   # HEADER
   if(missing(header)) {
     header <- rep(
@@ -534,6 +544,13 @@ cyto_plot_compensation <- function(x,
                 cyto_plot_new_page()
                 # RECORD
                 rec <- cyto_plot_record()
+                # SET PAGE FILL
+                cyto_plot_par(
+                  bg = adjustcolor(
+                    page_fill[ind],
+                    page_fill_alpha[ind]
+                  )
+                )
               }
               return(rec)
             }

R/cyto_plot_explore.R

@@ -49,6 +49,10 @@
 #'   possible.
 #' @param title text to display above each plot, set to the name of the group or
 #'   channels displayed in the plot by default.
+#' @param page_fill colour to use to fill the page prior to adding plot panels,
+#'   set to \code{"white"} by default.
+#' @param page_fill_alpha numeric [0,1] to control the transparency of the page
+#'   colour, set to 1 by default to remove transparency.
 #' @param ... additional arguments passed to \code{\link{cyto_plot}}.
 #'
 #' @return list of recorded plots.
@@ -104,6 +108,8 @@ cyto_plot_explore <- function(x,
                               axes_trans = NA,
                               header,
                               title,
+                              page_fill = "white",
+                              page_fill_alpha = 1,
                               ...) {
 
   # TODO: REMOVE EXCESS ARGUMENTS - PASS THROUGH ... TO .CYTO_PLOT_DATA()
@@ -213,6 +219,10 @@ cyto_plot_explore <- function(x,
     tp <- n * length(x)
   }
 
+  # PREPARE PAGE_FILL ARGUMENTS
+  page_fill <- rep(page_fill, length.out = tpg)
+  page_fill_alpha <- rep(page_fill_alpha, length.out = tpg)
+
   # PREPARE HEADERS
   if(missing(header)) {
     # CHANNEL ORDER
@@ -358,6 +368,8 @@ cyto_plot_explore <- function(x,
                       } else {
                         FALSE
                       },
+                      page_fill = page_fill[cnt + ceiling(w/np)],
+                      page_fill_alpha = page_fill_alpha[cnt + ceiling(w/np)],
                       ...
                     )
                   }
@@ -419,6 +431,8 @@ cyto_plot_explore <- function(x,
                         } else {
                           FALSE
                         },
+                        page_fill = page_fill[cnt + ceiling(v/np)],
+                        page_fill_alpha = page_fill_alpha[cnt + ceiling(v/np)],
                         ...
                       )
                     }

R/cyto_plot_gating_scheme.R

@@ -73,6 +73,10 @@
 #' @param gate_line_col colour(s) to use for gates, set to \code{"red"} by
 #'   default. Setting \code{gate_line_col = NA} will automatically match the
 #'   gate colour with node colour.
+#' @param page_fill colour to use to fill the page prior to adding plot panels,
+#'   set to \code{"white"} by default.
+#' @param page_fill_alpha numeric [0,1] to control the transparency of the page
+#'   colour, set to 1 by default to remove transparency.
 #' @param ... additional arguments passed to \code{cyto_plot()}.
 #'
 #' @importFrom flowWorkspace gh_pop_is_hidden
@@ -109,6 +113,8 @@ cyto_plot_gating_scheme <- function(x,
                                     header_text_col = "black",
                                     legend_text_font = 1,
                                     legend_text_size = 1.2,
+                                    page_fill = "white",
+                                    page_fill_alpha = 1,
                                     ...) {
 
   # CYTO_PLOT_COMPLETE ---------------------------------------------------------
@@ -481,6 +487,10 @@ cyto_plot_gating_scheme <- function(x,
     tp <- n * length(x_list)
   }
 
+  # PREPARE PAGE_FILL ARGUMENTS
+  page_fill <- rep(page_fill, length.out = tpg)
+  page_fill_alpha <- rep(page_fill_alpha, length.out = tpg)
+
   # DEFAULT HEADERS 
   if(missing(header)) {
     # SEPARATE GATING SCHEMES
@@ -773,6 +783,13 @@ cyto_plot_gating_scheme <- function(x,
                   cyto_plot_new_page()
                   # RECORD
                   rec <- cyto_plot_record()
+                  # PAGE FILL
+                  cyto_plot_par(
+                    bg = adjustcolor(
+                      page_fill[ind],
+                      page_fill_alpha[ind]
+                    )
+                  )
                 }
                 return(rec)
               }
@@ -967,6 +984,13 @@ cyto_plot_gating_scheme <- function(x,
                   cyto_plot_new_page()
                   # RECORD
                   rec <- cyto_plot_record()
+                  # PAGE FILL
+                  cyto_plot_par(
+                    bg = adjustcolor(
+                      page_fill[ind],
+                      page_fill_alpha[ind]
+                    )
+                  )
                 }
                 return(rec)
               }

R/cyto_plot_map.R

@@ -65,6 +65,10 @@
 #'   applied to the data prior to plotting. The transformerList is used
 #'   internally to ensure that the axes on the constructed plots are
 #'   appropriately labelled.
+#' @param page_fill colour to use to fill the page prior to adding plot panels,
+#'   set to \code{"white"} by default.
+#' @param page_fill_alpha numeric [0,1] to control the transparency of the page
+#'   colour, set to 1 by default to remove transparency.
 #' @param ... additional arguments passed to \code{\link{cyto_plot}}.
 #'
 #' @author Dillon Hammill ([email protected])
@@ -150,6 +154,8 @@ cyto_plot_map <- function(x,
                           header,
                           title,
                           axes_trans = NA,
+                          page_fill = "white",
+                          page_fill_alpha = 1,
                           ...) {
 
   # TODO: ADD SUPPORT FOR ALIAS
@@ -306,6 +312,10 @@ cyto_plot_map <- function(x,
     tp <- n * length(x)
   }
 
+  # PREPARE PAGE_FILL ARGUMENTS
+  page_fill <- rep(page_fill, length.out = tpg)
+  page_fill_alpha <- rep(page_fill_alpha, length.out = tpg)
+
   # DEFAULT HEADERS
   if(missing(header)) {
     # CHANNEL ORDER - GROUPS AS HEADERS
@@ -412,6 +422,8 @@ cyto_plot_map <- function(x,
                    },
                    point_col = point_col[w],
                    point_col_scale = point_col_scale[[w]],
+                   page_fill = page_fill[cnt + ceiling(w/np)],
+                   page_fill_alpha = page_fill_alpha[cnt + ceiling(w/np)],
                    ...
                  )
                }
@@ -456,6 +468,8 @@ cyto_plot_map <- function(x,
                   },
                   point_col = point_col[z],
                   point_col_scale = point_col_scale[[z]],
+                  page_fill = page_fill[cnt + ceiling(w/np)],
+                  page_fill_alpha = page_fill_alpha[cnt + ceiling(w/np)],
                   ...
                 )
               }

R/cyto_plot_profile.R

@@ -47,6 +47,10 @@
 #'   users can supply a vector of headers for each page, this can be tricky to
 #'   get right so it is recommended for users to use the default headers where
 #'   possible.
+#' @param page_fill colour to use to fill the page prior to adding plot panels,
+#'   set to \code{"white"} by default.
+#' @param page_fill_alpha numeric [0,1] to control the transparency of the page
+#'   colour, set to 1 by default to remove transparency.
 #' @param ... additional arguments passed to \code{\link{cyto_plot}}.
 #'
 #' @return list of recorded plots.
@@ -96,6 +100,8 @@ cyto_plot_profile <- function(x,
                               hist_stack = 0,
                               axes_trans = NA,
                               header,
+                              page_fill = "white",
+                              page_fill_alpha = 1,
                               ...) {
 
   # TODO: REMOVE EXCES ARGUMENTS - PASS THROUGH ... TO .CYTO_PLOT_DATA()
@@ -182,6 +188,10 @@ cyto_plot_profile <- function(x,
     tp <- n * length(x)
   }
 
+  # PREPARE PAGE_FILL ARGUMENTS
+  page_fill <- rep(page_fill, length.out = tpg)
+  page_fill_alpha <- rep(page_fill_alpha, length.out = tpg)
+
   # PREPARE HEADERS
   if(missing(header)) {
     # CHANNEL ORDER
@@ -274,6 +284,8 @@ cyto_plot_profile <- function(x,
               } else {
                 FALSE
               },
+              page_fill = page_fill[cnt + ceiling(w/np)],
+              page_fill_alpha = page_fill_alpha[cnt + ceiling(w/np)],
               ...
             )
           }
@@ -315,6 +327,8 @@ cyto_plot_profile <- function(x,
               } else {
                 FALSE
               },
+              page_fill = page_fill[cnt + ceiling(w/np)],
+              page_fill_alpha = page_fill_alpha[cnt + ceiling(w/np)],
               ...
             )
           }