diff --git a/DESCRIPTION b/DESCRIPTION index 9c101ac2c..09fed5401 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,14 +2,14 @@ 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" RRID:SCR_024675. -Version: 3.2.4 -Date: 2025-12-10 +Version: 3.2.4.9012 +Date: 2026-04-02 Authors@R: c( person(given = "Samuel", family = "Marsh", email = "sccustomize@gmail.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-3012-6945")), person(given = "Ming", family = "Tang", role = c("ctb"), email = "tangming2005@gmail.com"), person(given = 'Velina', family = 'Kozareva', role = c('ctb')), - person("Lucas", "Graybuck", email = "lucasg@alleninstitute.org", role = c('ctb')), - person("Zoe", "Clarke", email = "zoe.clarke@utoronto.ca", role = c('ctb'), comment = c(ORCID = "0000-0003-0336-8049")) + person(given ="Lucas", family = "Graybuck", email = "lucasg@alleninstitute.org", role = c('ctb')), + person(given ="Zoe", family = "Clarke", email = "zoe.clarke@utoronto.ca", role = c('ctb'), comment = c(ORCID = "0000-0003-0336-8049")) ) 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 diff --git a/NAMESPACE b/NAMESPACE index fc0717b1e..45b74d9bc 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -144,6 +144,7 @@ export(Read_CellBender_h5_Multi_File) export(Read_GEO_Delim) export(Read_Metrics_10X) export(Read_Metrics_CellBender) +export(Read_Velocity) export(Reduction_Loading_Present) export(Rename_Clusters) export(Replace_Suffix) diff --git a/NEWS.md b/NEWS.md index e480c085a..ac7e5395b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,28 @@ +# scCustomize 3.3.0 (2026-XX-XX) +## Added +- Added `reorder`, `reorder_decreasing`, and `plot_median` parameters to `Plot_Cells_per_Sample` when grouping by sample. +- Added `Read_Velocity` function to enable reading of velocyto loom output files without needing to install velocyto.R (which currently suffers from significant installation issues unrelated to reading loom files). + + + +## Changed +- **BREAKING CHANGE** The `plot_by` parameter has been soft-deprecated in `Seq_QC_Plot_*` family of functions. Please use `group.by` instead. Using `plot_by` will warn user but still work until scCustomize v3.5.0. +- **BREAKING CHANGE** The parameter `cutoff_line_width` has been soft-deprecated in `QC_Plot_*` family of functions. Please use `cutoff_linewidth` instead. Using `cutoff_line_width` will warn user but still work until scCustomize v3.5.0. +- **BREAKING CHANGE** The parameter `linewidth` has been soft-deprecated in `ElbowPlot_scCustom` function. Please use `cutoff_linewidth` instead. Using `linewidth` will warn user but still work until scCustomize v3.5.0. +- Add some checks for appropriate `...` usage. + + +## Fixes +- Fixed default setting of `linewidth` parameter in `geom_hline` and `geom_vline` calls to avoid unnecessary empty aesthetic warnings in ggplot2 4.0.0+. +- Fixed warning in `Dataset_Size_LIGER` due to deprecation in `Extract_Sample_Meta`. +- Fixed issue with group colors in in `DimPlot_scCustom` when split only contains one group Thanks @zrlewis, ([#262](https://github.com/samuel-marsh/scCustomize/issues/262)). + + + + + + + # scCustomize 3.2.4 (2025-12-10) ## Added - Add progress bar support to following functions with `parallel` parameter using mcprogress package: `Read10X_GEO`, `Read10X_h5_GEO`, `Read10X_Multi_Directory`, `Read10X_h5_Multi_Directory`, `Read_GEO_Delim`, `Read_CellBender_h5_Multi_Directory`, `Read_CellBender_h5_Multi_File`. diff --git a/R/Internal_Utilities.R b/R/Internal_Utilities.R index 7c3a2250e..f06b2e476 100644 --- a/R/Internal_Utilities.R +++ b/R/Internal_Utilities.R @@ -590,7 +590,7 @@ Percent_Expressing_Meta <- function( row_dim_names <- features_list col_dim_names <- names(x = percent_expressing) mat_dims <- list(row_dim_names, col_dim_names) - final_df <- data.frame(matrix(unlist(percent_expressing), nrow = length(features_list), byrow = FALSE, dimnames = mat_dims), stringsAsFactors = FALSE) + final_df <- data.frame(matrix(unlist(x = percent_expressing), nrow = length(features_list), byrow = FALSE, dimnames = mat_dims), stringsAsFactors = FALSE) return(final_df) } @@ -645,7 +645,7 @@ Middle_Number <- function( max ) { min_max <- c(min, max) - middle <- min_max[-length(min_max)] + diff(min_max) / 2 + middle <- min_max[-length(x = min_max)] + diff(x = min_max) / 2 return(middle) } diff --git a/R/LIGER_Utilities.R b/R/LIGER_Utilities.R index 37587733a..a922df152 100644 --- a/R/LIGER_Utilities.R +++ b/R/LIGER_Utilities.R @@ -581,7 +581,7 @@ Dataset_Size_LIGER <- function( found_meta <- Meta_Present(object = liger_object, meta_col_names = meta_data_column, print_msg = FALSE)[[1]] - sample_meta <- Extract_Sample_Meta(object = liger_object, sample_name = "dataset", variables_include = found_meta) + sample_meta <- Extract_Sample_Meta(object = liger_object, sample_col = "dataset", variables_include = found_meta) # join data dataset_cells_df <- right_join(x = dataset_cells_df, y = sample_meta, by = join_by("dataset")) @@ -1096,7 +1096,6 @@ Add_Cell_QC_Metrics.liger <- function( add_IEG = TRUE, add_hemo = TRUE, add_lncRNA = TRUE, - add_cell_cycle = TRUE, species, mito_name = "percent_mito", ribo_name = "percent_ribo", diff --git a/R/Plotting_QC_Seq_10X.R b/R/Plotting_QC_Seq_10X.R index 6ebf4c9bf..e9208f27f 100644 --- a/R/Plotting_QC_Seq_10X.R +++ b/R/Plotting_QC_Seq_10X.R @@ -8,7 +8,8 @@ #' Plot the mean number of reads per cell #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param plot_by `r lifecycle::badge("deprecated")` soft-deprecated. See `group.by`. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -35,45 +36,55 @@ Seq_QC_Plot_Reads_per_Cell <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Reads_per_Cell(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") + } + + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use } } - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Mean_Reads_per_Cell"]])) + @@ -89,7 +100,7 @@ Seq_QC_Plot_Reads_per_Cell <- function( xlab("") + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Mean_Reads_per_Cell"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Mean_Reads_per_Cell"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + theme(legend.position = "none", @@ -100,7 +111,7 @@ Seq_QC_Plot_Reads_per_Cell <- function( scale_fill_manual(values = colors_use) + ggtitle("Mean Reads per Cell per Sample") + ylab('Mean Reads per Cell') + - xlab(plot_by) + + xlab(group.by) + theme_ggprism_mod() } @@ -120,10 +131,10 @@ Seq_QC_Plot_Reads_per_Cell <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by ,colors_use = NULL,]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -142,7 +153,7 @@ Seq_QC_Plot_Reads_per_Cell <- function( #' Plot the number of cells per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -169,45 +180,55 @@ Seq_QC_Plot_Reads_per_Cell <- function( Seq_QC_Plot_Number_Cells <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Number_Cells(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use } } - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Estimated_Number_of_Cells"]])) + @@ -223,7 +244,7 @@ Seq_QC_Plot_Number_Cells <- function( xlab("") + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Estimated_Number_of_Cells"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Estimated_Number_of_Cells"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + theme(legend.position = "none", @@ -234,7 +255,7 @@ Seq_QC_Plot_Number_Cells <- function( scale_fill_manual(values = colors_use) + ggtitle("Cells per Sample") + ylab('Cells') + - xlab(plot_by) + + xlab(group.by) + theme_ggprism_mod() } @@ -254,10 +275,10 @@ Seq_QC_Plot_Number_Cells <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -276,7 +297,7 @@ Seq_QC_Plot_Number_Cells <- function( #' Plot the median genes per cell per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -303,45 +324,55 @@ Seq_QC_Plot_Number_Cells <- function( Seq_QC_Plot_Genes <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Genes(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { cli_abort(message = " is not a column in the provided `metrics_dataframe`.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use } } - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Median_Genes_per_Cell"]])) + @@ -352,13 +383,13 @@ Seq_QC_Plot_Genes <- function( xlab("") + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Median_Genes_per_Cell"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Median_Genes_per_Cell"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Median Genes per Cell") + ylab('Median Genes') + - xlab(plot_by) + + xlab(group.by) + theme_ggprism_mod() } @@ -378,10 +409,10 @@ Seq_QC_Plot_Genes <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -400,7 +431,7 @@ Seq_QC_Plot_Genes <- function( #' Plot the median UMIs per cell per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -427,45 +458,55 @@ Seq_QC_Plot_Genes <- function( Seq_QC_Plot_UMIs <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_UMIs(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use } } - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Median_UMI_Counts_per_Cell"]])) + @@ -476,13 +517,13 @@ Seq_QC_Plot_UMIs <- function( xlab("") + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Median_UMI_Counts_per_Cell"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Median_UMI_Counts_per_Cell"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Median UMIs per Cell") + ylab('Median UMIs') + - xlab(plot_by) + + xlab(group.by) + theme_ggprism_mod() } @@ -502,10 +543,10 @@ Seq_QC_Plot_UMIs <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -524,7 +565,7 @@ Seq_QC_Plot_UMIs <- function( #' Plot the total genes detected per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -551,45 +592,55 @@ Seq_QC_Plot_UMIs <- function( Seq_QC_Plot_Total_Genes <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Total_Genes(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") + } + + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use } } - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Total_Genes_Detected"]])) + @@ -600,13 +651,13 @@ Seq_QC_Plot_Total_Genes <- function( xlab("") + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Total_Genes_Detected"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Total_Genes_Detected"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Total Genes Detected per Sample") + ylab('Total Genes') + - xlab(plot_by) + + xlab(group.by) + theme_ggprism_mod() } @@ -626,10 +677,10 @@ Seq_QC_Plot_Total_Genes <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -648,7 +699,7 @@ Seq_QC_Plot_Total_Genes <- function( #' Plot the sequencing saturation percentage per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -676,38 +727,48 @@ Seq_QC_Plot_Total_Genes <- function( Seq_QC_Plot_Saturation <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Saturation(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -718,7 +779,7 @@ Seq_QC_Plot_Saturation <- function( metrics_dataframe[,"Sequencing_Saturation"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Sequencing_Saturation"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Sequencing_Saturation"]]), color = .data[["samples_plotting"]]) + @@ -730,13 +791,13 @@ Seq_QC_Plot_Saturation <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Sequencing_Saturation"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Sequencing_Saturation"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Sequencing Saturation") + ylab('Sequencing Saturation Percent') + - xlab(plot_by)+ + xlab(group.by)+ scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -757,10 +818,10 @@ Seq_QC_Plot_Saturation <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -779,7 +840,7 @@ Seq_QC_Plot_Saturation <- function( #' Plot the fraction of reads in cells per sample #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -807,38 +868,48 @@ Seq_QC_Plot_Saturation <- function( Seq_QC_Plot_Reads_in_Cells <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Reads_in_Cells(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") + } + + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -849,7 +920,7 @@ Seq_QC_Plot_Reads_in_Cells <- function( metrics_dataframe[,"Fraction_Reads_in_Cells"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Fraction_Reads_in_Cells"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Fraction_Reads_in_Cells"]]), color = .data[["samples_plotting"]]) + @@ -861,13 +932,13 @@ Seq_QC_Plot_Reads_in_Cells <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Fraction_Reads_in_Cells"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Fraction_Reads_in_Cells"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Fraction of Reads in Cells per Sample") + ylab('Fraction of Reads in Cells') + - xlab(plot_by)+ + xlab(group.by)+ scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -888,10 +959,10 @@ Seq_QC_Plot_Reads_in_Cells <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -910,7 +981,7 @@ Seq_QC_Plot_Reads_in_Cells <- function( #' Plot the fraction of reads confidently mapped to transcriptome #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -938,38 +1009,48 @@ Seq_QC_Plot_Reads_in_Cells <- function( Seq_QC_Plot_Transcriptome <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Transcriptome(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -980,7 +1061,7 @@ Seq_QC_Plot_Transcriptome <- function( metrics_dataframe[,"Reads_Mapped_Confidently_to_Transcriptome"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Confidently_to_Transcriptome"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Confidently_to_Transcriptome"]]), color = .data[["samples_plotting"]]) + @@ -992,13 +1073,13 @@ Seq_QC_Plot_Transcriptome <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Confidently_to_Transcriptome"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Confidently_to_Transcriptome"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Transcriptome") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1018,10 +1099,10 @@ Seq_QC_Plot_Transcriptome <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1040,7 +1121,7 @@ Seq_QC_Plot_Transcriptome <- function( #' Plot the fraction of reads confidently mapped to genome #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1068,38 +1149,48 @@ Seq_QC_Plot_Transcriptome <- function( Seq_QC_Plot_Genome <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Genome(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -1110,7 +1201,7 @@ Seq_QC_Plot_Genome <- function( metrics_dataframe[,"Reads_Mapped_Confidently_to_Genome"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Confidently_to_Genome"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Confidently_to_Genome"]]), color = .data[["samples_plotting"]]) + @@ -1122,13 +1213,13 @@ Seq_QC_Plot_Genome <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Confidently_to_Genome"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Confidently_to_Genome"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Genome") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1148,10 +1239,10 @@ Seq_QC_Plot_Genome <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1170,7 +1261,7 @@ Seq_QC_Plot_Genome <- function( #' Plot the fraction of reads confidently mapped to intergenic regions #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1198,38 +1289,48 @@ Seq_QC_Plot_Genome <- function( Seq_QC_Plot_Intergenic <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Intergenic(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -1240,7 +1341,7 @@ Seq_QC_Plot_Intergenic <- function( metrics_dataframe[,"Reads_Mapped_Confidently_to_Intergenic_Regions"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Confidently_to_Intergenic_Regions"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Confidently_to_Intergenic_Regions"]]), color = .data[["samples_plotting"]]) + @@ -1252,13 +1353,13 @@ Seq_QC_Plot_Intergenic <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Confidently_to_Intergenic_Regions"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Confidently_to_Intergenic_Regions"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Intergenic Regions") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1278,10 +1379,10 @@ Seq_QC_Plot_Intergenic <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1300,7 +1401,7 @@ Seq_QC_Plot_Intergenic <- function( #' Plot the fraction of reads confidently mapped to intronic regions #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1328,38 +1429,48 @@ Seq_QC_Plot_Intergenic <- function( Seq_QC_Plot_Intronic <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Intronic(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -1370,7 +1481,7 @@ Seq_QC_Plot_Intronic <- function( metrics_dataframe[,"Reads_Mapped_Confidently_to_Intronic_Regions"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Confidently_to_Intronic_Regions"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Confidently_to_Intronic_Regions"]]), color = .data[["samples_plotting"]]) + @@ -1382,13 +1493,13 @@ Seq_QC_Plot_Intronic <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Confidently_to_Intronic_Regions"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Confidently_to_Intronic_Regions"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Intronic Regions") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1408,10 +1519,10 @@ Seq_QC_Plot_Intronic <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1430,7 +1541,7 @@ Seq_QC_Plot_Intronic <- function( #' Plot the fraction of reads confidently mapped to Exonic regions #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1458,38 +1569,48 @@ Seq_QC_Plot_Intronic <- function( Seq_QC_Plot_Exonic <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Exonic(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") + } + + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -1500,7 +1621,7 @@ Seq_QC_Plot_Exonic <- function( metrics_dataframe[,"Reads_Mapped_Confidently_to_Exonic_Regions"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Confidently_to_Exonic_Regions"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Confidently_to_Exonic_Regions"]]), color = .data[["samples_plotting"]]) + @@ -1512,13 +1633,13 @@ Seq_QC_Plot_Exonic <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Confidently_to_Exonic_Regions"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Confidently_to_Exonic_Regions"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Exonic Regions") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1538,10 +1659,10 @@ Seq_QC_Plot_Exonic <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1560,7 +1681,7 @@ Seq_QC_Plot_Exonic <- function( #' Plot the fraction of reads mapped Antisense to Gene #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1588,38 +1709,48 @@ Seq_QC_Plot_Exonic <- function( Seq_QC_Plot_Antisense <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, significance = FALSE, ... ) { - if (!plot_by %in% colnames(x = metrics_dataframe)) { - cli_abort(message = "{.val {plot_by}} is not a column in the provided {.code metrics_dataframe}.") + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Antisense(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + + if (!group.by %in% colnames(x = metrics_dataframe)) { + cli_abort(message = "{.val {group.by}} is not a column in the provided {.code metrics_dataframe}.") } - # Change plot_by to character vector to make significance functions show all comparisons - if (inherits(x = metrics_dataframe[[plot_by]], what = "factor")) { + # Change group.by to character vector to make significance functions show all comparisons + if (inherits(x = metrics_dataframe[[group.by]], what = "factor")) { stats_dataframe <- metrics_dataframe - stats_dataframe[[plot_by]] <- as.character(stats_dataframe[[plot_by]]) + stats_dataframe[[group.by]] <- as.character(stats_dataframe[[group.by]]) } else { stats_dataframe <- metrics_dataframe } # Create color palette if null and check valid if provided - length_plotby <- length(x = unique(x = metrics_dataframe[[plot_by]])) + length_plotby <- length(x = unique(x = metrics_dataframe[[group.by]])) - if (is.null(x = colors_use) && !plot_by == "sample_id") { + if (is.null(x = colors_use) && !group.by == "sample_id") { if (length_plotby <= 8) { colors_use <- Dark2_Pal() } else { colors_use <- DiscretePalette_scCustomize(num_colors = length_plotby, palette = "polychrome") } } else { - if (length(x = colors_use) < length_plotby && !plot_by == "sample_id") { + if (length(x = colors_use) < length_plotby && !group.by == "sample_id") { cli_abort(message = c("Not enough colors provided.", - "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {plot_by}} column: {.field {length_plotby}}.") + "i" = "The number of colors supplied: {.field {length(x = colors_use)}}, is less than the number of groups in {.val {group.by}} column: {.field {length_plotby}}.") ) } else { colors_use <- colors_use @@ -1630,7 +1761,7 @@ Seq_QC_Plot_Antisense <- function( metrics_dataframe[,"Reads_Mapped_Antisense_to_Gene"] <- as.numeric(gsub("%", "", metrics_dataframe[,"Reads_Mapped_Antisense_to_Gene"])) - if (plot_by == "sample_id") { + if (group.by == "sample_id") { metrics_dataframe$samples_plotting <- "Samples" plot <- ggplot(metrics_dataframe, aes(x = .data[["samples_plotting"]], y = .data[["Reads_Mapped_Antisense_to_Gene"]]), color = .data[["samples_plotting"]]) + @@ -1642,13 +1773,13 @@ Seq_QC_Plot_Antisense <- function( scale_y_continuous(labels = label_percent(accuracy = 0.01, scale = 1)) + theme_ggprism_mod() } else { - plot <- ggplot(metrics_dataframe, aes(x=.data[[plot_by]], y = .data[["Reads_Mapped_Antisense_to_Gene"]], fill = .data[[plot_by]])) + + plot <- ggplot(metrics_dataframe, aes(x=.data[[group.by]], y = .data[["Reads_Mapped_Antisense_to_Gene"]], fill = .data[[group.by]])) + geom_boxplot(fill = "white") + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + scale_fill_manual(values = colors_use) + ggtitle("Percent of Reads Confidently Mapped to Antisense to Gene") + ylab('Percent of Reads') + - xlab(plot_by) + + xlab(group.by) + scale_y_continuous(labels = label_percent(accuracy = 1, scale = 1)) + theme_ggprism_mod() } @@ -1668,10 +1799,10 @@ Seq_QC_Plot_Antisense <- function( )) } - if (length(x = unique(x = stats_dataframe[[plot_by]])) < 2) { - cli_abort(message = "Cannot calculate statistics when {.val {plot_by}} column contains less than 2 groups.") + if (length(x = unique(x = stats_dataframe[[group.by]])) < 2) { + cli_abort(message = "Cannot calculate statistics when {.val {group.by}} column contains less than 2 groups.") } - groups <- unique(x = stats_dataframe[[plot_by]]) + groups <- unique(x = stats_dataframe[[group.by]]) comparisons <- combn(groups, 2) comparisons <- data.frame(comparisons, stringsAsFactors = FALSE) @@ -1695,7 +1826,7 @@ Seq_QC_Plot_Antisense <- function( #' Plot a combined plot of the basic QC metrics from sequencing output. #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1723,7 +1854,8 @@ Seq_QC_Plot_Antisense <- function( Seq_QC_Plot_Basic_Combined <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -1731,6 +1863,15 @@ Seq_QC_Plot_Basic_Combined <- function( significance = FALSE, ... ) { + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Basic_Combined(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + # Create rotated axis value if (isTRUE(x = x_lab_rotate)) { axis_angle <- 45 @@ -1739,36 +1880,36 @@ Seq_QC_Plot_Basic_Combined <- function( } # Create Plots & modify for plotting together - p1 <- Seq_QC_Plot_Number_Cells(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p1 <- Seq_QC_Plot_Number_Cells(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p1 <- p1 + labs(title = str_wrap(p1$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p2 <- Seq_QC_Plot_Reads_per_Cell(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p2 <- Seq_QC_Plot_Reads_per_Cell(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p2 <- p2 + labs(title = str_wrap(p2$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p3 <- Seq_QC_Plot_Genes(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p3 <- Seq_QC_Plot_Genes(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p3 <- p3 + labs(title = str_wrap(p3$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p4 <- Seq_QC_Plot_UMIs(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p4 <- Seq_QC_Plot_UMIs(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p4 <- p4 + labs(title = str_wrap(p4$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p5 <- Seq_QC_Plot_Total_Genes(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p5 <- Seq_QC_Plot_Total_Genes(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p5 <- p5 + labs(title = str_wrap(p5$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p6 <- Seq_QC_Plot_Saturation(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p6 <- Seq_QC_Plot_Saturation(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p6 <- p6 + labs(title = str_wrap(p6$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p7 <- Seq_QC_Plot_Reads_in_Cells(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p7 <- Seq_QC_Plot_Reads_in_Cells(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p7 <- p7 + labs(title = str_wrap(p7$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p8 <- Seq_QC_Plot_Transcriptome(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p8 <- Seq_QC_Plot_Transcriptome(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p8 <- p8 + labs(title = str_wrap(p8$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) @@ -1787,7 +1928,7 @@ Seq_QC_Plot_Basic_Combined <- function( #' Plot a combined plot of the Alignment QC metrics from sequencing output. #' #' @param metrics_dataframe data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}). -#' @param plot_by Grouping factor for the plot. Default is to plot as single group with single point per sample. +#' @param group.by Grouping factor for the plot. Default is to plot as single group with single point per sample. #' @param colors_use colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if #' less than 8 groups and `DiscretePalette_scCustomize(palette = "polychrome")` if more than 8. #' @param dot_size size of the dots plotted if `plot_by` is not `sample_id` Default is 1. @@ -1815,7 +1956,8 @@ Seq_QC_Plot_Basic_Combined <- function( Seq_QC_Plot_Alignment_Combined <- function( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -1823,6 +1965,15 @@ Seq_QC_Plot_Alignment_Combined <- function( significance = FALSE, ... ) { + # check deprecation + if (is_present(plot_by)) { + deprecate_warn(when = "3.5.0", + what = "Seq_QC_Plot_Alignment_Combined(plot_by)", + details = c("i" = "The {.code plot_by} parameter is soft-deprecated. Please update code to use `group.by` instead.") + ) + group.by <- plot_by + } + # Create rotated axis value if (isTRUE(x = x_lab_rotate)) { axis_angle <- 45 @@ -1831,28 +1982,28 @@ Seq_QC_Plot_Alignment_Combined <- function( } # Create Plots & modify for plotting together - p1 <- Seq_QC_Plot_Genome(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size, ...) + p1 <- Seq_QC_Plot_Genome(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size, ...) p1 <- p1 + labs(title = str_wrap(p1$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p2 <- Seq_QC_Plot_Intergenic(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p2 <- Seq_QC_Plot_Intergenic(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p2 <- p2 + labs(title = str_wrap(p2$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p3 <- Seq_QC_Plot_Transcriptome(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p3 <- Seq_QC_Plot_Transcriptome(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p3 <- p3 + labs(title = str_wrap(p3$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p4 <- Seq_QC_Plot_Exonic(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p4 <- Seq_QC_Plot_Exonic(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p4 <- p4 + labs(title = str_wrap(p4$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p5 <- Seq_QC_Plot_Intronic(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p5 <- Seq_QC_Plot_Intronic(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p5 <- p5 + labs(title = str_wrap(p5$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) - p6 <- Seq_QC_Plot_Antisense(metrics_dataframe = metrics_dataframe, plot_by = plot_by, colors_use = colors_use, significance = significance, dot_size = dot_size,) + p6 <- Seq_QC_Plot_Antisense(metrics_dataframe = metrics_dataframe, group.by = group.by, colors_use = colors_use, significance = significance, dot_size = dot_size,) p6 <- p6 + labs(title = str_wrap(p6$labels$title, 18)) + theme_ggprism_mod(base_size = 10, axis_text_angle = axis_angle) diff --git a/R/Plotting_QC_Seurat.R b/R/Plotting_QC_Seurat.R index 01c75ee5f..7d7f4fc86 100644 --- a/R/Plotting_QC_Seurat.R +++ b/R/Plotting_QC_Seurat.R @@ -14,7 +14,9 @@ #' @param x_axis_label Label for x axis. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting. #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -54,7 +56,8 @@ QC_Plots_Genes <- function( y_axis_label = "Features", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, plot_boxplot = FALSE, @@ -68,6 +71,15 @@ QC_Plots_Genes <- function( color_seed = 123, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_Genes(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -76,8 +88,14 @@ QC_Plots_Genes <- function( nFeature <- paste0("nFeature_", assay) + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + plot <- VlnPlot_scCustom(seurat_object = seurat_object, features = nFeature, group.by = group.by, colors_use = colors_use, pt.size = pt.size, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, plot_boxplot = plot_boxplot, median_size = median_size, ...) + - geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle(plot_title) + @@ -109,7 +127,9 @@ QC_Plots_Genes <- function( #' @param x_axis_label Label for x axis. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting. #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -149,7 +169,8 @@ QC_Plots_UMIs <- function( y_axis_label = "UMIs", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -163,6 +184,15 @@ QC_Plots_UMIs <- function( color_seed = 123, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_UMIs(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -171,8 +201,14 @@ QC_Plots_UMIs <- function( nCount <- paste0("nCount_", assay) + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + plot <- VlnPlot_scCustom(seurat_object = seurat_object, features = nCount, group.by = group.by, colors_use = colors_use, pt.size = pt.size, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, plot_boxplot = plot_boxplot, median_size = median_size, ...) + - geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle(plot_title) + @@ -206,7 +242,9 @@ QC_Plots_UMIs <- function( #' @param x_axis_label Label for x axis. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting. #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -246,7 +284,8 @@ QC_Plots_Mito <- function( y_axis_label = "% Mitochondrial Gene Counts", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -259,11 +298,26 @@ QC_Plots_Mito <- function( color_seed = 123, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_Mito(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + plot <- VlnPlot_scCustom(seurat_object = seurat_object, features = mito_name, group.by = group.by, colors_use = colors_use, pt.size = pt.size, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, plot_boxplot = plot_boxplot, median_size = median_size, ...) + - geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle(plot_title) + @@ -296,7 +350,9 @@ QC_Plots_Mito <- function( #' @param plot_title Plot Title. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting. #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -338,7 +394,8 @@ QC_Plots_Feature <- function( plot_title = NULL, low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -351,14 +408,30 @@ QC_Plots_Feature <- function( color_seed = 123, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_Feature(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) if (is.null(x = plot_title)) { plot_title <- paste0(feature, " per Cell/Nucleus") } + + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + plot <- VlnPlot_scCustom(seurat_object = seurat_object, features = feature, group.by = group.by, colors_use = colors_use, pt.size = pt.size, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, plot_boxplot = plot_boxplot, median_size = median_size, ...) + - geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle(plot_title) + @@ -391,7 +464,9 @@ QC_Plots_Feature <- function( #' @param plot_title Plot Title. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -432,7 +507,8 @@ QC_Plots_Complexity <- function( plot_title = "Cell Complexity", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, plot_boxplot = FALSE, @@ -445,7 +521,36 @@ QC_Plots_Complexity <- function( color_seed = 123, ... ) { - plot <- QC_Plots_Feature(seurat_object = seurat_object, feature = feature, group.by = group.by, x_axis_label = x_axis_label, y_axis_label = y_axis_label, plot_title = plot_title, low_cutoff = low_cutoff, high_cutoff = high_cutoff, pt.size = pt.size, colors_use = colors_use, x_lab_rotate = x_lab_rotate, y_axis_log = y_axis_log, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, median_size = median_size, plot_boxplot = plot_boxplot, cutoff_line_width = cutoff_line_width, ...) + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_Complexity(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + + # plot + plot <- QC_Plots_Feature(seurat_object = seurat_object, + feature = feature, + group.by = group.by, + x_axis_label = x_axis_label, + y_axis_label = y_axis_label, + plot_title = plot_title, + low_cutoff = low_cutoff, + high_cutoff = high_cutoff, + pt.size = pt.size, + colors_use = colors_use, + x_lab_rotate = x_lab_rotate, + y_axis_log = y_axis_log, + raster = raster, + ggplot_default_colors = ggplot_default_colors, + color_seed = color_seed, + plot_median = plot_median, + median_size = median_size, + plot_boxplot = plot_boxplot, + cutoff_linewidth = cutoff_linewidth, + ...) return(plot) } @@ -463,7 +568,9 @@ QC_Plots_Complexity <- function( #' @param mito_cutoffs Numeric vector of length 1 or 2 to plot lines for potential low/high threshold for filtering. #' @param mito_name The column name containing percent mitochondrial counts information. Default value is #' "percent_mito" which is default value created when using `Add_Mito_Ribo()`. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param pt.size Point size for plotting #' @param plot_median logical, whether to plot median for each ident on the plot (Default is FALSE). #' @param median_size Shape size for the median is plotted. @@ -502,7 +609,8 @@ QC_Plots_Combined_Vln <- function( UMI_cutoffs = NULL, mito_cutoffs = NULL, mito_name = "percent_mito", - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -515,6 +623,15 @@ QC_Plots_Combined_Vln <- function( color_seed = 123, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plots_Combined_Vln(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -536,11 +653,57 @@ QC_Plots_Combined_Vln <- function( } # Create Individual Plots - feature_plot <- QC_Plots_Genes(seurat_object = seurat_object, group.by = group.by, low_cutoff = feature_cutoffs[1], high_cutoff = feature_cutoffs[2], pt.size = pt.size, colors_use = colors_use, x_lab_rotate = x_lab_rotate, y_axis_log = y_axis_log, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, median_size = median_size, plot_boxplot = plot_boxplot, cutoff_line_width = cutoff_line_width, ...) - - UMI_plot <- QC_Plots_UMIs(seurat_object = seurat_object, group.by = group.by, low_cutoff = UMI_cutoffs[1], high_cutoff = UMI_cutoffs[2], pt.size = pt.size, colors_use = colors_use, x_lab_rotate = x_lab_rotate, y_axis_log = y_axis_log, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, median_size = median_size, plot_boxplot = plot_boxplot, cutoff_line_width = cutoff_line_width, ...) - - mito_plot <- QC_Plots_Mito(seurat_object = seurat_object, group.by = group.by, mito_name = mito_name, low_cutoff = mito_cutoffs[1], high_cutoff = mito_cutoffs[2], pt.size = pt.size, colors_use = colors_use, x_lab_rotate = x_lab_rotate, y_axis_log = y_axis_log, raster = raster, ggplot_default_colors = ggplot_default_colors, color_seed = color_seed, plot_median = plot_median, median_size = median_size, plot_boxplot = plot_boxplot, cutoff_line_width = cutoff_line_width, ...) + feature_plot <- QC_Plots_Genes(seurat_object = seurat_object, + group.by = group.by, + low_cutoff = feature_cutoffs[1], + high_cutoff = feature_cutoffs[2], + pt.size = pt.size, + colors_use = colors_use, + x_lab_rotate = x_lab_rotate, + y_axis_log = y_axis_log, + raster = raster, + ggplot_default_colors = ggplot_default_colors, + color_seed = color_seed, + plot_median = plot_median, + median_size = median_size, + plot_boxplot = plot_boxplot, + cutoff_linewidth = cutoff_linewidth, + ...) + + UMI_plot <- QC_Plots_UMIs(seurat_object = seurat_object, + group.by = group.by, + low_cutoff = UMI_cutoffs[1], + high_cutoff = UMI_cutoffs[2], + pt.size = pt.size, + colors_use = colors_use, + x_lab_rotate = x_lab_rotate, + y_axis_log = y_axis_log, + raster = raster, + ggplot_default_colors = ggplot_default_colors, + color_seed = color_seed, + plot_median = plot_median, + median_size = median_size, + plot_boxplot = plot_boxplot, + cutoff_linewidth = cutoff_linewidth, + ...) + + mito_plot <- QC_Plots_Mito(seurat_object = seurat_object, + group.by = group.by, + mito_name = mito_name, + low_cutoff = mito_cutoffs[1], + high_cutoff = mito_cutoffs[2], + pt.size = pt.size, + colors_use = colors_use, + x_lab_rotate = x_lab_rotate, + y_axis_log = y_axis_log, + raster = raster, + ggplot_default_colors = ggplot_default_colors, + color_seed = color_seed, + plot_median = plot_median, + median_size = median_size, + plot_boxplot = plot_boxplot, + cutoff_linewidth = cutoff_linewidth, + ...) # wrap plots plots <- wrap_plots(feature_plot, UMI_plot, mito_plot, ncol = 3) @@ -562,7 +725,9 @@ QC_Plots_Combined_Vln <- function( #' @param features Feature from meta.data, assay features, or feature name shortcut to plot. #' @param low_cutoff Plot line a potential low threshold for filtering. #' @param high_cutoff Plot line a potential high threshold for filtering. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param split.by Feature to split plots by (i.e. "orig.ident"). #' @param bins number of bins to plot default is 250. #' @param colors_use color to fill histogram bars, default is "dodgerblue". @@ -593,18 +758,28 @@ QC_Plots_Combined_Vln <- function( QC_Histogram <- function( seurat_object, - features, - low_cutoff = NULL, - high_cutoff = NULL, - cutoff_line_width = NULL, - split.by = NULL, - bins = 250, - colors_use = "dodgerblue", - num_columns = NULL, - plot_title = NULL, - assay = NULL, - print_defaults = FALSE + features, + low_cutoff = NULL, + high_cutoff = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, + split.by = NULL, + bins = 250, + colors_use = "dodgerblue", + num_columns = NULL, + plot_title = NULL, + assay = NULL, + print_defaults = FALSE ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Histogram(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -653,6 +828,12 @@ QC_Histogram <- function( plot_titles <- all_found_features } + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + # Plot if (is.null(x = split.by)) { plot_list <- lapply(1:length(x = all_found_features), function(x) { @@ -660,7 +841,7 @@ QC_Histogram <- function( plot <- ggplot(data = data_to_plot, aes(x = .data[[all_found_features[x]]])) + geom_histogram(color = "black", fill = colors_use, bins = bins) + theme_cowplot() + - geom_vline(xintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + + geom_vline(xintercept = c(low_cutoff, high_cutoff), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + ggtitle(plot_titles[x]) }) @@ -726,7 +907,9 @@ QC_Histogram <- function( #' @param high_cutoff_gene Plot line a potential high threshold for filtering genes per cell. #' @param low_cutoff_UMI Plot line a potential low threshold for filtering UMIs per cell. #' @param high_cutoff_UMI Plot line a potential high threshold for filtering UMIs per cell. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param colors_use vector of colors to use for plotting by identity. #' @param meta_gradient_name Name of continuous meta data variable to color points in plot by. #' (MUST be continuous variable i.e. "percent_mito"). @@ -784,7 +967,8 @@ QC_Plot_UMIvsGene <- function( high_cutoff_gene = Inf, low_cutoff_UMI = -Inf, high_cutoff_UMI = Inf, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, meta_gradient_name = NULL, meta_gradient_color = viridis_plasma_dark_high, @@ -803,6 +987,15 @@ QC_Plot_UMIvsGene <- function( shuffle_seed = 1, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plot_UMIvsGene(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -844,6 +1037,12 @@ QC_Plot_UMIvsGene <- function( } } + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + if (isFALSE(x = ident_legend) && isFALSE(x = combination)) { cli_warn(message = "{.code ident_legend} parameter ignored as {.code combination = FALSE}") } @@ -906,8 +1105,8 @@ QC_Plot_UMIvsGene <- function( scale_color_gradientn(colors = meta_gradient_color, limits = c(meta_gradient_low_cutoff, NA), na.value = meta_gradient_na_color) + theme_cowplot() + theme(plot.title = element_text(hjust = 0.5)) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle("Genes vs. UMIs per Cell/Nucleus", subtitle = c(paste0("Correlation of full dataset is: ", plot_cor_full, ".", "\nCorrelation of filtered dataset would be: ", plot_cor_filtered, ". ", "\nThe low cutoff for plotting ", meta_gradient_name, " is: ", meta_cutoff_reported))) @@ -918,8 +1117,8 @@ QC_Plot_UMIvsGene <- function( scale_color_gradientn(colors = meta_gradient_color, limits = c(meta_gradient_low_cutoff, NA), na.value = meta_gradient_na_color) + theme_cowplot() + theme(plot.title = element_text(hjust = 0.5)) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle("Genes vs. UMIs per Cell/Nucleus", subtitle = c(paste0("Correlation of full dataset is: ", plot_cor_full, ".", "\nCorrelation of filtered dataset would be: ", plot_cor_filtered, ". ", "\nThe low cutoff for plotting ", meta_gradient_name, " is: ", meta_cutoff_reported))) @@ -928,8 +1127,8 @@ QC_Plot_UMIvsGene <- function( # Plot by identity if (is.null(x = meta_gradient_name) && isFALSE(x = combination)) { p1 <- FeatureScatter(object = seurat_object, feature1 = nCount, feature2 = nFeature, cells = cells, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle("Genes vs. UMIs per Cell/Nucleus", subtitle = c(paste0("Correlation of full dataset is: ", plot_cor_full, ".", "\nCorrelation of filtered dataset would be: ", plot_cor_filtered, "."))) @@ -939,8 +1138,8 @@ QC_Plot_UMIvsGene <- function( if (isTRUE(x = combination)) { # Plot by identity p1 <- FeatureScatter(object = seurat_object, feature1 = nCount, feature2 = nFeature, cells = cells, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + ggtitle("") @@ -955,8 +1154,8 @@ QC_Plot_UMIvsGene <- function( scale_color_gradientn(colors = meta_gradient_color, limits = c(meta_gradient_low_cutoff, NA), na.value = meta_gradient_na_color) + theme_cowplot() + theme(plot.title = element_text(hjust = 0.5)) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) } else { @@ -965,8 +1164,8 @@ QC_Plot_UMIvsGene <- function( scale_color_gradientn(colors = meta_gradient_color, limits = c(meta_gradient_low_cutoff, NA), na.value = meta_gradient_na_color) + theme_cowplot() + theme(plot.title = element_text(hjust = 0.5)) + - geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + geom_hline(yintercept = c(if(is.finite(x = low_cutoff_gene)) {low_cutoff_gene}, if(is.finite(x = high_cutoff_gene)) {high_cutoff_gene}), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(if(is.finite(x = low_cutoff_UMI)) {low_cutoff_UMI}, if(is.finite(x = high_cutoff_UMI)) {high_cutoff_UMI}), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) } @@ -990,7 +1189,9 @@ QC_Plot_UMIvsGene <- function( #' @param high_cutoff_gene Plot line a potential high threshold for filtering genes per cell. #' @param low_cutoff_feature Plot line a potential low threshold for filtering feature1 per cell. #' @param high_cutoff_feature Plot line a potential high threshold for filtering feature1 per cell. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param colors_use vector of colors to use for plotting by identity. #' @param pt.size Adjust point size for plotting. #' @param group.by Name of one or more metadata columns to group (color) cells by (for example, orig.ident). @@ -1031,7 +1232,8 @@ QC_Plot_GenevsFeature <- function( high_cutoff_gene = NULL, low_cutoff_feature = NULL, high_cutoff_feature = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, pt.size = 1, group.by = NULL, @@ -1043,6 +1245,15 @@ QC_Plot_GenevsFeature <- function( shuffle_seed = 1, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plot_GenevsFeature(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -1081,12 +1292,20 @@ QC_Plot_GenevsFeature <- function( } } + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + # Plot - FeatureScatter(object = seurat_object, feature1 = feature1, feature2 = nFeature, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + - geom_hline(yintercept = c(low_cutoff_gene, high_cutoff_gene), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(low_cutoff_feature, high_cutoff_feature), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + plot <- FeatureScatter(object = seurat_object, feature1 = feature1, feature2 = nFeature, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + + geom_hline(yintercept = c(low_cutoff_gene, high_cutoff_gene), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(low_cutoff_feature, high_cutoff_feature), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + + return(plot) } @@ -1102,7 +1321,9 @@ QC_Plot_GenevsFeature <- function( #' @param high_cutoff_UMI Plot line a potential high threshold for filtering UMI per cell. #' @param low_cutoff_feature Plot line a potential low threshold for filtering feature1 per cell. #' @param high_cutoff_feature Plot line a potential high threshold for filtering feature1 per cell. -#' @param cutoff_line_width numerical value for thickness of cutoff lines, default is NULL. +#' @param cutoff_line_width `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. +#' @param cutoff_linewidth numerical value for thickness of cutoff lines, +#' default is NULL, uses ggplot2 defaults. #' @param colors_use vector of colors to use for plotting by identity. #' @param pt.size Adjust point size for plotting. #' @param group.by Name of one or more metadata columns to group (color) cells by (for example, orig.ident). @@ -1143,7 +1364,8 @@ QC_Plot_UMIvsFeature <- function( high_cutoff_UMI = NULL, low_cutoff_feature = NULL, high_cutoff_feature = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, pt.size = 1, group.by = NULL, @@ -1155,6 +1377,15 @@ QC_Plot_UMIvsFeature <- function( shuffle_seed = 1, ... ) { + # check deprecation + if (is_present(cutoff_line_width)) { + deprecate_warn(when = "3.5.0", + what = "QC_Plot_UMIvsFeature(cutoff_line_width)", + details = c("i" = "The {.code cutoff_line_width} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- cutoff_line_width + } + # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -1193,10 +1424,18 @@ QC_Plot_UMIvsFeature <- function( } } + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + # Plot - FeatureScatter(object = seurat_object, feature1 = feature1, feature2 = nCount, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + - geom_hline(yintercept = c(low_cutoff_UMI, high_cutoff_UMI), linetype = "dashed", color = "red", linewidth = cutoff_line_width) + - geom_vline(xintercept = c(low_cutoff_feature, high_cutoff_feature), linetype = "dashed", color = "blue", linewidth = cutoff_line_width) + + plot <- FeatureScatter(object = seurat_object, feature1 = feature1, feature2 = nCount, pt.size = pt.size, shuffle = TRUE, raster = raster, raster.dpi = raster.dpi, cols = colors_use, group.by = group.by, seed = shuffle_seed, ...) + + geom_hline(yintercept = c(low_cutoff_UMI, high_cutoff_UMI), linetype = "dashed", color = "red", linewidth = cutoff_linewidth) + + geom_vline(xintercept = c(low_cutoff_feature, high_cutoff_feature), linetype = "dashed", color = "blue", linewidth = cutoff_linewidth) + xlab(x_axis_label) + ylab(y_axis_label) + + return(plot) } diff --git a/R/Plotting_Seurat.R b/R/Plotting_Seurat.R index 597a6fcdc..2ae4f5f5e 100644 --- a/R/Plotting_Seurat.R +++ b/R/Plotting_Seurat.R @@ -2188,7 +2188,14 @@ DimPlot_scCustom <- function( if (is.null(x = group.by)) { levels_overall <- levels(x = Idents(object = seurat_object)) } else { - levels_overall <- levels(x = seurat_object@meta.data[[group.by]]) + if (inherits(x = seurat_object@meta.data[[group.by]], what = "factor")) { + levels_overall <- levels(x = seurat_object@meta.data[[group.by]]) + } else { + cli_inform(message = c("The variable {.field {group.by}} is not a factor. Converting for plot.", + "i" = "To avoid this warning set meta.data column to factor before plotting.")) + seurat_object@meta.data[[group.by]] <- factor(seurat_object@meta.data[[group.by]]) + levels_overall <- levels(x = seurat_object@meta.data[[group.by]]) + } } if (length(x = levels_overall) > length(x = colors_use)) { @@ -2197,7 +2204,9 @@ DimPlot_scCustom <- function( colors_overall <- colors_use - names(x = colors_overall) <- levels_overall + if (is.null(x = names(x = colors_overall))) { + names(x = colors_overall) <- levels_overall + } # plot plots <- lapply(1:length(x = split_by_list), function(x) { @@ -2666,9 +2675,10 @@ FeatureScatter_scCustom <- function( #' @param ndims The number of dims to plot. Default is NULL and will plot all dims #' @param reduction The reduction to use, default is "pca" #' @param calc_cutoffs logical, whether or not to calculate the cutoffs, default is TRUE. -#' @param plot_cutoffs lgoical, whether to plot the cutoffs as vertical lines on plot, default is TRUE. +#' @param plot_cutoffs logical, whether to plot the cutoffs as vertical lines on plot, default is TRUE. #' @param line_colors colors for the cutoff lines, default is c("dodgerblue", "firebrick"). -#' @param linewidth widith of the cutoff lines, default is 0.5. +#' @param cutoff_linewidth width of the cutoff lines, default is NULL, uses ggplot2 default. +#' @param linewidth `r lifecycle::badge("soft-deprecated")`. See `cutoff_linewidth`. #' #' @references Modified from following: \url{https://hbctraining.github.io/scRNA-seq/lessons/elbow_plot_metric.html}. #' @@ -2691,8 +2701,18 @@ ElbowPlot_scCustom <- function( calc_cutoffs = TRUE, plot_cutoffs = TRUE, line_colors = c("dodgerblue", "firebrick"), - linewidth = 0.5 + cutoff_linewidth = NULL, + linewidth = deprecated() ) { + # check deprecation + if (is_present(linewidth)) { + deprecate_warn(when = "3.5.0", + what = "ElbowPlot_scCustom(linewidth)", + details = c("i" = "The {.code linewidth} parameter is soft-deprecated. Please update code to use `cutoff_linewidth` instead.") + ) + cutoff_linewidth <- linewidth + } + # check seurat Is_Seurat(seurat_object = seurat_object) @@ -2734,6 +2754,12 @@ ElbowPlot_scCustom <- function( cli_abort(message = "The number of values provided to {.code line_colors} must be either 1 or 2.") } + # set default `linewidth` when ggplot2 >= 4.0.0 to avoid empty aesthetic warnings + # 0.6365 is as close to default as I can approximate + if (is.null(x = cutoff_linewidth) && packageVersion(pkg = "ggplot2") >= "4.0.0") { + cutoff_linewidth <- 0.6365 + } + # Create plot plot <- ElbowPlot(seurat_object, ndims = ndims, reduction = reduction) diff --git a/R/Plotting_Statistics.R b/R/Plotting_Statistics.R index 0abaf8cd6..1a28e3704 100644 --- a/R/Plotting_Statistics.R +++ b/R/Plotting_Statistics.R @@ -645,6 +645,11 @@ Plot_Median_Other <- function( #' @param x_axis_label Label for x axis. #' @param legend_title Label for plot legend. #' @param x_lab_rotate logical. Whether to rotate the axes labels on the x-axis. Default is FALSE. +#' @param reorder logical, if plotting by sample should x-axis be reordered according to number of cells, +#' default is FALSE. +#' @param reorder_decreasing logical, if `reorder = TRUE` should points be ordered from fewest to +#' greatest number of cells (FALSE) or reverse (TRUE), default is FALSE. +#' @param plot_median logical, if plotting by sample should line be added showing median, default is TRUE. #' @param color_seed random seed for the "varibow" palette shuffle if `colors_use = NULL` and number of #' groups plotted is greater than 36. Default = 123. #' @@ -661,22 +666,33 @@ Plot_Median_Other <- function( #' #' @examples #' \dontrun{ -#' Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "Treatment") +#' # Plot cells per sample grouped by "Diagnosis" +#' Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "Diagnosis") +#' +#' # Plot cells per sample individually +#' Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "orig.ident") +#' +#' #' # Plot cells per sample individually and reorder x-axis by cell number +#' Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "orig.ident", order = TRUE) +#' #' } #' Plot_Cells_per_Sample <- function( - seurat_object, - sample_col = "orig.ident", - group.by = NULL, - colors_use = NULL, - dot_size = 1, - plot_title = "Cells/Nuclei per Sample", - y_axis_label = "Number of Cells", - x_axis_label = NULL, - legend_title = NULL, - x_lab_rotate = TRUE, - color_seed = 123 + seurat_object, + sample_col = "orig.ident", + group.by = NULL, + colors_use = NULL, + dot_size = 1, + plot_title = "Cells/Nuclei per Sample", + y_axis_label = "Number of Cells", + x_axis_label = NULL, + legend_title = NULL, + x_lab_rotate = TRUE, + reorder = FALSE, + reorder_decreasing = FALSE, + plot_median = TRUE, + color_seed = 123 ) { # Check Seurat Is_Seurat(seurat_object = seurat_object) @@ -730,15 +746,44 @@ Plot_Cells_per_Sample <- function( } } - # Generate base plot - plot <- ggplot(data = merged, mapping = aes(x = .data[[group.by]], y = .data[["Number_of_Cells"]], fill = .data[[group.by]])) + - geom_boxplot(fill = "white") + - geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + - scale_fill_manual(values = colors_use) + - theme_ggprism_mod() + - ggtitle(plot_title) + - ylab(y_axis_label) + - xlab("") + if (nrow(x = unique(x = seurat_object[[group.by]])) == nrow(x = unique(x = seurat_object[[sample_col]]))) { + # create sample binwidth to avoid printing irrelevent warning + sample_binwidth <- (max(merged[["Number_of_Cells"]]) - min(merged[["Number_of_Cells"]])) * 1/30 + + if (isFALSE(x = reorder)) { + plot <- ggplot(data = merged, mapping = aes(x = .data[[group.by]], y = .data[["Number_of_Cells"]], fill = .data[[group.by]])) + + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size, binwidth = sample_binwidth) + + scale_fill_manual(values = colors_use) + + theme_ggprism_mod() + + ggtitle(plot_title) + + ylab(y_axis_label) + + xlab("") + } else { + plot <- ggplot(data = merged, mapping = aes(x = reorder(.data[[group.by]], .data[["Number_of_Cells"]], decreasing = reorder_decreasing), y = .data[["Number_of_Cells"]], fill = .data[[group.by]])) + + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size, binwidth = sample_binwidth) + + scale_fill_manual(values = colors_use) + + theme_ggprism_mod() + + ggtitle(plot_title) + + ylab(y_axis_label) + + xlab("") + } + if (isTRUE(x = plot_median)) { + plot <- plot + geom_hline(yintercept = median(merged[["Number_of_Cells"]])) + } + } else { + if (isTRUE(x = reorder) || isFALSE(x = plot_median) || isTRUE(x = reorder_decreasing)) { + cli_warn(message = "The {.code reorder}, {.code plot_median}, and {.code reorder_decreasing} parameters were ignored as they are only valid if samples are not grouped by additional variable.") + } + # Generate base plot + plot <- ggplot(data = merged, mapping = aes(x = .data[[group.by]], y = .data[["Number_of_Cells"]], fill = .data[[group.by]])) + + geom_boxplot(fill = "white") + + geom_dotplot(binaxis ='y', stackdir = 'center', dotsize = dot_size) + + scale_fill_manual(values = colors_use) + + theme_ggprism_mod() + + ggtitle(plot_title) + + ylab(y_axis_label) + + xlab("") + } # Modify base plot if (isTRUE(x = x_lab_rotate)) { @@ -753,6 +798,10 @@ Plot_Cells_per_Sample <- function( plot <- plot + labs(fill = legend_title) } + if (length(x = unique(seurat_object[[group.by]])) == length(unique(seurat_object[[sample_col]]))) { + plot <- plot & NoLegend() + } + # Return plot return(plot) } diff --git a/R/Read_Write_Data.R b/R/Read_Write_Data.R index 131ad7d86..4612d0e4f 100644 --- a/R/Read_Write_Data.R +++ b/R/Read_Write_Data.R @@ -502,8 +502,6 @@ Read10X_GEO <- function( #' @import mcprogress #' @import parallel #' @import pbapply -#' @importFrom Matrix readMM -#' @importFrom utils read.delim txtProgressBar setTxtProgressBar #' #' @export #' @@ -691,7 +689,7 @@ Read10X_Multi_Directory <- function( if (isTRUE(x = parallel)) { cli_inform(message = c("NOTE: Parallel processing may not report informative error messages.", "i" = "If function fails set {.code parallel = FALSE} and re-run for informative error reporting.")) - # *** Here is where the swap of mclapply or pbmclapply is occuring *** + raw_data_list <- pmclapply(mc.cores = num_cores, 1:length(x = sample_list), function(x) { if (isTRUE(x = cellranger_multi)) { file_path <- file.path(base_path, sample_list[x], secondary_path, sample_list[x], multi_extra_path) @@ -767,7 +765,6 @@ Read10X_Multi_Directory <- function( #' @import pbapply #' @importFrom Seurat Read10X_h5 #' @importFrom stringr str_extract -#' @importFrom utils txtProgressBar setTxtProgressBar #' #' @export #' @@ -842,7 +839,7 @@ Read10X_h5_Multi_Directory <- function( if (isTRUE(x = parallel)) { cli_inform(message = c("NOTE: Parallel processing may not report informative error messages.", "i" = "If function fails set {.code parallel = FALSE} and re-run for informative error reporting.")) - # *** Here is where the swap of mclapply or pbmclapply is occuring *** + raw_data_list <- pmclapply(mc.cores = num_cores, 1:length(x = sample_list), function(x) { if (isTRUE(x = cellranger_multi)) { file_path <- file.path(base_path, sample_list[x], secondary_path, sample_list[x], multi_extra_path, h5_filename) @@ -1534,6 +1531,417 @@ Read_CellBender_h5_Multi_File <- function( } + +#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +#################### READ loom DATA #################### +#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +#' Read Loom Files +#' +#' Internalfunction to read velocyto loom files using hdf5r package. +#' +#' @param loom_file loom file to read +#' +#' @return list of sparse matrices containing spliced, unspliced, and ambiguous counts +#' @noRd +#' @keywords internal +#' +#' @references Function is updated from velocyto.R `read.loom.matrices` \url{https://github.com/velocyto-team/velocyto.R}. +#' Function included in scCustomize to avoid installation issues related to other aspects of +#' velocyto.R package. +#' + +ReadLoomMatrices <- function( + loom_file, + gene_symbol = TRUE, + verbose = TRUE +) { + # Check hdf5r installed + hdf5r_check <- is_installed(pkg = "hdf5r") + if (isFALSE(x = hdf5r_check)) { + cli_abort(message = c( + "Please install the {.val hdf5r} package to use {.code Read_CellBender_h5_Mat} and read HDF5 files.", + "i" = "This can be accomplished with the following commands: ", + "----------------------------------------", + "{.field `install.packages({symbol$dquote_left}hdf5r{symbol$dquote_right})`}", + "----------------------------------------" + )) + } + + f <- hdf5r::H5File$new(loom_file, mode='r') + cells <- f[["col_attrs/CellID"]][] + if (isTRUE(x = gene_symbol)) { + genes <- f[["row_attrs/Gene"]][] + } else { + genes <- f[["row_attrs/Accession"]][] + } + + dl <- c(spliced="layers/spliced", + unspliced="layers/unspliced", + ambiguous="layers/ambiguous") + if("layers/spanning" %in% hdf5r::list.datasets(f)) { + dl <- c(dl, c(spanning="layers/spanning")) + } + + dlist <- lapply(dl, function(path) { + m <- as.sparse(t(f[[path]][,])) + rownames(x = m) <- genes; colnames(x = m) <- cells; + return(m) + }) + f$close_all() + + # check unique and edit gene names/ids if needed + num_dup <- sum(duplicated(x = rownames(x = dlist[["spliced"]]))) + + if (num_dup > 0) { + if (isTRUE(x = verbose)) { + cli_inform(message = c("A total of {.field {num_dup}} duplicate row names were found.", + "i" = "Making unique with {.code make.unique()}.")) + } + + rownames(dlist[["spliced"]]) <- make.unique(names = rownames(dlist[["spliced"]])) + rownames(dlist[["unspliced"]]) <- make.unique(names = rownames(dlist[["unspliced"]])) + rownames(dlist[["ambiguous"]]) <- make.unique(names = rownames(dlist[["ambiguous"]])) + } + + return(dlist) +} + + +#' Read multiple loom files from same directory +#' +#' Internal wrapper to be used be `Read_Velocity` if data directory is provided. +#' +#' @param data_dir Directory containing the loom files provided by velocyto. +#' @param gene_symbol logical, should rownames of returned matrices have gene symbols or accession ID #s, +#' default is TRUE (symbols). +#' @param sort_type logical, default is FALSE and will return list with 1 sample per entry. Each +#' sample entry will contain 3 matrices (spliced, unspliced, ambiguous). If TRUE will return list of +#' 3 matrix types (spliced, unspliced, ambiguous) with one entry per sample +#' @param sample_list A vector of file prefixes/names if specific samples are desired. Default is `NULL` and +#' will load all samples in given directory. +#' @param sample_names a set of sample names to use for each sample entry in returned list. If `NULL` +#' will set names to the file name of each sample. +#' @param shared_suffix a suffix and file extension shared by all samples. +#' @param parallel logical (default FALSE). Whether to use multiple cores when reading in data. +#' Only possible on Linux based systems. +#' @param num_cores if `parallel = TRUE` indicates the number of cores to use for multicore processing. +#' +#' @returns list of list of matrices +#' @noRd +#' @keywords internal +#' +#' @import mcprogress +#' @import parallel +#' @import pbapply +#' + +ReadVelocity_Multi_File_Internal <- function( + data_dir = NULL, + gene_symbol = TRUE, + sort_type = FALSE, + sample_list = NULL, + sample_names = NULL, + shared_suffix = NULL, + parallel = FALSE, + num_cores = NULL +) { + if (!dir.exists(paths = data_dir)) { + cli_abort(message = "Directory provided does not exist") + } + if (length(x = data_dir) > 1) { + cli_abort(message = "{.code Read_Velocity} only supports reading from single data directory at a time.") + } + + # Confirm num_cores specified + if (isTRUE(x = parallel) && is.null(x = num_cores)) { + cli_abort("If {.code parallel = TRUE} then {.code num_cores} must be specified.") + } + + file.list <- list.files(path = data_dir, pattern = ".loom", full.names = FALSE) + + # Remove file suffix if provided + if (!is.null(x = shared_suffix)) { + shared_suffix <- gsub(pattern = ".loom", replacement = "", x = shared_suffix) + } + + if (is.null(x = sample_list)) { + if (is.null(x = shared_suffix)) { + sample_list <- gsub(pattern = ".loom", x = file.list, replacement = "") + } else { + sample_list <- gsub(pattern = paste0(shared_suffix, ".loom"), x = file.list, replacement = "") + } + } + + # Check sample_names length is ok + if (!is.null(x = sample_names) && length(x = sample_names) != length(x = sample_list)) { + cli_abort(message = "Length of {.code sample_names} {.field {length(x = sample_names)}} must be equal to number of samples {.field {length(x = sample_list)}}.") + } + + cli_inform(message = "{.field Reading Loom files from directory}") + pboptions(char = "=") + if (isTRUE(x = parallel)) { + cli_inform(message = c("NOTE: Parallel processing may not report informative error messages.", + "i" = "If function fails set {.code parallel = FALSE} and re-run for informative error reporting.")) + raw_data_list <- pmclapply(mc.cores = num_cores, 1:length(x = sample_list), function(i) { + loom_loc <- file.path(data_dir, paste0(sample_list[i], shared_suffix, ".loom")) + data <- ReadLoomMatrices(loom_file = loom_loc, gene_symbol = gene_symbol, verbose = FALSE) + }) + } else { + raw_data_list <- pblapply(1:length(x = sample_list), function(i) { + loom_loc <- file.path(data_dir, paste0(sample_list[i], shared_suffix, ".loom")) + data <- ReadLoomMatrices(loom_file = loom_loc, gene_symbol = gene_symbol, verbose = FALSE) + }) + } + + # add call to report duplicates single time + reporter_file_path <- file.path(data_dir, paste0(sample_list[1], shared_suffix, ".loom")) + reporter_data <- ReadLoomMatrices(loom_file = reporter_file_path, gene_symbol = gene_symbol, verbose = TRUE) + + # Name the matrices + if (is.null(x = sample_names)) { + names(x = raw_data_list) <- sample_list + } else { + names(x = raw_data_list) <- sample_names + } + + # sort matrices by read type + if (isTRUE(x = sort_type)) { + spliced_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["spliced"]] + }) + names(x = spliced_list) <- names(x = raw_data_list) + + unspliced_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["unspliced"]] + }) + names(x = unspliced_list) <- names(x = raw_data_list) + + ambiguous_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["ambiguous"]] + }) + names(x = ambiguous_list) <- names(x = raw_data_list) + + raw_data_list <- list("spliced" = spliced_list, + "unspliced" = unspliced_list, + "ambiguous" = ambiguous_list) + } + + # return object + return(raw_data_list) +} + + +#' Read loom files from multiple directories +#' +#' Wrapper to read loom files from multiple directory and return a list +#' +#' @param base_path path to the parent directory which contains all of the subdirectories of interest. +#' @param secondary_path path from the parent directory to loom files for each sample. +#' @param gene_symbol logical, should rownames of returned matrices have gene symbols or accession ID #s, +#' default is TRUE (symbols). +#' @param sort_type logical, default is FALSE and will return list with 1 sample per entry. Each +#' sample entry will contain 3 matrices (spliced, unspliced, ambiguous). If TRUE will return list of +#' 3 matrix types (spliced, unspliced, ambiguous) with one entry per sample +#' @param sample_list A vector of file prefixes/names if specific samples are desired. Default is `NULL` and +#' will load all samples in given directory. +#' @param sample_names a set of sample names to use for each sample entry in returned list. If `NULL` +#' will set names to the file name of each sample. +#' @param shared_suffix a suffix and file extension shared by all samples. +#' @param parallel logical (default FALSE). Whether to use multiple cores when reading in data. +#' Only possible on Linux based systems. +#' @param num_cores if `parallel = TRUE` indicates the number of cores to use for multicore processing. +#' +#' @returns list of list of matrices +#' @noRd +#' @keywords internal +#' +#' @import mcprogress +#' @import parallel +#' @import pbapply +#' + +ReadVelocity_Multi_Directory <- function( + base_path, + secondary_path = NULL, + gene_symbol = TRUE, + sort_type = FALSE, + sample_list = NULL, + sample_names = NULL, + parallel = FALSE, + num_cores = NULL +) { + # Confirm num_cores specified + if (isTRUE(x = parallel) && is.null(x = num_cores)) { + cli_abort("If {.code parallel = TRUE} then {.code num_cores} must be specified.") + } + # Confirm directory exists + if (dir.exists(paths = base_path) == FALSE) { + cli_abort(message = "Directory: {.val {base_path}} specified by {.code base_path} does not exist.") + } + # Detect libraries if sample_list is NULL + if (is.null(x = sample_list)) { + sample_list <- Pull_Directory_List(base_path = base_path) + } + + # set "" if no secondary path + if (is.null(x = secondary_path)) { + secondary_path <- "" + } + # Check if full directory path exists + for (i in 1:length(x = sample_list)) { + full_directory_path <- file.path(base_path, sample_list[i], secondary_path) + if (dir.exists(paths = full_directory_path) == FALSE) { + cli_abort(message = "Full Directory does not exist {.val {full_directory_path}} was not found.") + } + } + + # read data + cli_inform(message = "{.field Reading Loom files.}") + if (isTRUE(x = parallel)) { + cli_inform(message = c("NOTE: Parallel processing may not report informative error messages.", + "i" = "If function fails set {.code parallel = FALSE} and re-run for informative error reporting.")) + # if parallel + raw_data_list <- pmclapply(mc.cores = num_cores, 1:length(x = sample_list), function(x) { + file_path <- file.path(base_path, sample_list[x], secondary_path, paste0(sample_list[x], ".loom")) + raw_data <- ReadLoomMatrices(loom_file = file_path, gene_symbol = gene_symbol, verbose = FALSE) + return(raw_data) + }) + } else { + raw_data_list <- pblapply(1:length(x = sample_list), function(x) { + file_path <- file.path(base_path, sample_list[x], secondary_path, paste0(sample_list[x], ".loom")) + raw_data <- ReadLoomMatrices(loom_file = file_path, gene_symbol = gene_symbol, verbose = FALSE) + }) + } + + # add call to report duplicates single time + reporter_file_path <- file.path(base_path, sample_list[1], secondary_path, paste0(sample_list[1], ".loom")) + reporter_data <- ReadLoomMatrices(loom_file = reporter_file_path, gene_symbol = gene_symbol, verbose = TRUE) + + # Name the list items + if (is.null(x = sample_names)) { + names(x = raw_data_list) <- sample_list + } else { + names(x = raw_data_list) <- sample_names + } + + # sort matrices by read type + if (isTRUE(x = sort_type)) { + spliced_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["spliced"]] + }) + names(x = spliced_list) <- names(x = raw_data_list) + + unspliced_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["unspliced"]] + }) + names(x = unspliced_list) <- names(x = raw_data_list) + + ambiguous_list <- lapply(1:length(x = raw_data_list), function(x){ + data <- testing[[x]][["ambiguous"]] + }) + names(x = ambiguous_list) <- names(x = raw_data_list) + + raw_data_list <- list("spliced" = spliced_list, + "unspliced" = unspliced_list, + "ambiguous" = ambiguous_list) + } + return(raw_data_list) +} + + +#' Load RNA Velocity results +#' +#' Wrapper function to +#' +#' @param loom_file path and name of loom file to read +#' @param data_dir path to data directory containing all loom files to read +#' @param gene_symbol logical, should row names of returned matrices have gene symbols or accession ID #s, +#' default is TRUE (symbols). +#' @param sort_type logical, default is FALSE and will return list with 1 sample per entry. Each +#' sample entry will contain 3 matrices (spliced, unspliced, ambiguous). If TRUE will return list of +#' 3 matrix types (spliced, unspliced, ambiguous) with one entry per sample +#' @param sample_list A vector of file prefixes/names if specific samples are desired. Default is `NULL` and +#' will load all samples in given directory. +#' @param sample_names a set of sample names to use for each sample entry in returned list. If `NULL` +#' will set names to the file name of each sample. +#' @param shared_suffix a suffix and file extension shared by all samples. +#' @param parallel logical (default FALSE). Whether to use multiple cores when reading in data. +#' Only possible on Linux based systems. +#' @param num_cores if `parallel = TRUE` indicates the number of cores to use for multi-core processing. +#' +#' @return list of sparse matrices containing spliced, unspliced, and ambiguous counts +#' +#' @export +#' +#' @references Function is updated from `SeuratWrappers::ReadVelocity` +#' \url{https://github.com/satijalab/seurat-wrappers/blob/master/R/velocity.R} (License: GPL-3). +#' Function included in scCustomize to avoid installation issues related to other aspects of +#' velocyto.R package which `SeuratWrappers::ReadVelocity` requires. +#' scCustomize version also adds multi-file and multi-directory support, ability to return Ensembl IDs, +#' and multi-core parallel file reading. +#' +#' +#' @examples +#' \dontrun{ +#' # Read single velocity loom file +#' velo_res <- Read_Velocity(loom_file = "PATH/sample01.loom") +#' +#' # Read single velocity loom file with ensembl IDs +#' velo_res <- Read_Velocity(loom_file = "PATH/sample01.loom", gene_symbol = FALSE) +#' +#' # Read multiple files from a parent directory with many subdirectories & return 1 list entry per sample +#' # Each entry will contain 3 matrices (spliced, unspliced, ambiguous) +#' velo_res_list <- Read_Velocity(loom_file = "PATH/", secondary_path = "SEC_PATH/") +#' +#' # Sort returned list by read type instead of by sample +#' # list will contain 3 entries (spliced, unspliced, ambiguous) +#' # each entry will contain 1 matrix per sample +#' velo_res_list <- Read_Velocity(loom_file = "PATH/", secondary_path = "SEC_PATH/", sort_type = TRUE) +#' +#' # Read multiple files from a single directory +#' velo_res_list <- Read_Velocity(loom_file = "PATH/", multi_dir = FALSE) +#' } + +Read_Velocity <- function( + loom_file = NULL, + data_dir = NULL, + multi_dir = TRUE, + gene_symbol = TRUE, + sort_type = FALSE, + sample_list = NULL, + sample_names = NULL, + shared_suffix = NULL, + parallel = FALSE, + num_cores = NULL +) { + if (!is.null(x = loom_file) && !is.null(x = data_dir)) { + cli_abort(message = "Cannot specify values for both {.code loom_file} and {.code data_dir}.") + } + + if (!is.null(x = loom_file)) { + invisible(x = capture.output(data <- ReadLoomMatrices( + loom_file = loom_file, + gene_symbol = gene_symbol, + verbose = TRUE + ))) + return(data) + } + # single data directory + if (isFALSE(x = multi_dir)) { + data_list <- ReadVelocity_Multi_File_Internal(data_dir = data_dir, gene_symbol = gene_symbol, sample_list = sample_list, sample_names = sample_names, shared_suffix = shared_suffix, parallel = parallel, num_cores = num_cores, sort_type = sort_type) + return(data_list) + } + + # multi directory + if (isTRUE(x = multi_dir)) { + data_list <- ReadVelocity_Multi_Dir_Internal(data_dir = data_dir, gene_symbol = gene_symbol, sample_list = sample_list, sample_names = sample_names, shared_suffix = shared_suffix, parallel = parallel, num_cores = num_cores, sort_type = sort_type) + return(data_list) + } +} + + #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% #################### READ OTHER DATA #################### #%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/R/Utilities.R b/R/Utilities.R index 996148818..3b21d7bed 100644 --- a/R/Utilities.R +++ b/R/Utilities.R @@ -1132,7 +1132,7 @@ Add_Pct_Diff <- function( overwrite = FALSE ) { # Check if percent difference exists already - if ("pct_diff" %in% colnames(marker_dataframe)) { + if ("pct_diff" %in% colnames(x = marker_dataframe)) { df_name <- deparse(expr = substitute(expr = marker_dataframe)) if (isFALSE(x = overwrite)) { cli_abort(message = c("{.val pct_diff} column already present in {.code marker_dataframe}: {.val {df_name}}.", diff --git a/R/Utilities_Objects.R b/R/Utilities_Objects.R index c8cac1c03..9d00c84f8 100644 --- a/R/Utilities_Objects.R +++ b/R/Utilities_Objects.R @@ -497,7 +497,7 @@ Add_Sample_Meta <- function( #' @param include_all logical, whether or not to include all object meta data columns in output data.frame. #' Default is FALSE. #' -#' @return Returns a data.frame with one row per `sample_name`. +#' @return Returns a data.frame with one row per `sample_col`. #' #' @importFrom dplyr any_of grouped_df select slice #' @importFrom magrittr "%>%" @@ -510,14 +510,14 @@ Add_Sample_Meta <- function( #' library(Seurat) #' pbmc_small[["batch"]] <- sample(c("batch1", "batch2"), size = ncol(pbmc_small), replace = TRUE) #' -#' sample_meta <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident") +#' sample_meta <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident") #' #' # Only return specific columns from meta data (orig.ident and batch) -#' sample_meta2 <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident", +#' sample_meta2 <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident", #' variables_include = "batch") #' #' # Return all columns from meta data -#' sample_meta3 <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident", +#' sample_meta3 <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident", #' include_all = TRUE) #' @@ -892,7 +892,7 @@ Random_Cells_Downsample <- function( rownames() %>% sample(size = num_cells[x]) }) - names(random_cells) <- idents_all + names(x = random_cells) <- idents_all } else { # set seed and select random cells per ident prev_seed <- get_seed() @@ -1089,7 +1089,12 @@ Store_Palette_Seurat <- function( # Check Seurat Is_Seurat(seurat_object = seurat_object) - seurat_object <- Store_Misc_Info_Seurat(seurat_object = seurat_object, data_to_store = palette, data_name = palette_name, list_as_list = list_as_list, overwrite = overwrite, verbose = verbose) + seurat_object <- Store_Misc_Info_Seurat(seurat_object = seurat_object, + data_to_store = palette, + data_name = palette_name, + list_as_list = list_as_list, + overwrite = overwrite, + verbose = verbose) return(seurat_object) } @@ -1168,7 +1173,7 @@ Add_Alt_Feature_ID <- function( # if providing features_tsv if (!is.null(x = features_tsv_file)) { features_table <- data.table::fread(file = features_tsv_file, header = FALSE, data.table = FALSE) - colnames(features_table) <- c("Ensembl_ID", "Symbol", "Modality") + colnames(x = features_table) <- c("Ensembl_ID", "Symbol", "Modality") features_table$Symbol <- make.unique(features_table$Symbol) diff --git a/R/QC_Utilities_Seurat.R b/R/Utilities_QC_Seurat.R similarity index 96% rename from R/QC_Utilities_Seurat.R rename to R/Utilities_QC_Seurat.R index 7749bdf12..c8f80abdc 100644 --- a/R/QC_Utilities_Seurat.R +++ b/R/Utilities_QC_Seurat.R @@ -19,6 +19,8 @@ #' @param add_lncRNA logical, whether to add percentage of counts belonging to lncRNA genes to object (Default is TRUE). #' @param add_cell_cycle logical, whether to addcell cycle scores and phase based on #' \code{\link[Seurat]{CellCycleScoring}}. Only applicable if `species = "human"`. (Default is TRUE). +#' @param assay_suffix logical, whether to add assay suffix to the QC column name added to meta.data. +#' Default is FALSE. #' @param mito_name name to use for the new meta.data column containing percent mitochondrial counts. #' Default is "percent_mito". #' @param ribo_name name to use for the new meta.data column containing percent ribosomal counts. @@ -94,6 +96,7 @@ Add_Cell_QC_Metrics.Seurat <- function( add_hemo = TRUE, add_lncRNA = TRUE, add_cell_cycle = TRUE, + assay_suffix = FALSE, mito_name = "percent_mito", ribo_name = "percent_ribo", mito_ribo_name = "percent_mito_ribo", @@ -119,6 +122,9 @@ Add_Cell_QC_Metrics.Seurat <- function( overwrite = FALSE, ... ) { + # check dots + chkDots(...) + # Set assay assay <- assay %||% DefaultAssay(object = object) @@ -150,6 +156,11 @@ Add_Cell_QC_Metrics.Seurat <- function( macaque_options <- accepted_names$Macaque_Options chicken_options <- accepted_names$Chicken_Options + # pull column names before adding QC + if (isTRUE(x = assay_suffix)) { + old_col_names <- colnames(x = Fetch_Meta(object = object)) + } + # Add mito/ribo if (isTRUE(x = add_mito_ribo)) { cli_inform(message = c("*" = "Adding {.field Mito/Ribo Percentages} to meta.data.")) @@ -239,10 +250,27 @@ Add_Cell_QC_Metrics.Seurat <- function( # Add Cell Cycle Scoring cli_inform(message = "Calculating {.field Cell Cycle Scores}.") - object <- CellCycleScoring(object = object, s.features = Seurat::cc.genes.updated.2019$s.genes, g2m.features = Seurat::cc.genes.updated.2019$g2m.genes) + s.genes_found <- Feature_PreCheck(object = object, features = Seurat::cc.genes.updated.2019$s.genes) + g2m.genes_found <- Feature_PreCheck(object = object, features = Seurat::cc.genes.updated.2019$g2m.genes) + + object <- CellCycleScoring(object = object, s.features = s.genes_found, g2m.features = g2m.genes_found) } } + # pull new column names after adding QC + if (isTRUE(x = assay_suffix)) { + new_col_names <- colnames(x = Fetch_Meta(object = object)) + + added_cols <- setdiff(x = new_col_names, y = old_col_names) + + assay <- DefaultAssay(object = object) + + added_cols_new <- paste0(added_cols, "_", assay) + + # Add assay suffix to new columns + colnames(x = object@meta.data) <- c(old_col_names, added_cols_new) + } + # Log Command object <- LogSeuratCommand(object = object) @@ -318,6 +346,9 @@ Add_Mito_Ribo.Seurat <- function( species_prefix = NULL, ... ) { + # check dots + chkDots(...) + # Accepted species names accepted_names <- data.frame( Mouse_Options = c("Mouse", "mouse", "Ms", "ms", "Mm", "mm"), @@ -556,6 +587,9 @@ Add_Hemo.Seurat <- function( list_species_names = FALSE, ... ) { + # check dots + chkDots(...) + # Accepted species names accepted_names <- data.frame( Mouse_Options = c("Mouse", "mouse", "Ms", "ms", "Mm", "mm"), @@ -711,8 +745,8 @@ Add_Cell_Complexity.Seurat <- function( overwrite = FALSE, ... ) { - # Check Seurat - Is_Seurat(seurat_object = object) + # check dots + chkDots(...) # Add assay warning message if (assay != "RNA") { @@ -795,6 +829,9 @@ Add_Top_Gene_Pct.Seurat <- function( verbose = TRUE, ... ){ + # check dots + chkDots(...) + # Check for scuttle first scuttle_check <- is_installed(pkg = "scuttle") if (isFALSE(x = scuttle_check)) { @@ -892,6 +929,8 @@ Add_Top_Gene_Pct.Seurat <- function( #' @param sample_col column name in meta.data that contains sample ID information. #' @param malat1_threshold_name name to use for the new meta.data column containing percent IEG gene counts. #' Default is set dependent on species gene symbol. +#' @param assay_suffix logical, whether to add assay suffix to the QC column name added to meta.data. +#' Default is FALSE. #' @param ensembl_ids logical, whether feature names in the object are gene names or #' ensembl IDs (default is FALSE; set TRUE if feature names are ensembl IDs). #' @param assay Assay to use (default is the current object default assay). @@ -974,6 +1013,7 @@ Add_MALAT1_Threshold.Seurat <- function( species, sample_col = NULL, malat1_threshold_name = NULL, + assay_suffix = FALSE, ensembl_ids = FALSE, assay = NULL, overwrite = FALSE, @@ -994,8 +1034,8 @@ Add_MALAT1_Threshold.Seurat <- function( rough_max = 2, ... ) { - # Check Seurat - Is_Seurat(seurat_object = object) + # check dots + chkDots(...) # Check for sample column if (is.null(x = sample_col) && isFALSE(x = whole_object)) { @@ -1049,6 +1089,11 @@ Add_MALAT1_Threshold.Seurat <- function( } } + # pull column names before adding QC + if (isTRUE(x = assay_suffix)) { + old_col_names <- colnames(x = Fetch_Meta(object = object)) + } + # Overwrite check if (malat1_threshold_name %in% colnames(x = object@meta.data)) { if (isFALSE(x = overwrite)) { @@ -1210,6 +1255,20 @@ Add_MALAT1_Threshold.Seurat <- function( object[[malat1_threshold_name]] <- factor(object[[malat1_threshold_name]][,1], levels = c("TRUE","FALSE")) } + # pull new column names after adding QC + if (isTRUE(x = assay_suffix)) { + new_col_names <- colnames(x = Fetch_Meta(object = object)) + + added_cols <- setdiff(x = new_col_names, y = old_col_names) + + assay <- DefaultAssay(object = object) + + added_cols_new <- paste0(added_cols, "_", assay) + + # Add assay suffix to new columns + colnames(x = object@meta.data) <- c(old_col_names, added_cols_new) + } + object <- LogSeuratCommand(object = object) return(object) @@ -1223,6 +1282,8 @@ Add_MALAT1_Threshold.Seurat <- function( #' @param seurat_object object name. #' @param species Species of origin for given Seurat Object. Only accepted species are: mouse, human (name or abbreviation). #' @param exam_module_name name to use for the new meta.data column containing module scores. +#' @param assay_suffix logical, whether to add assay suffix to the QC column name added to meta.data. +#' Default is FALSE. #' @param method method to use for module scoring, currently only "Seurat" is supported but more to be added. . #' @param ensembl_ids logical, whether feature names in the object are gene names or #' ensembl IDs (default is FALSE; set TRUE if feature names are ensembl IDs). @@ -1252,6 +1313,7 @@ exAM_Scoring <- function( seurat_object, species, exam_module_name = NULL, + assay_suffix = FALSE, method = "Seurat", ensembl_ids = FALSE, assay = NULL, @@ -1293,6 +1355,11 @@ exAM_Scoring <- function( # Check Seurat Is_Seurat(seurat_object = seurat_object) + # pull column names before adding QC + if (isTRUE(x = assay_suffix)) { + old_col_names <- colnames(x = Fetch_Meta(object = seurat_object)) + } + if (method == "UCell") { # Check Nebulosa installed UCell_check <- is_installed(pkg = "UCell") @@ -1375,6 +1442,20 @@ exAM_Scoring <- function( } } + # pull new column names after adding QC + if (isTRUE(x = assay_suffix)) { + new_col_names <- colnames(x = Fetch_Meta(object = seurat_object)) + + added_cols <- setdiff(x = new_col_names, y = old_col_names) + + assay <- DefaultAssay(object = seurat_object) + + added_cols_new <- paste0(added_cols, "_", assay) + + # Add assay suffix to new columns + colnames(x = seurat_object@meta.data) <- c(old_col_names, added_cols_new) + } + # Log Command seurat_object <- LogSeuratCommand(object = seurat_object) diff --git a/man/Add_CellBender_Diff.Rd b/man/Add_CellBender_Diff.Rd index fe93c7843..19639266d 100644 --- a/man/Add_CellBender_Diff.Rd +++ b/man/Add_CellBender_Diff.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/QC_Utilities_Seurat.R +% Please edit documentation in R/Utilities_QC_Seurat.R \name{Add_CellBender_Diff} \alias{Add_CellBender_Diff} \title{Calculate and add differences post-cell bender analysis} diff --git a/man/Add_Cell_Complexity.Rd b/man/Add_Cell_Complexity.Rd index a905db38c..cdc3d181a 100644 --- a/man/Add_Cell_Complexity.Rd +++ b/man/Add_Cell_Complexity.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/Generics.R, R/LIGER_Utilities.R, -% R/QC_Utilities_Seurat.R +% R/Utilities_QC_Seurat.R \name{Add_Cell_Complexity} \alias{Add_Cell_Complexity} \alias{Add_Cell_Complexity.liger} diff --git a/man/Add_Cell_QC_Metrics.Rd b/man/Add_Cell_QC_Metrics.Rd index f72a93b05..28f905a93 100644 --- a/man/Add_Cell_QC_Metrics.Rd +++ b/man/Add_Cell_QC_Metrics.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/Generics.R, R/LIGER_Utilities.R, -% R/QC_Utilities_Seurat.R +% R/Utilities_QC_Seurat.R \name{Add_Cell_QC_Metrics} \alias{Add_Cell_QC_Metrics} \alias{Add_Cell_QC_Metrics.liger} @@ -18,7 +18,6 @@ Add_Cell_QC_Metrics(object, ...) add_IEG = TRUE, add_hemo = TRUE, add_lncRNA = TRUE, - add_cell_cycle = TRUE, species, mito_name = "percent_mito", ribo_name = "percent_ribo", @@ -57,6 +56,7 @@ Add_Cell_QC_Metrics(object, ...) add_hemo = TRUE, add_lncRNA = TRUE, add_cell_cycle = TRUE, + assay_suffix = FALSE, mito_name = "percent_mito", ribo_name = "percent_ribo", mito_ribo_name = "percent_mito_ribo", @@ -105,9 +105,6 @@ object (Default is TRUE).} \item{add_lncRNA}{logical, whether to add percentage of counts belonging to lncRNA genes to object (Default is TRUE).} -\item{add_cell_cycle}{logical, whether to addcell cycle scores and phase based on -\code{\link[Seurat]{CellCycleScoring}}. Only applicable if \code{species = "human"}. (Default is TRUE).} - \item{species}{Species of origin for given Seurat Object. If mouse, human, marmoset, zebrafish, rat, drosophila, rhesus macaque, or chicken (name or abbreviation) are provided the function will automatically generate patterns and features.} @@ -180,6 +177,12 @@ function will abort if column with name provided to \code{meta_col_name} is pres \item{add_IEG_module_score}{logical, whether to add module score belonging to IEG genes to object (Default is TRUE).} +\item{add_cell_cycle}{logical, whether to addcell cycle scores and phase based on +\code{\link[Seurat]{CellCycleScoring}}. Only applicable if \code{species = "human"}. (Default is TRUE).} + +\item{assay_suffix}{logical, whether to add assay suffix to the QC column name added to meta.data. +Default is FALSE.} + \item{ieg_module_name}{name to use for new meta data column for module score of IEGs. Default is "ieg_score".} } \value{ diff --git a/man/Add_Hemo.Rd b/man/Add_Hemo.Rd index ccb3897b0..f824c84d2 100644 --- a/man/Add_Hemo.Rd +++ b/man/Add_Hemo.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/Generics.R, R/LIGER_Utilities.R, -% R/QC_Utilities_Seurat.R +% R/Utilities_QC_Seurat.R \name{Add_Hemo} \alias{Add_Hemo} \alias{Add_Hemo.liger} diff --git a/man/Add_MALAT1_Threshold.Rd b/man/Add_MALAT1_Threshold.Rd index 98db74ab9..7f7293e11 100644 --- a/man/Add_MALAT1_Threshold.Rd +++ b/man/Add_MALAT1_Threshold.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/Generics.R, R/QC_Utilities_Seurat.R +% Please edit documentation in R/Generics.R, R/Utilities_QC_Seurat.R \name{Add_MALAT1_Threshold} \alias{Add_MALAT1_Threshold} \alias{Add_MALAT1_Threshold.Seurat} @@ -12,6 +12,7 @@ Add_MALAT1_Threshold(object, ...) species, sample_col = NULL, malat1_threshold_name = NULL, + assay_suffix = FALSE, ensembl_ids = FALSE, assay = NULL, overwrite = FALSE, @@ -45,6 +46,9 @@ Add_MALAT1_Threshold(object, ...) \item{malat1_threshold_name}{name to use for the new meta.data column containing percent IEG gene counts. Default is set dependent on species gene symbol.} +\item{assay_suffix}{logical, whether to add assay suffix to the QC column name added to meta.data. +Default is FALSE.} + \item{ensembl_ids}{logical, whether feature names in the object are gene names or ensembl IDs (default is FALSE; set TRUE if feature names are ensembl IDs).} diff --git a/man/Add_Mito_Ribo.Rd b/man/Add_Mito_Ribo.Rd index 184ebdbc8..8d8e6f092 100644 --- a/man/Add_Mito_Ribo.Rd +++ b/man/Add_Mito_Ribo.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/Generics.R, R/LIGER_Utilities.R, -% R/QC_Utilities_Seurat.R +% R/Utilities_QC_Seurat.R \name{Add_Mito_Ribo} \alias{Add_Mito_Ribo} \alias{Add_Mito_Ribo.liger} diff --git a/man/Add_Top_Gene_Pct.Rd b/man/Add_Top_Gene_Pct.Rd index a1a93a5e5..0334c2fe2 100644 --- a/man/Add_Top_Gene_Pct.Rd +++ b/man/Add_Top_Gene_Pct.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/Generics.R, R/LIGER_Utilities.R, -% R/QC_Utilities_Seurat.R +% R/Utilities_QC_Seurat.R \name{Add_Top_Gene_Pct} \alias{Add_Top_Gene_Pct} \alias{Add_Top_Gene_Pct.liger} diff --git a/man/ElbowPlot_scCustom.Rd b/man/ElbowPlot_scCustom.Rd index 22791ddce..24cb194c1 100644 --- a/man/ElbowPlot_scCustom.Rd +++ b/man/ElbowPlot_scCustom.Rd @@ -11,7 +11,8 @@ ElbowPlot_scCustom( calc_cutoffs = TRUE, plot_cutoffs = TRUE, line_colors = c("dodgerblue", "firebrick"), - linewidth = 0.5 + cutoff_linewidth = NULL, + linewidth = deprecated() ) } \arguments{ @@ -23,11 +24,13 @@ ElbowPlot_scCustom( \item{calc_cutoffs}{logical, whether or not to calculate the cutoffs, default is TRUE.} -\item{plot_cutoffs}{lgoical, whether to plot the cutoffs as vertical lines on plot, default is TRUE.} +\item{plot_cutoffs}{logical, whether to plot the cutoffs as vertical lines on plot, default is TRUE.} \item{line_colors}{colors for the cutoff lines, default is c("dodgerblue", "firebrick").} -\item{linewidth}{widith of the cutoff lines, default is 0.5.} +\item{cutoff_linewidth}{width of the cutoff lines, default is NULL, uses ggplot2 default.} + +\item{linewidth}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} } \value{ ggplot2 object diff --git a/man/Extract_Sample_Meta.Rd b/man/Extract_Sample_Meta.Rd index d49dc3b3f..e45324f4e 100644 --- a/man/Extract_Sample_Meta.Rd +++ b/man/Extract_Sample_Meta.Rd @@ -38,7 +38,7 @@ function can be joined with output of \code{\link[scCustomize]{Median_Stats}}. Default is FALSE.} } \value{ -Returns a data.frame with one row per \code{sample_name}. +Returns a data.frame with one row per \code{sample_col}. } \description{ Returns a by identity meta.data data.frame with one row per sample. Useful for downstream @@ -48,14 +48,14 @@ quick view of sample breakdown, meta data table creation, and/or use in pseudobu library(Seurat) pbmc_small[["batch"]] <- sample(c("batch1", "batch2"), size = ncol(pbmc_small), replace = TRUE) -sample_meta <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident") +sample_meta <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident") # Only return specific columns from meta data (orig.ident and batch) -sample_meta2 <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident", +sample_meta2 <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident", variables_include = "batch") # Return all columns from meta data -sample_meta3 <- Extract_Sample_Meta(object = pbmc_small, sample_name = "orig.ident", +sample_meta3 <- Extract_Sample_Meta(object = pbmc_small, sample_col = "orig.ident", include_all = TRUE) } diff --git a/man/Plot_Cells_per_Sample.Rd b/man/Plot_Cells_per_Sample.Rd index 498f0e4d6..e45c2a1c9 100644 --- a/man/Plot_Cells_per_Sample.Rd +++ b/man/Plot_Cells_per_Sample.Rd @@ -15,6 +15,9 @@ Plot_Cells_per_Sample( x_axis_label = NULL, legend_title = NULL, x_lab_rotate = TRUE, + reorder = FALSE, + reorder_decreasing = FALSE, + plot_median = TRUE, color_seed = 123 ) } @@ -39,6 +42,14 @@ Plot_Cells_per_Sample( \item{x_lab_rotate}{logical. Whether to rotate the axes labels on the x-axis. Default is FALSE.} +\item{reorder}{logical, if plotting by sample should x-axis be reordered according to number of cells, +default is FALSE.} + +\item{reorder_decreasing}{logical, if \code{reorder = TRUE} should points be ordered from fewest to +greatest number of cells (FALSE) or reverse (TRUE), default is FALSE.} + +\item{plot_median}{logical, if plotting by sample should line be added showing median, default is TRUE.} + \item{color_seed}{random seed for the "varibow" palette shuffle if \code{colors_use = NULL} and number of groups plotted is greater than 36. Default = 123.} } @@ -50,7 +61,15 @@ Plot of total cell or nuclei number per sample grouped by another meta data vari } \examples{ \dontrun{ -Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "Treatment") +# Plot cells per sample grouped by "Diagnosis" +Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "Diagnosis") + +# Plot cells per sample individually +Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "orig.ident") + +#' # Plot cells per sample individually and reorder x-axis by cell number +Plot_Cells_per_Sample(seurat_object = obj, sample_col = "orig.ident", group.by = "orig.ident", order = TRUE) + } } diff --git a/man/QC_Histogram.Rd b/man/QC_Histogram.Rd index a677b3654..088c57535 100644 --- a/man/QC_Histogram.Rd +++ b/man/QC_Histogram.Rd @@ -9,7 +9,8 @@ QC_Histogram( features, low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, split.by = NULL, bins = 250, colors_use = "dodgerblue", @@ -28,7 +29,10 @@ QC_Histogram( \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{split.by}{Feature to split plots by (i.e. "orig.ident").} diff --git a/man/QC_Plot_GenevsFeature.Rd b/man/QC_Plot_GenevsFeature.Rd index f968becb3..8cd6bb133 100644 --- a/man/QC_Plot_GenevsFeature.Rd +++ b/man/QC_Plot_GenevsFeature.Rd @@ -13,7 +13,8 @@ QC_Plot_GenevsFeature( high_cutoff_gene = NULL, low_cutoff_feature = NULL, high_cutoff_feature = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, pt.size = 1, group.by = NULL, @@ -43,7 +44,10 @@ QC_Plot_GenevsFeature( \item{high_cutoff_feature}{Plot line a potential high threshold for filtering feature1 per cell.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{colors_use}{vector of colors to use for plotting by identity.} diff --git a/man/QC_Plot_UMIvsFeature.Rd b/man/QC_Plot_UMIvsFeature.Rd index 49b41dc6b..ba3f5fb19 100644 --- a/man/QC_Plot_UMIvsFeature.Rd +++ b/man/QC_Plot_UMIvsFeature.Rd @@ -13,7 +13,8 @@ QC_Plot_UMIvsFeature( high_cutoff_UMI = NULL, low_cutoff_feature = NULL, high_cutoff_feature = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, pt.size = 1, group.by = NULL, @@ -43,7 +44,10 @@ QC_Plot_UMIvsFeature( \item{high_cutoff_feature}{Plot line a potential high threshold for filtering feature1 per cell.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{colors_use}{vector of colors to use for plotting by identity.} diff --git a/man/QC_Plot_UMIvsGene.Rd b/man/QC_Plot_UMIvsGene.Rd index 1394f5d4b..9ac9f7d4e 100644 --- a/man/QC_Plot_UMIvsGene.Rd +++ b/man/QC_Plot_UMIvsGene.Rd @@ -12,7 +12,8 @@ QC_Plot_UMIvsGene( high_cutoff_gene = Inf, low_cutoff_UMI = -Inf, high_cutoff_UMI = Inf, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, colors_use = NULL, meta_gradient_name = NULL, meta_gradient_color = viridis_plasma_dark_high, @@ -47,7 +48,10 @@ QC_Plot_UMIvsGene( \item{high_cutoff_UMI}{Plot line a potential high threshold for filtering UMIs per cell.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{colors_use}{vector of colors to use for plotting by identity.} diff --git a/man/QC_Plots_Combined_Vln.Rd b/man/QC_Plots_Combined_Vln.Rd index 1e3f09b40..baa41dde6 100644 --- a/man/QC_Plots_Combined_Vln.Rd +++ b/man/QC_Plots_Combined_Vln.Rd @@ -11,7 +11,8 @@ QC_Plots_Combined_Vln( UMI_cutoffs = NULL, mito_cutoffs = NULL, mito_name = "percent_mito", - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -40,7 +41,10 @@ default is the current active.ident of the object.} \item{mito_name}{The column name containing percent mitochondrial counts information. Default value is "percent_mito" which is default value created when using \code{Add_Mito_Ribo()}.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting} diff --git a/man/QC_Plots_Complexity.Rd b/man/QC_Plots_Complexity.Rd index 769ac3e1d..a7c278dec 100644 --- a/man/QC_Plots_Complexity.Rd +++ b/man/QC_Plots_Complexity.Rd @@ -13,7 +13,8 @@ QC_Plots_Complexity( plot_title = "Cell Complexity", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, plot_boxplot = FALSE, @@ -45,7 +46,10 @@ default is the current active.ident of the object.} \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting} diff --git a/man/QC_Plots_Feature.Rd b/man/QC_Plots_Feature.Rd index d48e76ccc..49e7192ef 100644 --- a/man/QC_Plots_Feature.Rd +++ b/man/QC_Plots_Feature.Rd @@ -13,7 +13,8 @@ QC_Plots_Feature( plot_title = NULL, low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -45,7 +46,10 @@ default is the current active.ident of the object.} \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting.} diff --git a/man/QC_Plots_Genes.Rd b/man/QC_Plots_Genes.Rd index 7eca2a978..4f3afe155 100644 --- a/man/QC_Plots_Genes.Rd +++ b/man/QC_Plots_Genes.Rd @@ -12,7 +12,8 @@ QC_Plots_Genes( y_axis_label = "Features", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, plot_boxplot = FALSE, @@ -43,7 +44,10 @@ default is the current active.ident of the object.} \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting.} diff --git a/man/QC_Plots_Mito.Rd b/man/QC_Plots_Mito.Rd index be3399d02..eed70b4a6 100644 --- a/man/QC_Plots_Mito.Rd +++ b/man/QC_Plots_Mito.Rd @@ -13,7 +13,8 @@ QC_Plots_Mito( y_axis_label = "\% Mitochondrial Gene Counts", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -46,7 +47,10 @@ default is the current active.ident of the object.} \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting.} diff --git a/man/QC_Plots_UMIs.Rd b/man/QC_Plots_UMIs.Rd index 7b05a56a6..3f7a011cb 100644 --- a/man/QC_Plots_UMIs.Rd +++ b/man/QC_Plots_UMIs.Rd @@ -12,7 +12,8 @@ QC_Plots_UMIs( y_axis_label = "UMIs", low_cutoff = NULL, high_cutoff = NULL, - cutoff_line_width = NULL, + cutoff_line_width = deprecated(), + cutoff_linewidth = NULL, pt.size = NULL, plot_median = FALSE, median_size = 15, @@ -43,7 +44,10 @@ default is the current active.ident of the object.} \item{high_cutoff}{Plot line a potential high threshold for filtering.} -\item{cutoff_line_width}{numerical value for thickness of cutoff lines, default is NULL.} +\item{cutoff_line_width}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}. See \code{cutoff_linewidth}.} + +\item{cutoff_linewidth}{numerical value for thickness of cutoff lines, +default is NULL, uses ggplot2 defaults.} \item{pt.size}{Point size for plotting.} diff --git a/man/Read_Velocity.Rd b/man/Read_Velocity.Rd new file mode 100644 index 000000000..b05b73491 --- /dev/null +++ b/man/Read_Velocity.Rd @@ -0,0 +1,79 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Read_Write_Data.R +\name{Read_Velocity} +\alias{Read_Velocity} +\title{Load RNA Velocity results} +\usage{ +Read_Velocity( + loom_file = NULL, + data_dir = NULL, + multi_dir = TRUE, + gene_symbol = TRUE, + sort_type = FALSE, + sample_list = NULL, + sample_names = NULL, + shared_suffix = NULL, + parallel = FALSE, + num_cores = NULL +) +} +\arguments{ +\item{loom_file}{path and name of loom file to read} + +\item{data_dir}{path to data directory containing all loom files to read} + +\item{gene_symbol}{logical, should row names of returned matrices have gene symbols or accession ID #s, +default is TRUE (symbols).} + +\item{sort_type}{logical, default is FALSE and will return list with 1 sample per entry. Each +sample entry will contain 3 matrices (spliced, unspliced, ambiguous). If TRUE will return list of +3 matrix types (spliced, unspliced, ambiguous) with one entry per sample} + +\item{sample_list}{A vector of file prefixes/names if specific samples are desired. Default is \code{NULL} and +will load all samples in given directory.} + +\item{sample_names}{a set of sample names to use for each sample entry in returned list. If \code{NULL} +will set names to the file name of each sample.} + +\item{shared_suffix}{a suffix and file extension shared by all samples.} + +\item{parallel}{logical (default FALSE). Whether to use multiple cores when reading in data. +Only possible on Linux based systems.} + +\item{num_cores}{if \code{parallel = TRUE} indicates the number of cores to use for multi-core processing.} +} +\value{ +list of sparse matrices containing spliced, unspliced, and ambiguous counts +} +\description{ +Wrapper function to +} +\examples{ +\dontrun{ +# Read single velocity loom file +velo_res <- Read_Velocity(loom_file = "PATH/sample01.loom") + +# Read single velocity loom file with ensembl IDs +velo_res <- Read_Velocity(loom_file = "PATH/sample01.loom", gene_symbol = FALSE) + +# Read multiple files from a parent directory with many subdirectories & return 1 list entry per sample +# Each entry will contain 3 matrices (spliced, unspliced, ambiguous) +velo_res_list <- Read_Velocity(loom_file = "PATH/", secondary_path = "SEC_PATH/") + +# Sort returned list by read type instead of by sample +# list will contain 3 entries (spliced, unspliced, ambiguous) +# each entry will contain 1 matrix per sample +velo_res_list <- Read_Velocity(loom_file = "PATH/", secondary_path = "SEC_PATH/", sort_type = TRUE) + +# Read multiple files from a single directory +velo_res_list <- Read_Velocity(loom_file = "PATH/", multi_dir = FALSE) +} +} +\references{ +Function is updated from \code{SeuratWrappers::ReadVelocity} +\url{https://github.com/satijalab/seurat-wrappers/blob/master/R/velocity.R} (License: GPL-3). +Function included in scCustomize to avoid installation issues related to other aspects of +velocyto.R package which \code{SeuratWrappers::ReadVelocity} requires. +scCustomize version also adds multi-file and multi-directory support, ability to return Ensembl IDs, +and multi-core parallel file reading. +} diff --git a/man/Seq_QC_Plot_Alignment_Combined.Rd b/man/Seq_QC_Plot_Alignment_Combined.Rd index f4989dc18..6b804b297 100644 --- a/man/Seq_QC_Plot_Alignment_Combined.Rd +++ b/man/Seq_QC_Plot_Alignment_Combined.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Alignment_Combined( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -18,7 +19,7 @@ Seq_QC_Plot_Alignment_Combined( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Antisense.Rd b/man/Seq_QC_Plot_Antisense.Rd index 493df5b16..ab02d3fe8 100644 --- a/man/Seq_QC_Plot_Antisense.Rd +++ b/man/Seq_QC_Plot_Antisense.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Antisense( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Antisense( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Basic_Combined.Rd b/man/Seq_QC_Plot_Basic_Combined.Rd index 6e3968aed..51e54dfac 100644 --- a/man/Seq_QC_Plot_Basic_Combined.Rd +++ b/man/Seq_QC_Plot_Basic_Combined.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Basic_Combined( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -18,7 +19,7 @@ Seq_QC_Plot_Basic_Combined( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Exonic.Rd b/man/Seq_QC_Plot_Exonic.Rd index c03a0ce04..4b22d111f 100644 --- a/man/Seq_QC_Plot_Exonic.Rd +++ b/man/Seq_QC_Plot_Exonic.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Exonic( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Exonic( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Genes.Rd b/man/Seq_QC_Plot_Genes.Rd index b90312610..904edcf66 100644 --- a/man/Seq_QC_Plot_Genes.Rd +++ b/man/Seq_QC_Plot_Genes.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Genes( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Genes( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Genome.Rd b/man/Seq_QC_Plot_Genome.Rd index 355f97b81..87a55f93c 100644 --- a/man/Seq_QC_Plot_Genome.Rd +++ b/man/Seq_QC_Plot_Genome.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Genome( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Genome( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Intergenic.Rd b/man/Seq_QC_Plot_Intergenic.Rd index 147c76daa..ff7847a65 100644 --- a/man/Seq_QC_Plot_Intergenic.Rd +++ b/man/Seq_QC_Plot_Intergenic.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Intergenic( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Intergenic( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Intronic.Rd b/man/Seq_QC_Plot_Intronic.Rd index 193a8003f..161962252 100644 --- a/man/Seq_QC_Plot_Intronic.Rd +++ b/man/Seq_QC_Plot_Intronic.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Intronic( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Intronic( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Number_Cells.Rd b/man/Seq_QC_Plot_Number_Cells.Rd index 35ea5bf88..f927a2991 100644 --- a/man/Seq_QC_Plot_Number_Cells.Rd +++ b/man/Seq_QC_Plot_Number_Cells.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Number_Cells( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Number_Cells( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Reads_in_Cells.Rd b/man/Seq_QC_Plot_Reads_in_Cells.Rd index 7be4f5002..fb28f4057 100644 --- a/man/Seq_QC_Plot_Reads_in_Cells.Rd +++ b/man/Seq_QC_Plot_Reads_in_Cells.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Reads_in_Cells( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Reads_in_Cells( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Reads_per_Cell.Rd b/man/Seq_QC_Plot_Reads_per_Cell.Rd index 61f47787c..5c3bce88d 100644 --- a/man/Seq_QC_Plot_Reads_per_Cell.Rd +++ b/man/Seq_QC_Plot_Reads_per_Cell.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Reads_per_Cell( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,9 @@ Seq_QC_Plot_Reads_per_Cell( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} + +\item{plot_by}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} soft-deprecated. See \code{group.by}.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Saturation.Rd b/man/Seq_QC_Plot_Saturation.Rd index 43427e9af..18fcc4aa4 100644 --- a/man/Seq_QC_Plot_Saturation.Rd +++ b/man/Seq_QC_Plot_Saturation.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Saturation( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Saturation( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Total_Genes.Rd b/man/Seq_QC_Plot_Total_Genes.Rd index 90038a8c3..b8397c160 100644 --- a/man/Seq_QC_Plot_Total_Genes.Rd +++ b/man/Seq_QC_Plot_Total_Genes.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Total_Genes( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Total_Genes( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_Transcriptome.Rd b/man/Seq_QC_Plot_Transcriptome.Rd index 0fe36c1a6..7b955fdfd 100644 --- a/man/Seq_QC_Plot_Transcriptome.Rd +++ b/man/Seq_QC_Plot_Transcriptome.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_Transcriptome( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_Transcriptome( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/Seq_QC_Plot_UMIs.Rd b/man/Seq_QC_Plot_UMIs.Rd index 5ee01a979..a8714e7b3 100644 --- a/man/Seq_QC_Plot_UMIs.Rd +++ b/man/Seq_QC_Plot_UMIs.Rd @@ -6,7 +6,8 @@ \usage{ Seq_QC_Plot_UMIs( metrics_dataframe, - plot_by = "sample_id", + group.by = "sample_id", + plot_by = deprecated(), colors_use = NULL, dot_size = 1, x_lab_rotate = FALSE, @@ -17,7 +18,7 @@ Seq_QC_Plot_UMIs( \arguments{ \item{metrics_dataframe}{data.frame contain Cell Ranger QC Metrics (see \code{\link{Read_Metrics_10X}}).} -\item{plot_by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} +\item{group.by}{Grouping factor for the plot. Default is to plot as single group with single point per sample.} \item{colors_use}{colors to use for plot if plotting by group. Defaults to RColorBrewer Dark2 palette if less than 8 groups and \code{DiscretePalette_scCustomize(palette = "polychrome")} if more than 8.} diff --git a/man/exAM_Scoring.Rd b/man/exAM_Scoring.Rd index ad339f55b..689928d35 100644 --- a/man/exAM_Scoring.Rd +++ b/man/exAM_Scoring.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/QC_Utilities_Seurat.R +% Please edit documentation in R/Utilities_QC_Seurat.R \name{exAM_Scoring} \alias{exAM_Scoring} \title{Add exAM Gene List Module Scores} @@ -8,6 +8,7 @@ exAM_Scoring( seurat_object, species, exam_module_name = NULL, + assay_suffix = FALSE, method = "Seurat", ensembl_ids = FALSE, assay = NULL, @@ -23,6 +24,9 @@ exAM_Scoring( \item{exam_module_name}{name to use for the new meta.data column containing module scores.} +\item{assay_suffix}{logical, whether to add assay suffix to the QC column name added to meta.data. +Default is FALSE.} + \item{method}{method to use for module scoring, currently only "Seurat" is supported but more to be added. .} \item{ensembl_ids}{logical, whether feature names in the object are gene names or