Merge pull request #141 from samuel-marsh/release/2.0.0

Release/2.0.0

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>.
-Version: 1.1.3
-Date: 2023-07-19
+Version: 2.0.0
+Date: 2023-11-13
 Authors@R: c(
     person(given = "Samuel", family = "Marsh", email = "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-3012-6945")),
     person(given = "Ming", family = "Tang", role = c("ctb"), email = "[email protected]"),
@@ -13,7 +13,7 @@ Authors@R: c(
 URL: https://github.com/samuel-marsh/scCustomize, https://samuel-marsh.github.io/scCustomize/, https://doi.org/10.5281/zenodo.5706431
 BugReports: https://github.com/samuel-marsh/scCustomize/issues
 Depends: R (>= 4.0.0),
-         Seurat (>= 4.3.0)
+         Seurat (>= 4.3.0.1)
 Imports: 
     circlize,
     cli (>= 3.2.0),
@@ -40,8 +40,8 @@ Imports:
     purrr,
     rlang (>= 1.0.1),
     scales,
-    scattermore (>= 0.7), 
-    SeuratObject (>= 4.1.2),
+    scattermore (>= 1.2), 
+    SeuratObject (>= 5.0.0),
     stats,
     stringi,
     stringr,
@@ -58,8 +58,8 @@ Suggests:
     remotes,
     rliger,
     rmarkdown,
+    scuttle,
     tidyselect,
-    tidyverse, 
     qs,
     viridis
 License: GPL (>= 3)

NAMESPACE

@@ -5,10 +5,13 @@ S3method(Fetch_Meta,liger)
 export(Add_CellBender_Diff)
 export(Add_Cell_Complexity_LIGER)
 export(Add_Cell_Complexity_Seurat)
+export(Add_Cell_QC_Metrics)
 export(Add_Mito_Ribo_LIGER)
 export(Add_Mito_Ribo_Seurat)
 export(Add_Pct_Diff)
 export(Add_Sample_Meta)
+export(Add_Top_Gene_Pct_Seurat)
+export(Barcode_Plot)
 export(Blank_Theme)
 export(Case_Check)
 export(CellBender_Diff_Plot)
@@ -38,9 +41,11 @@ export(Extract_Sample_Meta)
 export(Extract_Top_Markers)
 export(FeaturePlot_DualAssay)
 export(FeaturePlot_scCustom)
+export(FeatureScatter_scCustom)
 export(Fetch_Meta)
 export(Gene_Present)
 export(Hue_Pal)
+export(Iterate_Barcode_Rank_Plot)
 export(Iterate_Cluster_Highlight_Plot)
 export(Iterate_DimPlot_bySample)
 export(Iterate_FeaturePlot_scCustom)
@@ -51,6 +56,7 @@ export(Iterate_Plot_Density_Joint)
 export(Iterate_VlnPlot_scCustom)
 export(JCO_Four)
 export(Liger_to_Seurat)
+export(MAD_Stats)
 export(Median_Stats)
 export(Merge_Seurat_List)
 export(Merge_Sparse_Data_All)
@@ -74,6 +80,7 @@ export(Plot_Median_Other)
 export(Plot_Median_UMIs)
 export(Pull_Cluster_Annotation)
 export(Pull_Directory_List)
+export(QC_Histogram)
 export(QC_Plot_GenevsFeature)
 export(QC_Plot_UMIvsFeature)
 export(QC_Plot_UMIvsGene)
@@ -156,7 +163,10 @@ importFrom(Seurat,VariableFeaturePlot)
 importFrom(Seurat,VizDimLoadings)
 importFrom(Seurat,VlnPlot)
 importFrom(SeuratObject,DefaultDimReduc)
-importFrom(SeuratObject,PackageCheck)
+importFrom(SeuratObject,Features)
+importFrom(SeuratObject,JoinLayers)
+importFrom(SeuratObject,LayerData)
+importFrom(SeuratObject,Layers)
 importFrom(circlize,colorRamp2)
 importFrom(cowplot,theme_cowplot)
 importFrom(data.table,fread)
@@ -176,6 +186,7 @@ importFrom(dplyr,n)
 importFrom(dplyr,pull)
 importFrom(dplyr,rename)
 importFrom(dplyr,select)
+importFrom(dplyr,setdiff)
 importFrom(dplyr,slice)
 importFrom(dplyr,slice_max)
 importFrom(dplyr,summarise)
@@ -212,15 +223,16 @@ importFrom(purrr,keep)
 importFrom(purrr,map)
 importFrom(purrr,map2)
 importFrom(purrr,map_dbl)
-importFrom(purrr,pluck)
 importFrom(purrr,reduce)
+importFrom(rlang,is_installed)
 importFrom(rlang,sym)
 importFrom(scales,alpha)
 importFrom(scales,hue_pal)
 importFrom(scales,label_percent)
 importFrom(scattermore,geom_scattermore)
 importFrom(stats,cor)
 importFrom(stats,kmeans)
+importFrom(stats,mad)
 importFrom(stats,median)
 importFrom(stats,quantile)
 importFrom(stats,setNames)

NEWS.md

@@ -1,3 +1,65 @@
+# scCustomize 2.0.0 (2023-11-13)  
+## Added  
+- Added support for metrics produced by Cell Ranger `multi` pipeline to `Read10X_Metrics` via new parameter `cellranger_multi`.
+- Added `dot_size` parameter to `Seq_QC_Plot_*` family of functions.  
+- Added two new sequencing QC functions to create and iterate barcode rank plots: `Barcode_Plot` and `Iterate_Barcode_Rank_Plot`.  
+- Added `ident_legend` parameter to `QC_Plot_UMIvsGene` to control show/hide of the identity legend ([#121](https://github.com/samuel-marsh/scCustomize/issues/121)).  
+- Added support for sparse matrix input in `CellBender_Feature_Diff`.  
+- Added `min_count_label` in `CellBender_Diff_Plot` to better control feature labeling.  
+- Allow specification of meta data column containing sample names/IDs in `Iterate_DimPlot_bySample` using new `sample_column` parameter.  
+- Added new function `MAD_Stats` to calculate to the median absolute deviation of meta.data columns by grouping variable and across entire object.  
+- Added new function `Add_Top_Gene_Pct_Seurat` to add another QC measure of cell complexity to object meta.data.  Returns percentage of counts occupied by top XX genes in each cell.  
+- Added ability to provide set of custom features to `VariableFeaturePlot_scCustom` using `custom_features` parameter.  
+- Added new overall cell QC metric function `Add_Cell_QC_Metrics` to simplify adding cell QC metrics.  Single function call to add Mito/Ribo Percentages, Cell Complexity, Top Gene Percentages, MSigDB Percentages, IEG Percentages, and/or Cell Cycle Scoring (human only).  
+- Added 2 new gene lists to package data for use in `Add_Cell_QC_Metrics` function: "msigdb_qc_gene_list" and "ieg_gene_list".
+- Added several internal functions to support new MsigDB and IEG capabilities of `Add_Cell_QC_Metrics`.  
+- Added new parameters `plot_median` and `plot_boxplot` to `VlnPlot_scCustom` (and `VlnPlot_scCustom`-based plots; e.g., `QC_Plot_*` family) for added visualization.  
+- Added `QC_Histogram` to plot QC features (or any feature) using simple histogram.  
+- Added `FeatureScatter_scCustom` function to customize Seurat's `FeatureScatter` plots.  
+- Added `figure_plot` parameter to all 2D DR (t-SNE, UMAP, etc) based plots ([#127](https://github.com/samuel-marsh/scCustomize/issues/127)).  
+
+
+## Changed  
+- Large scale under the hood code adjustments to ensure compatibility with Seurat V5 object structure.  
+- Internal code syntax updates independent of Seurat functionality.  
+- **HARD DEPRECATION** `Split_FeatureScatter` function has been completely deprecated and it's functionality has been moved to new `FeatureScatter_scCustom`.  
+- **SOFT DEPRECATION** The parameter `gene_list` in `Iterate_FeaturePlot_scCustom` and `Iterate_VlnPlot_scCustom` has been soft-deprecated and replaced by `features` parameter.  Specifying `gene_list` will display deprecation warning but continue to function until next major update.  
+- The above soft deprecation was to clarify that other features besides genes can be plotted and coincides with update to functions to allow for iterative plots of meta.data or reductions in addition to assay features ([#123](https://github.com/samuel-marsh/scCustomize/issues/123)).  
+- Internal rewrite of `Read10X_Metrics` to use new internal helper functions.  
+- Changed `Liger_to_Seurat` to transfer the liger_object@H slot in addition to H.norm slot already moved.  
+- Replaced `length(x = colnames(x = obj)` with `length(x = Cells(x = obj)` for accurate plotting based on V5 object structure.  
+- `Gene_Present` now accepts `assay` parameter.  
+- Internal reorganization of some functions within `R/` for better organization.  
+- Updated default scCustomize color palettes (`scCustomize_Palette`).  Now if number of colors is greater than 2 but less than 8 the default palette will be `ColorBlind_Pal` (previously it was "polychrome").  Polychrome remains the default when number of colors is between 9-36.  
+- Updated parameter default within `scCustomize_Palette` to `ggplot_default_colors = FALSE` to avoid uncessary error when no value supplied.  
+- Minimum version of scattermore package updated to v1.2.  
+- `DimPlot_scCustom` will now set `label = TRUE` if `label.box` is set to TRUE but `label` is not changed from default.  
+- Removed loading of full tidyverse in vignettes to remove from package suggests (lessen dependency installs when not completely needed).  
+- Replace Seurat `PackageCheck` (now deprecated), with `rlang::is_installed()` for non-dependency checks.  
+- Update vignettes with new features and bug fixes from old code.  
+
+
+## Fixes  
+- Fixed issue in `Read10X_Metrics` that caused errors when reading files on windows operating system ([#115](https://github.com/samuel-marsh/scCustomize/issues/115)).  
+- Fixed issue in `Create_CellBender_Merged_Seurat` when feature names are changed (underscore to dash) during object creation ([#118](https://github.com/samuel-marsh/scCustomize/issues/118)).  
+- Fixed error in `Read10X_h5_Mutli_Directory` when reading Cell Ranger `multi` directories.  
+- Added new checks to `VlnPlot_scCustom`, `DimPlot_scCustom`, and `DotPlot_scCustom` to avoid otherwise ambiguous error messages ([#120](https://github.com/samuel-marsh/scCustomize/issues/120)).  
+- Fixed internal check message accidentally user facing in `VlnPlot_scCustom` ([#122](https://github.com/samuel-marsh/scCustomize/issues/122)).  
+- Fixed cli warning in `Cell_Highlight_Plot` that could cause function to error without proper error message.  
+- Fixed handling of file names in `Read_*` functions to avoid unnecessary errors.  
+- Replace superseded dplyr syntax/functionality `drop_na(.data[[var]]`, with current dplyr syntax.  
+- Internal code fixes to accelerate plotting functions.  
+- Fixed default plot colors in `VlnPlot`-based plots when `split.by` is not NULL.  
+- Fixed error when trying to plot more than two variables with `group.by` when using `DimPlot_scCustom` ([#128](https://github.com/samuel-marsh/scCustomize/issues/128)).  
+- Fixed errors in parameter description for `Add_Mito_Ribo_Seurat` and `Add_Mito_Ribo_LIGER` which incorrectly stated the names of new meta.data/cell.data columns to be added.  
+- Fixed bug in `DotPlot_scCustom` that prevented it from working unless `group.by` parameter was explicitly added.  
+- Fixed bug in `Case_Check` caused by typo.  
+- Fixed color warning messages in `Cluster_Highlight_Plot` and `Meta_Highlight_Plot` that were too verbose.  
+- Fixed bug in `Add_Mito_Ribo_Seurat` and `Add_Mito_Ribo_LIGER` which caused error when supplying custom list of features for non-default organism ([#133](https://github.com/samuel-marsh/scCustomize/issues/133)).  
+- Fixed bug in `DimPlot_scCustom` preventing that errored when trying to split plot and use `figure_plot` at same time.  
+
+
+
 # scCustomize 1.1.3 (2023-07-19)  
 ## Added  
 - None.   

R/Color_Palettes.R

@@ -215,7 +215,7 @@ NavyAndOrange <- function(
   flip_order = FALSE
 ) {
   navy_orange <- c("navy", "orange")
-  if (flip_order) {
+  if (isTRUE(x = flip_order)) {
     navy_orange <- rev(x = navy_orange)
   }
   return(navy_orange)
@@ -376,7 +376,7 @@ varibow_scCustom <- function(
 #' @import cli
 # #' @importFrom colorway varibow (now directly ported for CRAN compatibility)
 #' @importFrom paletteer paletteer_d
-#' @importFrom SeuratObject PackageCheck
+#' @importFrom rlang is_installed
 #'
 #' @return A vector of colors
 #'
@@ -428,8 +428,8 @@ DiscretePalette_scCustomize <- function(
 
   # dittoseq check
   if (palette == "ditto_seq") {
-    dittoseq_check <- PackageCheck("dittoSeq", error = FALSE)
-    if (!dittoseq_check[1]) {
+    dittoseq_check <- is_installed(pkg = "dittoSeq")
+    if (isFALSE(x = dittoseq_check[1])) {
       cli_abort(message = c(
         "Please install the {.val dittoSeq} package to {.code palette = {symbol$dquote_left}ditto_seq{symbol$dquote_right}}",
         "i" = "This can be accomplished with the following commands:",
@@ -467,7 +467,7 @@ DiscretePalette_scCustomize <- function(
                           "i" = "Please adjust {.code num_colors} to be less than or equal to {.field {length(x = palette_out)}} or select a different {.code palette}.")
     )
   }
-  if (shuffle_pal) {
+  if (isTRUE(x = shuffle_pal)) {
     set.seed(seed = seed)
     palette_out <- sample(x = palette_out[1:num_colors])
   } else {
@@ -484,7 +484,8 @@ DiscretePalette_scCustomize <- function(
 #' @param num_groups number of groups to be plotted. If `ggplot_default_colors = FALSE` then by default:
 #' \itemize{
 #'       \item If number of levels plotted equal to 2 then colors will be `NavyAndOrange()`.
-#'       \item If If number of levels plotted greater than 2 but less than or equal to 36 it will use "polychrome" from `DiscretePalette_scCustomize`.
+#'       \item If number of levels plotted greater than 2 but less than or equal to 8 it will use `ColorBlind_Pal()`.
+#'       \item If number of levels plotted greater than 2 but less than or equal to 36 it will use "polychrome" from `DiscretePalette_scCustomize()`.
 #'       \item If greater than 36 will use "varibow" with shuffle = TRUE from `DiscretePalette_scCustomize`.
 #'       }
 #' @param ggplot_default_colors logical.  Whether to use default ggplot hue palette or not.
@@ -503,11 +504,11 @@ DiscretePalette_scCustomize <- function(
 
 scCustomize_Palette <- function(
   num_groups,
-  ggplot_default_colors,
+  ggplot_default_colors = FALSE,
   color_seed = 123
 ) {
   # Set color palette depending on group length
-  if (ggplot_default_colors) {
+  if (isTRUE(x = ggplot_default_colors)) {
     colors_use <- Hue_Pal(num_colors = num_groups)
   } else {
     if (num_groups == 1) {
@@ -516,7 +517,10 @@ scCustomize_Palette <- function(
     if (num_groups == 2) {
       colors_use <- NavyAndOrange()
     }
-    if (num_groups > 2 && num_groups <= 36) {
+    if (num_groups > 2 && num_groups <= 8) {
+      colors_use <- ColorBlind_Pal()
+    }
+    if (num_groups > 8 && num_groups <= 36) {
       colors_use <- DiscretePalette_scCustomize(num_colors = num_groups, palette = "polychrome")
     }
     if (num_groups > 36) {
@@ -585,7 +589,7 @@ PalettePlot <- function(
 
   # Plot
   # Label plot
-  if (label_color_num) {
+  if (isTRUE(x = label_color_num)) {
     palette_plot <- ggplot(palette_data) +
       geom_tile(aes(x = .data[["x"]], y = .data[["y"]], fill = .data[["fill"]])) +
       geom_text(aes(x = .data[["x"]], y = .data[["y"]], label = .data[["x"]])) +

R/Data.R

@@ -35,3 +35,56 @@
 #' @concept data
 #'
 "ensembl_ribo_id"
+
+
+#' QC Gene Lists
+#'
+#' Gene symbols for qc percentages from MSigDB database.  The gene sets are from 3 MSigDB lists:
+#' "HALLMARK_OXIDATIVE_PHOSPHORYLATION", "HALLMARK_APOPTOSIS", and "HALLMARK_DNA_REPAIR".
+#'
+#' @format A list of 18 vectors
+#' \describe{
+#'   \item{Homo_sapiens_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for human}
+#'   \item{Homo_sapiens_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for human}
+#'   \item{Homo_sapiens_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for human}
+#'   \item{Mus_musculus_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for mouse}
+#'   \item{Mus_musculus_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for mouse}
+#'   \item{Mus_musculus_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for mouse}
+#'   \item{Rattus_norvegicus_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for rat}
+#'   \item{Rattus_norvegicus_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for rat}
+#'   \item{Rattus_norvegicus_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for rat}
+#'   \item{Drosophila_melanogaster_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for fly}
+#'   \item{Drosophila_melanogaster_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for fly}
+#'   \item{Drosophila_melanogaster_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for fly}
+#'   \item{Dario_rerio_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for zebrafish}
+#'   \item{Dario_rerio_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for zebrafish}
+#'   \item{Dario_rerio_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for zebrafish}
+#'   \item{Macaca_mulatta_msigdb_oxphos}{Genes in msigdb "HALLMARK_OXIDATIVE_PHOSPHORYLATION" list for macaque}
+#'   \item{Macaca_mulatta_msigdb_apop}{Genes in msigdb "HALLMARK_APOPTOSIS" list for macaque}
+#'   \item{Macaca_mulatta_msigdb_dna_repair}{Genes in msigdb "HALLMARK_DNA_REPAIR" list for macaque}
+#'
+#' }
+#' @concept data
+#'
+#' @source MSigDB gene sets via msigdbr package \url{https://cran.r-project.org/package=msigdbr}
+#'
+"msigdb_qc_gene_list"
+
+
+#' Immediate Early Gene (IEG) gene lists
+#'
+#' Gene symbols for immediate early genes
+#'
+#' @format A list of seven vectors
+#' \describe{
+#'   \item{Mus_musculus_IEGs}{Gene symbols for IEGs from source publication (see below)}
+#'   \item{Homo_sapiens_IEGs}{Human gene symbols for homologous genes from mouse gene list}
+#'
+#' }
+#' @concept data
+#'
+#' @source Mouse gene list is from: SI Table 4 from \doi{10.1016/j.neuron.2017.09.026}.  Human
+#' gene list was compiled by first creating homologous gene list using biomaRt and then adding some manually curated
+#' homologs according to HGNC.
+#'
+"ieg_gene_list"