Improve user guidance on rename() (#199)

Co-authored-by: Alex Richardson <alexjoerich@gmail.com>
Co-authored-by: alexjoerich <73207272+alexjoerich@users.noreply.github.com>
Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com>

.lintr

@@ -1,5 +1,6 @@
 linters: linters_with_defaults(
   line_length_linter = line_length_linter(120),
   cyclocomp_linter = NULL,
-  object_usage_linter = NULL
+  object_usage_linter = NULL,
+  object_name_linter = NULL
   )

R/HermesData-class.R

@@ -12,6 +12,7 @@ NULL
 #'
 #' @details The additional criteria are:
 #' - The first assay must be `counts` containing non-missing, integer, non-negative values.
+#'   Note that [rename()] can be used to edit the assay name to `counts` if needed.
 #' - The following columns must be in `rowData`:
 #'   - `symbol` (also often called `HGNC` or similar, example: `"INMT"`)
 #'   - `desc` (the gene name, example: `"indolethylamine N-methyltransferase"`)
@@ -49,6 +50,8 @@ NULL
 #' @aliases HermesData RangedHermesData AnyHermesData
 #' @exportClass HermesData RangedHermesData AnyHermesData
 #'
+#' @seealso [rename()] for renaming columns of the input data.
+#'
 #' @examples
 #' # Convert an `ExpressionSet` to a `RangedSummarizedExperiment`.
 #' ranged_summarized_experiment <- makeSummarizedExperimentFromExpressionSet(expression_set)

R/HermesData-methods.R

@@ -585,6 +585,8 @@ h_map_pos <- function(names, map) {
 #' @export
 #' @examples
 #' x <- summarized_experiment
+#' # Use deliberately a non-standard assay name in this example.
+#' assayNames(x) <- "count"
 #'
 #' # Rename `HGNC` to `symbol` in the `rowData`.
 #' x <- rename(x, row_data = c(symbol = "HGNC"))
@@ -594,8 +596,8 @@ h_map_pos <- function(names, map) {
 #' x <- rename(x, col_data = c(low_depth_flag = "LowDepthFlag"))
 #' tail(names(colData(x)))
 #'
-#' # Rename assay `counts` to `count`.
-#' x <- rename(x, assays = c(count = "counts"))
+#' # Rename assay `count` to `counts`.
+#' x <- rename(x, assays = c(counts = "count"))
 #' assayNames(x)
 setMethod(
   f = "rename",

R/HermesData-validate.R

@@ -29,7 +29,7 @@ NULL
 validate_counts <- function(object) {
   nams <- assayNames(object)
   if (!("counts" %in% nams)) {
-    return("no 'counts' assay found")
+    return("no 'counts' assay found, consider using rename() to change assay name")
   }
   if (nams[1] != "counts") {
     return("'counts' must be the first assay")

tests/testthat/test-HermesData-validate.R

@@ -11,7 +11,7 @@ test_that("validate_counts returns messages as expected for invalid objects", {
   object <- SummarizedExperiment(
     list(a = matrix(rnorm(4), 2, 2))
   )
-  expect_identical(validate_counts(object), "no 'counts' assay found")
+  expect_identical(validate_counts(object), "no 'counts' assay found, consider using rename() to change assay name")
 
   object <- SummarizedExperiment(
     list(a = matrix(rnorm(4), 2, 2), counts = matrix(1:4, 2, 2))

vignettes/hermes.Rmd

@@ -176,6 +176,22 @@ For the below, let's use the already prepared `HermesData` object.
 object <- hermes_data
 ```
 
+Likewise, when we receive the error "no 'counts' assay found", we can use the `rename()` function to change the name of the assay in the `SummarizedExperiment` object to `counts`. For example, the following object of type `SummarizedExperiment` would have the assay name `count`, and would produce the assay name error:
+
+```{r}
+object_exp <- summarized_experiment %>%
+  rename(assays = c(count = "counts"))
+```
+
+And we would use the following code to convert the assay name to `counts`, making it able to convert into `HermesData` object:
+
+```{r}
+object_exp <- rename(object_exp,
+  assays = c(counts = "count")
+)
+object_exp <- HermesData(object_exp)
+```
+
 ## Importing an `ExpressionSet`
 
 If we start from an `ExpressionSet`, we can first convert it to a `RangedSummarizedExperiment` and then import it to `RangedHermesData`: