Merge pull request #203 from samuel-marsh/release/3.0.0

Release/3.0.0

.Rbuildignore

@@ -15,3 +15,4 @@ vignettes/*.orig$
 ^README\.Rmd$
 ^cran-comments\.md$
 ^CRAN-SUBMISSION$
+^data-raw$

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 2.1.2
-Date: 2024-02-27 15:16:14 UTC
-SHA: 3789733c4393d9d0abdff14c94b57f25a4da29ff
+Version: 3.0.0
+Date: 2024-12-05 20:08:02 UTC
+SHA: 0193fbdf787f715d4eb9e36b96bb74d32fc9ad15

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: 2.1.2
-Date: 2024-02-27
+Version: 3.0.0
+Date: 2024-12-05
 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"),
@@ -68,4 +68,4 @@ License: GPL (>= 3)
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2

NAMESPACE

@@ -1,34 +1,54 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method("Idents<-",liger)
 S3method(Add_Cell_Complexity,Seurat)
 S3method(Add_Cell_Complexity,liger)
+S3method(Add_Cell_QC_Metrics,Seurat)
+S3method(Add_Cell_QC_Metrics,liger)
+S3method(Add_Hemo,Seurat)
+S3method(Add_Hemo,liger)
 S3method(Add_Mito_Ribo,Seurat)
 S3method(Add_Mito_Ribo,liger)
+S3method(Add_Top_Gene_Pct,Seurat)
+S3method(Add_Top_Gene_Pct,liger)
+S3method(Cells,liger)
+S3method(Embeddings,liger)
+S3method(Features,liger)
 S3method(Fetch_Meta,Seurat)
 S3method(Fetch_Meta,liger)
+S3method(Idents,liger)
+S3method(Rename_Clusters,Seurat)
+S3method(Rename_Clusters,liger)
+S3method(WhichCells,liger)
 S3method(as.LIGER,Seurat)
 S3method(as.LIGER,list)
 S3method(as.Seurat,liger)
 S3method(as.anndata,Seurat)
 S3method(as.anndata,liger)
+export("Idents<-")
 export(Add_Alt_Feature_ID)
 export(Add_CellBender_Diff)
 export(Add_Cell_Complexity)
 export(Add_Cell_Complexity_LIGER)
 export(Add_Cell_Complexity_Seurat)
 export(Add_Cell_QC_Metrics)
+export(Add_Hemo)
 export(Add_Mito_Ribo)
 export(Add_Mito_Ribo_LIGER)
 export(Add_Mito_Ribo_Seurat)
 export(Add_Pct_Diff)
 export(Add_Sample_Meta)
+export(Add_Top_Gene_Pct)
 export(Add_Top_Gene_Pct_Seurat)
 export(Barcode_Plot)
 export(Blank_Theme)
 export(Case_Check)
 export(CellBender_Diff_Plot)
 export(CellBender_Feature_Diff)
 export(Cell_Highlight_Plot)
+export(Cells)
+export(Cells_by_Identities_LIGER)
+export(Cells_per_Sample)
 export(Change_Delim_All)
 export(Change_Delim_Prefix)
 export(Change_Delim_Suffix)
@@ -49,16 +69,21 @@ export(DimPlot_LIGER)
 export(DimPlot_scCustom)
 export(DiscretePalette_scCustomize)
 export(DotPlot_scCustom)
+export(Embeddings)
 export(Extract_Modality)
 export(Extract_Sample_Meta)
 export(Extract_Top_Markers)
+export(Factor_Cor_Plot)
 export(FeaturePlot_DualAssay)
 export(FeaturePlot_scCustom)
 export(FeatureScatter_scCustom)
 export(Feature_Present)
+export(Features)
 export(Fetch_Meta)
+export(Find_Factor_Cor)
 export(Gene_Present)
 export(Hue_Pal)
+export(Idents)
 export(Iterate_Barcode_Rank_Plot)
 export(Iterate_Cluster_Highlight_Plot)
 export(Iterate_DimPlot_bySample)
@@ -69,7 +94,6 @@ export(Iterate_Plot_Density_Custom)
 export(Iterate_Plot_Density_Joint)
 export(Iterate_VlnPlot_scCustom)
 export(JCO_Four)
-export(LIGER_Features)
 export(Liger_to_Seurat)
 export(MAD_Stats)
 export(Median_Stats)
@@ -93,6 +117,7 @@ export(Plot_Median_Genes)
 export(Plot_Median_Mito)
 export(Plot_Median_Other)
 export(Plot_Median_UMIs)
+export(Proportion_Plot)
 export(Pull_Cluster_Annotation)
 export(Pull_Directory_List)
 export(QC_Histogram)
@@ -105,6 +130,7 @@ export(QC_Plots_Feature)
 export(QC_Plots_Genes)
 export(QC_Plots_Mito)
 export(QC_Plots_UMIs)
+export(Random_Cells_Downsample)
 export(Read10X_GEO)
 export(Read10X_Multi_Directory)
 export(Read10X_h5_GEO)
@@ -114,6 +140,7 @@ export(Read_CellBender_h5_Multi_Directory)
 export(Read_CellBender_h5_Multi_File)
 export(Read_GEO_Delim)
 export(Read_Metrics_10X)
+export(Read_Metrics_CellBender)
 export(Reduction_Loading_Present)
 export(Rename_Clusters)
 export(Replace_Suffix)
@@ -134,23 +161,28 @@ export(Seq_QC_Plot_Transcriptome)
 export(Seq_QC_Plot_UMIs)
 export(Setup_scRNAseq_Project)
 export(Single_Color_Palette)
+export(SpatialDimPlot_scCustom)
 export(Split_FeatureScatter)
 export(Split_Layers)
 export(Split_Vector)
 export(Stacked_VlnPlot)
 export(Store_Misc_Info_Seurat)
 export(Store_Palette_Seurat)
+export(Subset_LIGER)
 export(Top_Genes_Factor)
 export(UnRotate_X)
 export(Updated_HGNC_Symbols)
+export(Updated_MGI_Symbols)
 export(VariableFeaturePlot_scCustom)
 export(Variable_Features_ALL_LIGER)
 export(VlnPlot_scCustom)
+export(WhichCells)
 export(as.LIGER)
 export(as.Seurat)
 export(as.anndata)
 export(plotFactors_scCustom)
 export(scCustomize_Palette)
+export(seq_zeros)
 export(theme_ggprism_mod)
 export(viridis_dark_high)
 export(viridis_inferno_dark_high)
@@ -182,11 +214,16 @@ importFrom(Seurat,Read10X_h5)
 importFrom(Seurat,VariableFeaturePlot)
 importFrom(Seurat,VizDimLoadings)
 importFrom(Seurat,VlnPlot)
+importFrom(SeuratObject,"Idents<-")
+importFrom(SeuratObject,Cells)
 importFrom(SeuratObject,DefaultDimReduc)
+importFrom(SeuratObject,Embeddings)
 importFrom(SeuratObject,Features)
+importFrom(SeuratObject,Idents)
 importFrom(SeuratObject,JoinLayers)
 importFrom(SeuratObject,LayerData)
 importFrom(SeuratObject,Layers)
+importFrom(SeuratObject,WhichCells)
 importFrom(SeuratObject,as.Seurat)
 importFrom(circlize,colorRamp2)
 importFrom(cowplot,theme_cowplot)
@@ -208,6 +245,7 @@ importFrom(dplyr,mutate)
 importFrom(dplyr,n)
 importFrom(dplyr,pull)
 importFrom(dplyr,rename)
+importFrom(dplyr,right_join)
 importFrom(dplyr,select)
 importFrom(dplyr,setdiff)
 importFrom(dplyr,slice)
@@ -216,6 +254,7 @@ importFrom(dplyr,summarise)
 importFrom(dplyr,summarize)
 importFrom(dplyr,union)
 importFrom(forcats,fct_relevel)
+importFrom(forcats,fct_rev)
 importFrom(ggbeeswarm,geom_quasirandom)
 importFrom(ggplot2,theme)
 importFrom(ggprism,theme_prism)
@@ -258,8 +297,11 @@ importFrom(scales,alpha)
 importFrom(scales,hue_pal)
 importFrom(scales,label_percent)
 importFrom(scattermore,geom_scattermore)
+importFrom(stats,as.dist)
 importFrom(stats,complete.cases)
 importFrom(stats,cor)
+importFrom(stats,cutree)
+importFrom(stats,hclust)
 importFrom(stats,kmeans)
 importFrom(stats,mad)
 importFrom(stats,median)
@@ -271,6 +313,7 @@ importFrom(stringi,stri_replace_last_fixed)
 importFrom(stringr,str_c)
 importFrom(stringr,str_detect)
 importFrom(stringr,str_extract)
+importFrom(stringr,str_pad)
 importFrom(stringr,str_replace)
 importFrom(stringr,str_replace_na)
 importFrom(stringr,str_to_lower)

NEWS.md

@@ -1,3 +1,115 @@
+# scCustomize 3.0.0 (2024-12-05)  
+## Added  
+**Major Updates to Functionality with rliger Package:**  
+*Added new utility functions to interact with liger v2.0.0+ object format change:*  
+    - `Subset_LIGER` to quickly subset by cluster or other meta data variable.  
+    - `Cells_by_Identities_LIGER` to extract list of barcodes sorted by values within given meta data column.  
+
+*Extended the following Seurat/SeuratObject generic functions to work seamlessly with liger objects:*  
+    - `Cells` to extract vector of all cells or list vectors of cells by dataset.  
+    - `Features` to extract vector of all features or list vectors of features by dataset.  
+    - `WhichCells` to extract vector or list of cells matching identity criteria.  
+    - `Embeddings` to extract matrix containing dimensionality reduction embeddings or iNMF h.norm matrix.  
+    - `Idents` and `Idents<-` to extract and set default identities/clusters.  
+
+*Updated functions to interact with both old and new style liger objects:*  
+    - `plotFactors_scCustom()`  
+    - `Fetch_Meta`  
+    - `Top_Genes_Factor`  
+    - `Add_Mito_Ribo`  
+    - `Add_Cell_Complexity`  
+    - `DimPlot_LIGER`  
+    - `Variable_Features_ALL_LIGER`  
+    - `Feature_Present`  
+
+*New functions compatible with old and new style liger objects:*  
+    - Added new function `Add_Hemo` to add hemoglobin gene percentage for QC.  Also added as parameter to `Add_Cell_QC_Metrics`.  `Add_Hemo` supports all default species: (human, mouse, marmoset, zebrafish, rat, drosophila, rhesus macaque, and chicken) and works with both Seurat and liger objects.  
+
+*New scCustomize generics to function across both Seurat and Liger objects:*  
+    - `Add_Hemo` (see above).  
+    - `Rename_Clusters` now S3 generic for setting new active.ident (Seurat) or defaultCluster (Liger).  
+
+*New functions for Seurat and rliger v2.0.0+ only:*
+    - Added new function `Find_Factor_Cor` to return correlation matrix between factor gene loadings from liger or Seurat object.  
+    - Added new function `Factor_Cor_Plot` to plot positive correlations from liger or Seurat object.  
+
+*Updated functions to recommend new rliger equivalents for users with rliger v2.0.0+:*  
+    - `as.LIGER`  
+    - `as.Seurat`  
+
+
+**General scCustomize Updates:**  
+*New functions:*  
+- Added new function `Add_Hemo` to add hemoglobin gene percentage for QC.  Also added as parameter to `Add_Cell_QC_Metrics`.  `Add_Hemo` supports all default species: (human, mouse, marmoset, zebrafish, rat, drosophila, and rhesus macaque) and works with both Seurat and liger objects.  
+- Added new function `seq_zeros()` to create sequences with preceding zeros.  
+- Added new function `Read_Metrics_CellBender` to read in the summary metrics csv file produced by CellBender.  Can either read all metrics files from parent directory of output folders or a single metrics file.  
+- Added `Updated_MGI_Symbols` to check for update gene names/symbols in mouse data ([#202](https://github.com/samuel-marsh/scCustomize/issues/202)).  
+- Added plotting function `Proportion_Plot` to plot pie chart or bar chart of proportion (or total counts) of cells in each identity class.  
+- Added new function `Random_Cells_Downsample` to return either a vector or list with randomly downsampled cells for each identity class.  
+- Added new function `Cells_per_Sample` to quickly return data.frame with just number of cells per sample.  
+
+*Updated functions:*  
+- Added new parameters `data_name` and `overwrite` to `Add_Alt_Feature_ID` to support new storage location.  
+- Added `cells` parameter explicitly to `FeatureScatter_scCustom`.  
+- Added Chicken (Gallus gallus) to default species for QC functions.  Thanks @dpearton; ([#176](https://github.com/samuel-marsh/scCustomize/issues/176)).  
+- Added new plotting function `SpatialDimPlot_scCustom`.  Thanks for encouragement @puapinyoying @nina-hahn ([#160](https://github.com/samuel-marsh/scCustomize/issues/160)).  
+- Added ability of `Read_Metrics_10X` to read a single metrics csv file and return data formatted the same way as when reading multiple files.  
+- Added parameter `cutoff_line_width` to the `QC_Plot_*` family of plots to control line thickness of cutoff lines.  
+- `Cluster_Stats_All_Samples` now returns data.frame with row order reflecting the frequency of cells.  
+- `Add_Mito_Ribo` now supports datasets aligned to multi-species reference genomes ([#184](https://github.com/samuel-marsh/scCustomize/issues/184)).  
+- Added parameter `add_prop_plot` to `DimPlot_scCustom` to return plot showing number or percent of cells per identity along with the DimPlot.  
+- Added optional parameter `colors_use_assay2` to `FeaturePlot_DualAssay` which allows for specification of different palettes for the two plots ([#182](https://github.com/samuel-marsh/scCustomize/issues/182)).  
+- Added new folder and scripts (see "data-raw/" on GitHub) detailing the creation of gene lists used in `Add_Cell_QC_Metrics`.  
+- Added ensembl ID support for percent hemoglobin, msigdb, and IEG gene sets ([#186](https://github.com/samuel-marsh/scCustomize/issues/186)).  
+- Add verbosity parameter to `Store_Misc_Info_Seurat` and `Store_Palette_Seurat`.  
+- Explicitly reveal the `reduction` parameter in `Cluster_Highlight_Plot` and `Meta_Highlight_Plot` ([#198](https://github.com/samuel-marsh/scCustomize/issues/198)).  
+- Added `show_row_names` `show_column_names`, `column_names_side`, `row_names_side`, `legend_position`, `legend_orientation`, `show_ident_legend`, and `show_ident_colors` parameters to `Clustered_DotPlot`.  Thanks for idea and code @johnminglu ([#199](https://github.com/samuel-marsh/scCustomize/issues/199)).  
+- Updated `Split_Vector` to allow user to specify number of chunks or size of chunks for splitting vector.  
+- Update `RenameClusters` with additional parameters to enable storage of both old idents and new idents in meta.data within the function.  
+- Update `Add_Cell_QC_Metrics.Seurat` to explicitly reveal `list_species_names` parameter.  
+- Added new vignette for spatial plotting.  
+- Added new and expanded vignette on use of object QC functions for better clarity on these functions and their uses (previously was part of QC Plotting & Helpers/Utilities Vignettes).  Plotting elements of QC Plotting vignette are unchanged.  
+
+
+## Changed  
+- **BREAKING CHANGES** `Add_Top_Gene_Pct_Seurat` is now S3 generic that works with both Seurat and liger objects and has been renamed `Add_Top_Gene_Pct`.  
+- `Add_Cell_QC_Metrics` is now S3 generic and works with both Seurat and liger objects.  
+- Changed storage location for `Add_Alt_Feature_ID` to `@misc` slot of object for safer storage across object filtering.  
+- Added error check in `as.anndata` to explicitly check for installation of anndata before starting conversion ([#162](https://github.com/samuel-marsh/scCustomize/issues/162)).  
+- Updated `Plot_Median_Genes`, `Plot_Median_UMIs`, `Plot_Median_Mito`, `Plot_Median_Other`, `Plot_Cells_per_Sample` to understand "ident" as grouping variable.  
+- Updated `Store_Misc_Info_Seurat` to use Seurat accessor/setter function `Seurat::Misc()`.  
+- Updated documentation for `sample_names` in `Read_CellBender_h5_Multi_File` to clarify parameter behavior (related to ([#208](https://github.com/samuel-marsh/scCustomize/issues/208))).  
+- Updated `Read_Metrics_10X` to support adjusts to metrics summary format and metric names in output from Cell Ranger v9+.  
+- Some reorganization of R/ directory/scripts.  
+
+
+## Fixes  
+- Nebulosa plotting functions `Plot_Density_Custom` and `Plot_Density_Joint_Only` have been re-enabled for users with ggplot2 v3.5.0 following Nebulosa v1.12.1 update patch.     
+- Fixed bug causing error in `Add_Cell_QC_Metrics` when `overwrite = TRUE` ([#165](https://github.com/samuel-marsh/scCustomize/issues/165)).  
+- Fixed wrong description of parameter in manual entry for `DotPlot_scCustom` ([#158](https://github.com/samuel-marsh/scCustomize/issues/158)).  
+- Fixed several potential errors in `as.anndata` from Seurat conversion that previously caused failures ([#168](https://github.com/samuel-marsh/scCustomize/issues/168)).  
+- Fixed errors in `Create_Cluster_Annotation_File` if for file path and csv name errors.  
+- Fixed error when using `plot_median` and more than one feature in `VlnPlot_scCustom` ([#169](https://github.com/samuel-marsh/scCustomize/issues/169)).  
+- Fixed bug while collecting legends for `DimPlot_scCustom` due to changes in guides updated with ggplot2 v3.5.0 ([#171](https://github.com/samuel-marsh/scCustomize/issues/171)).  
+- Fixed error in `Add_Sample_Meta` that still errored when setting `na_ok = TRUE`.  
+- Fixed errors in `Plot_Median_*` family that caused issues when `group_by` parameter was NULL.  
+- Fixed errors in `FeaturePlot_scCustom` when setting `combine = FALSE`.  
+- Fixed bug in `DimPlot_scCustom` that could cause blank plot when rasterizing points.  
+- Fixed bug in `MAD_Stats` that didn't respect `mad_num` parameter ([#183](https://github.com/samuel-marsh/scCustomize/issues/183)).  
+- Fixed bugs in `MAD_Stats` that could cause issues if `mad_num` was less than or equal to 0 and returned error if setting `group_by_var` to "ident".  
+- Replaced lingering instances of deprecated tidyr code .data[["var"]] with update `all_of`/`any_of` syntax.  
+- Fixed issue that could occur with some meta data modifying functions due to column name collisions in internals of function ([#193](https://github.com/samuel-marsh/scCustomize/issues/193)).  
+- Fixed issue that caused error when using `Cluster_Highlight_Plot` with `split.by` parameter ([#201](https://github.com/samuel-marsh/scCustomize/issues/201)).  
+- Added check and informative error message to `Convert_Assay` ([#205](https://github.com/samuel-marsh/scCustomize/issues/205)).  
+- Fixed issue with anndata conversion and Seurat V5 objects ([#195](https://github.com/samuel-marsh/scCustomize/issues/195)).  
+- Fixed issue with `Updated_HGNC_Symbols` due to change in URL path for gene names ([#209](https://github.com/samuel-marsh/scCustomize/issues/209)).  
+- Fixed bug in `DimPlot_scCustom` when `split.by` and `label.box = TRUE`.  
+- Fixed bug in `DiscretePalette_scCustom` that didn't error when supplying invalid palette names.  
+- Fixed bug in `DimPlot_LIGER` that provided uniformative error message when changing the default cluster ident.  
+- Spelling and style fixes.  Thanks @kew24.  
+
+
+
 # scCustomize 2.1.2 (2024-02-27)  
 ## Added  
 - None.  

R/Color_Palettes.R

@@ -420,12 +420,20 @@ DiscretePalette_scCustomize <- function(
   shuffle_pal = FALSE,
   seed = 123
 ) {
+  palette_options <- c("alphabet", "alphabet2", "glasbey", "polychrome", "stepped", "ditto_seq", "varibow")
+
   if (is.null(x = palette)) {
     cli_abort(message = c("Must specify a palette to return colors.",
-                          "i" = "{.code palette} options are: {.field {names(palette_list)}}")
+                          "i" = "{.code palette} options are: {.field {names(palette_options)}}")
     )
   }
 
+  # check palette valid
+  if (!palette %in% palette_options) {
+    cli_abort(message = c("The specified palette: {.field {palette}} is not valid.",
+                          "i" = "Valid palettes are: {.val {palette_options}}"))
+  }
+
   # dittoseq check
   if (palette == "ditto_seq") {
     dittoseq_check <- is_installed(pkg = "dittoSeq")
@@ -510,6 +518,9 @@ scCustomize_Palette <- function(
   if (isTRUE(x = ggplot_default_colors)) {
     colors_use <- Hue_Pal(num_colors = num_groups)
   } else {
+    if (num_groups < 36 && color_seed != 123) {
+      cli_inform(message = "{.code color_seed} only applies if number of groups plotted is greater than 36.")
+    }
     if (num_groups == 1) {
       colors_use <- "dodgerblue"
     }