Merge pull request #220 from samuel-marsh/release/3.0.1

Release 3.0.1

Author: samuel-marsh

DESCRIPTION

@@ -2,8 +2,8 @@ Package: scCustomize
 Type: Package
 Title: Custom Visualizations & Functions for Streamlined Analyses of Single Cell Sequencing
 Description: Collection of functions created and/or curated to aid in the visualization and analysis of single-cell data using 'R'.  'scCustomize' aims to provide 1) Customized visualizations for aid in ease of use and to create more aesthetic and functional visuals. 2) Improve speed/reproducibility of common tasks/pieces of code in scRNA-seq analysis with a single or group of functions.  For citation please use: Marsh SE (2021) "Custom Visualizations & Functions for Streamlined Analyses of Single Cell Sequencing" <doi:10.5281/zenodo.5706430> RRID:SCR_024675.
-Version: 3.0.0
-Date: 2024-12-05
+Version: 3.0.1
+Date: 2024-12-18
 Authors@R: c(
     person(given = "Samuel", family = "Marsh", email = "samuel.marsh@childrens.harvard.edu", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-3012-6945")),
     person(given = "Ming", family = "Tang", role = c("ctb"), email = "tangming2005@gmail.com"),

NEWS.md

@@ -1,3 +1,20 @@
+# scCustomize 3.0.1 (2024-12-18)  
+## Added  
+- Added new parameters `output_width` and `output_height` to the `Iterate_*` family of plotting functions ([#217](https://github.com/samuel-marsh/scCustomize/issues/217)).  
+  
+  
+## Changed  
+    
+
+## Fixes  
+- Fixed bug in `Random_Cells_Downsample` that prevented setting identity using the `group.by` parameter.  
+- Fixed bug in `Cell_Highlight_Plot` that didn't pass the reduction parameter properly ([#216](https://github.com/samuel-marsh/scCustomize/issues/216)).  
+- Fixed bug when retrieving ensembl IDs for IEGs.  
+- Fixed bug that prevented using `return_plots` in iterative plotting functions([#217](https://github.com/samuel-marsh/scCustomize/issues/217)).  
+
+
+
+
 # scCustomize 3.0.0 (2024-12-05)  
 ## Added  
 **Major Updates to Functionality with rliger Package:**  

R/Internal_Utilities.R

@@ -47,7 +47,7 @@
 
 
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-#################### Object Checks ####################
+#################### Object/Feature Checks ####################
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
@@ -188,8 +188,68 @@ Assay5_Check <- function(
 }
 
 
+#' Perform Feature and Meta Checks before plotting
+#'
+#' Wraps the `Feature_Present`, `Meta_Present`, `Reduction_Loading_Present`, and `Case_Check` into
+#' single function to perform feature checks before plotting.
+#'
+#' @param object Seurat object
+#' @param features vector of features and/or meta data variables to plot.
+#' @param assay Assay to use (default all assays present).
+#'
+#' @return vector of features and/or meta data that were found in object.
+#'
+#' @noRd
+#'
+#' @keywords internal
+#'
+
+Feature_PreCheck <- function(
+    object,
+    features,
+    assay = NULL
+) {
+  # set assay (if null set to active assay)
+  assay <- assay %||% Assays(object = object)
+
+  # Check features and meta to determine which features present
+  features_list <- Feature_Present(data = object, features = features, omit_warn = FALSE, print_msg = FALSE, case_check_msg = FALSE, return_none = TRUE, seurat_assay = assay)
+
+  meta_list <- Meta_Present(object = object, meta_col_names = features_list[[2]], omit_warn = FALSE, print_msg = FALSE, return_none = TRUE)
+
+  reduction_list <- Reduction_Loading_Present(seurat_object = object, reduction_names = meta_list[[2]], omit_warn = FALSE, print_msg = FALSE, return_none = TRUE)
+
+  all_not_found_features <- reduction_list[[2]]
+
+  all_found_features <- c(features_list[[1]], meta_list[[1]], reduction_list[[1]])
+
+  # Stop if no features found
+  if (length(x = all_found_features) < 1) {
+    cli_abort(message = c("No features were found.",
+                          "*" = "The following are not present in object:",
+                          "i" = "{.field {glue_collapse_scCustom(input_string = all_not_found_features, and = TRUE)}}")
+    )
+  }
+
+  # Return message of features not found
+  if (length(x = all_not_found_features) > 0) {
+    op <- options(warn = 1)
+    on.exit(options(op))
+    cli_warn(message = c("The following features were omitted as they were not found:",
+                         "i" = "{.field {glue_collapse_scCustom(input_string = all_not_found_features, and = TRUE)}}")
+    )
+  }
+
+  # Check feature case and message if found
+  Case_Check(seurat_object = object, gene_list = all_not_found_features, case_check_msg = TRUE, return_features = FALSE)
+
+  # return all found features
+  return(all_found_features)
+}
+
+
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-#################### WARN/ERROR MESSAGING ####################
+#################### FUNCTION HELPERS ####################
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
@@ -250,66 +310,6 @@ glue_collapse_scCustom <- function(
 }
 
 
-#' Perform Feature and Meta Checks before plotting
-#'
-#' Wraps the `Feature_Present`, `Meta_Present`, `Reduction_Loading_Present`, and `Case_Check` into
-#' single function to perform feature checks before plotting.
-#'
-#' @param object Seurat object
-#' @param features vector of features and/or meta data variables to plot.
-#' @param assay Assay to use (default all assays present).
-#'
-#' @return vector of features and/or meta data that were found in object.
-#'
-#' @noRd
-#'
-#' @keywords internal
-#'
-
-Feature_PreCheck <- function(
-    object,
-    features,
-    assay = NULL
-) {
-  # set assay (if null set to active assay)
-  assay <- assay %||% Assays(object = object)
-
-  # Check features and meta to determine which features present
-  features_list <- Feature_Present(data = object, features = features, omit_warn = FALSE, print_msg = FALSE, case_check_msg = FALSE, return_none = TRUE, seurat_assay = assay)
-
-  meta_list <- Meta_Present(object = object, meta_col_names = features_list[[2]], omit_warn = FALSE, print_msg = FALSE, return_none = TRUE)
-
-  reduction_list <- Reduction_Loading_Present(seurat_object = object, reduction_names = meta_list[[2]], omit_warn = FALSE, print_msg = FALSE, return_none = TRUE)
-
-  all_not_found_features <- reduction_list[[2]]
-
-  all_found_features <- c(features_list[[1]], meta_list[[1]], reduction_list[[1]])
-
-  # Stop if no features found
-  if (length(x = all_found_features) < 1) {
-    cli_abort(message = c("No features were found.",
-                          "*" = "The following are not present in object:",
-                          "i" = "{.field {glue_collapse_scCustom(input_string = all_not_found_features, and = TRUE)}}")
-    )
-  }
-
-  # Return message of features not found
-  if (length(x = all_not_found_features) > 0) {
-    op <- options(warn = 1)
-    on.exit(options(op))
-    cli_warn(message = c("The following features were omitted as they were not found:",
-                         "i" = "{.field {glue_collapse_scCustom(input_string = all_not_found_features, and = TRUE)}}")
-    )
-  }
-
-  # Check feature case and message if found
-  Case_Check(seurat_object = object, gene_list = all_not_found_features, case_check_msg = TRUE, return_features = FALSE)
-
-  # return all found features
-  return(all_found_features)
-}
-
-
 #' Ask yes/no question to proceed
 #'
 #' Asks the user to answer yes/no question and returns logical value depending on
@@ -337,6 +337,37 @@ yesno <- function(msg, .envir = parent.frame()) {
 }
 
 
+#' Change function parameter value from NULL to NA
+#'
+#' Provides method to change parameter value dynamically within function to suit defaults of other functions.
+#' Used in iterative plotting functions.
+#'
+#' @param parameter the parameter to check for NULL
+#'
+#' @return if NULL returns NA otherwise returns input value.
+#'
+#'
+#' @import cli
+#'
+#' @noRd
+#'
+
+replace_null <- function(
+    parameter
+) {
+  # check length
+  if (length(x = parameter) > 1) {
+    cli_abort(message = "{.code parameter} must be single value.")
+  }
+
+  # check NULL and swap NA
+  if (is.null(x = parameter)) {
+    parameter <- NA
+  }
+  return(parameter)
+}
+
+
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 #################### QC HELPERS ####################
 #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -827,7 +858,7 @@ Retrieve_IEG_Ensembl_Lists <- function(
 
   # pull lists
   qc_gene_list <- list(
-    ieg = ieg_gene_list[[ieg]]
+    ieg = ensembl_ieg_list[[ieg]]
   )
 
   return(qc_gene_list)

R/Object_Utilities.R

@@ -474,7 +474,7 @@ Fetch_Meta.Seurat <- function(
 #' @param num_cells number of cells per ident to use in down-sampling.  This value must be less than or
 #' equal to the size of ident with fewest cells.  Alternatively, can set to "min" which will
 #' use the maximum number of barcodes based on size of smallest group.
-#' @param group.by The ident to use to group cells.  Default is "ident" which use current active.ident.  .
+#' @param group.by The ident to use to group cells.  Default is NULL which use current active.ident.  .
 #' @param return_list logical, whether or not to return the results as list instead of vector, default is
 #' FALSE.
 #' @param allow_lower logical, if number of cells in identity is lower than `num_cells` keep the
@@ -513,7 +513,7 @@ Fetch_Meta.Seurat <- function(
 Random_Cells_Downsample <- function(
     seurat_object,
     num_cells,
-    group.by = "ident",
+    group.by = NULL,
     return_list = FALSE,
     allow_lower = FALSE,
     seed = 123
@@ -522,7 +522,7 @@ Random_Cells_Downsample <- function(
   Is_Seurat(seurat_object = seurat_object)
 
   # set ident in case of NULL
-  group.by <- "ident" %||% group.by
+  group.by <- group.by %||% "ident"
 
   # Check and set idents if not "ident"
   if (group.by != "ident") {
@@ -536,7 +536,7 @@ Random_Cells_Downsample <- function(
     rownames_to_column("barcodes")
 
   # get unique ident vector
-  idents_all <- as.character(levels(x = Idents(object = seurat_object)))
+  idents_all <- as.character(x = levels(x = Idents(object = seurat_object)))
 
   # Find minimum length ident and warn if num_cells not equal or lower
   min_cells <- CellsByIdentities(object = seurat_object)
@@ -574,7 +574,7 @@ Random_Cells_Downsample <- function(
   # set seed and select random cells per ident
   set.seed(seed = seed)
 
-  random_cells <- lapply(1:length(idents_all), function(x) {
+  random_cells <- lapply(1:length(x = idents_all), function(x) {
     clus_barcodes <- cluster_barcodes %>%
       filter(.data[["ident"]] == idents_all[x]) %>%
       column_to_rownames("barcodes") %>%

R/Plotting_Seurat.R

@@ -1688,6 +1688,7 @@ Cell_Highlight_Plot <- function(
                            split.by = split.by,
                            split_seurat = split_seurat,
                            label = label,
+                           reduction = reduction,
                            ...)
 
   # Edit plot legend
@@ -1710,9 +1711,6 @@ Cell_Highlight_Plot <- function(
 }
 
 
-
-
-
 #' DimPlot with modified default settings
 #'
 #' Creates DimPlot with some of the settings modified from their Seurat defaults (colors_use, shuffle, label).