Apply 'adjustment's to metadata targets

NAMESPACE

@@ -67,6 +67,7 @@ importFrom(pheatmap,pheatmap)
 importFrom(stats,as.formula)
 importFrom(stats,median)
 importFrom(stats,sd)
+importFrom(stats,setNames)
 importFrom(utils,modifyList)
 importFrom(utils,packageVersion)
 importFrom(utils,read.table)

R/ColorAdjustments.R

@@ -2,7 +2,7 @@
 #' Darkens input colors by a set amount
 #'
 #' @description A wrapper for the darken function of the colorspace package.
-#' @param colors the color(s) input. Can be a list of colors, for example, /code{dittoColors()}.
+#' @param colors the color(s) input. Can be a list of colors, for example, \code{dittoColors()}.
 #' @param percent.change # between 0 and 1. the percentage to darken by. Defaults to 0.25 if not given.
 #' @param relative TRUE/FALSE. Whether the percentage should be a relative change versus an absolute one. Default = TRUE.
 #' @return Return a darkened version of the color in hexadecimal color form (="#RRGGBB" in base 16)
@@ -23,7 +23,7 @@ Darken <- function(colors, percent.change = 0.25, relative = TRUE) {
 #' Lightens input colors by a set amount
 #'
 #' @description A wrapper for the lighten function of the colorspace package.
-#' @param colors the color(s) input. Can be a list of colors, for example, /code{dittoColors()}.
+#' @param colors the color(s) input. Can be a list of colors, for example, \code{dittoColors()}.
 #' @param percent.change # between 0 and 1. the percentage to darken by. Defaults to 0.25 if not given.
 #' @param relative TRUE/FALSE. Whether the percentage should be a relative change versus an absolute one. Default = TRUE.
 #' @return Return a lighter version of the color in hexadecimal color form (="#RRGGBB" in base 16)

R/DittoDimPlot.R

@@ -70,7 +70,7 @@
 #' @param shape.legend.title String which sets the title of the shapes legend.  Default is \code{shape.by}
 #' @param assay,slot single strings or integers (SCEs and SEs) or an optionally named vector of such values that set which expression data to use.
 #' See \code{\link{GeneTargeting}} for specifics and examples -- Seurat and SingleCellExperiment objects deal with these differently, and functionality additions in dittoSeq have led to some minimal divergence from the native methodologies.
-#' @param adjustment When plotting gene / feature expression, should that data be used directly (default) or should it be adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating if numeric \code{var}-data should be used directly (default) or should be adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}

R/DittoScatterPlot.R

@@ -33,7 +33,7 @@
 #' @param colors Integer vector, the indexes / order, of colors from color.panel to actually use
 #' @param assay.x,assay.y,assay.color,assay.extra,slot.x,slot.y,slot.color,slot.extra single strings or integers (SCEs and SEs) or an optionally named vector of such values that set which expression data to use for each given data target.
 #' See \code{\link{GeneTargeting}} for specifics and examples -- Seurat and SingleCellExperiment objects deal with these differently, and functionality additions in dittoSeq have led to some minimal divergence from the native methodologies.
-#' @param adjustment.x,adjustment.y,adjustment.color,adjustment.extra For the given data target, when targeting gene / feature expression, should that data be used directly (default) or should it be adjusted to be
+#' @param adjustment.x,adjustment.y,adjustment.color,adjustment.extra \code{NULL} for off or a recognized string indicating if, for the given data target, when targeting numeric data, that data should be used directly (default) or should be adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}

R/dittoDotPlot.R

@@ -22,9 +22,9 @@
 #' adding \code{theme(strip.placement = "outside", strip.background.y = element_blank())} to the given \code{theme} (or 'x' counterpart depending on \code{vars.dir})
 #' @param summary.fxn.color,summary.fxn.size A function which sets how color or size will be used to summarize variables' data for each group.
 #' Any function can be used as long as it takes in a numeric vector and returns a single numeric value.
-#' @param scale String which sets whether the values shown with color (default: mean non-zero expression) should be centered and scaled. 
+#' @param scale String which sets whether the values shown with color should be centered and scaled after being summarized per \code{group.by} groups. 
 #' @param size Number which sets the visual dot size associated with the highest value shown by dot size (default: percent non-zero expression).
-#' @param adjustment Should expression data be used directly (default) or should it be adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating if \code{vars}-data should be used directly (default) or, prior to any potential scaling per groupings controlled via \code{scale}, should be adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}
@@ -597,7 +597,7 @@ dittoDotPlot <- function(
     )
 }
 
-#' @importFrom stats sd
+#' @importFrom stats sd setNames
 .multi_var_gather_raw <- function(
     object,
     vars,
@@ -623,7 +623,18 @@ dittoDotPlot <- function(
     }
 
     gets_data <- if (length(meta_gets)>0) {
-        getMetas(object, names.only = FALSE)[, meta_gets, drop = FALSE]
+        data.frame(
+            setNames(
+                lapply(
+                    meta_gets,
+                    function(m) {
+                        # Individual pulls for applying adjustments
+                        meta(m, object, adjustment, add.names = FALSE)
+                    }
+                ),
+                meta_gets),
+            row.names = .all_cells(object)
+        )
     } else {
         data.frame(row.names = .all_cells(object))
     }

R/dittoPlot.R

@@ -37,7 +37,7 @@
 #' See details section for more info.
 #' @param assay,slot single strings or integers (SCEs and SEs) or an optionally named vector of such values that set which expression data to use.
 #' See \code{\link{GeneTargeting}} for specifics and examples -- Seurat and SingleCellExperiment objects deal with these differently, and functionality additions in dittoSeq have led to some minimal divergence from the native methodologies.
-#' @param adjustment When plotting gene expression / feature counts, should that data be used directly (default) or should it be adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating if \code{var}-data should be used directly (default) or should be adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}

R/dittoPlotVarsAcrossGroups.R

@@ -15,7 +15,7 @@
 #' @param plots String vector which sets the types of plots to include: possibilities = "jitter", "boxplot", "vlnplot", "ridgeplot".
 #' Order matters: c("vlnplot", "boxplot", "jitter") will put a violin plot in the back, boxplot in the middle, and then individual dots in the front.
 #' See details section for more info.
-#' @param adjustment When plotting gene expression (or antibody, or other forms of counts data), should that data be used directly or should it be adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating if \code{var}-data should be used directly or should be adjusted to be
 #' \itemize{
 #' \item{"z-score": DEFAULT, centered and scaled to produce a relative-to-mean z-score representation}
 #' \item{NULL: no adjustment, the normal method for all other ditto expression plotting functions}

R/gene-getters.R

@@ -110,7 +110,7 @@ getGenes <- function(
 #' @param object A Seurat, SingleCellExperiment, or SummarizedExperiment object.
 #' @param assay,slot single strings or integers (SCEs and SEs) or a vector of such values that set which expression data to use.
 #' See \code{\link{GeneTargeting}} for specifics and examples -- Seurat and SingleCellExperiment objects deal with these differently, and functionality additions in dittoSeq have led to some minimal divergence from the native methodologies.
-#' @param adjustment Should expression data be used directly (default) or should it be adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating if expression data should be used directly (default) or should instead be adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}

R/meta-getters.R

@@ -86,11 +86,11 @@ getMetas <- function(object, names.only = TRUE){
 }
 
 #### meta: for extracting the values of a particular metadata for all cells/samples ####
-#' Returns the values of a meta.data  for all cells/samples
+#' Returns the values of a meta.data for all cells/samples
 #'
 #' @param meta String, the name of the "metadata" slot to grab. OR "ident" to retireve the clustering of a Seurat \code{object}.
 #' @param object A Seurat, SingleCellExperiment, or SummarizedExperiment object.
-#' @param adjustment A recognized string indicating whether numeric metadata should be used directly (default) versus adjusted to be
+#' @param adjustment \code{NULL} for off or a recognized string indicating whether numeric metadata should be used directly (default) versus adjusted to be
 #' \itemize{
 #' \item{"z-score": scaled with the scale() function to produce a relative-to-mean z-score representation}
 #' \item{"relative.to.max": divided by the maximum expression value to give percent of max values between [0,1]}
@@ -100,14 +100,15 @@ getMetas <- function(object, names.only = TRUE){
 #' @param adj.fxn A function which takes a vector (of metadata values) and returns a vector of the same length.
 #' 
 #' For example, \code{function(x) \{log2(x)\}} or \code{as.factor}
-#' @return A named vector.
+#' @param add.names Logical which sets whether cells'/samples' names should be added as names on the output.
+#' @return A vector
 #' @details
 #' Retrieves the values of a metadata slot from \code{object}, or the clustering slot if \code{meta = "ident"} and the \code{object} is a Seurat.
 #' 
 #' If \code{adjustment} or \code{adj.fxn} are provided, then these requested adjustments are applied to these values (\code{adjustment} first).
 #' Note: Alterations via \code{adjustment} are only applied when metadata is numeric, but \code{adj.fxn} alterations are applied to metadata of any type.
 #' 
-#' Lastly, outputs these values are named as the cells'/samples' names.
+#' Lastly, if \code{add.names = TRUE} the values are named as the cells'/samples' names before being output. 
 #' @seealso
 #' \code{\link{metaLevels}} for returning just the unique discrete identities that exist within a metadata slot
 #'
@@ -127,7 +128,7 @@ getMetas <- function(object, names.only = TRUE){
 #' @export
 
 meta <- function(meta, object,
-    adjustment = NULL, adj.fxn = NULL) {
+    adjustment = NULL, adj.fxn = NULL, add.names = TRUE) {
 
     if (!isMeta(meta, object)) {
         stop(dQuote(meta)," is not a metadata of 'object'")
@@ -165,7 +166,9 @@ meta <- function(meta, object,
     }
 
     # Add names
-    names(values) <- .all_cells(object)
+    if (add.names) {
+        names(values) <- .all_cells(object)
+    }
 
     values
 }

R/utils-getters.R

@@ -113,7 +113,7 @@
 
     if (length(var)==1 && is.character(var)) {
         if (isMeta(var, object)) {
-            OUT <- meta(var, object)
+            OUT <- meta(var, object, adjustment)
         } else if (isGene(var, object, assay)) {
             OUT <- gene(var, object, assay, slot, adjustment)
         }