141: Polish documentation of hermes. (#176)

DESCRIPTION

@@ -46,6 +46,7 @@ Imports:
     utils.nest (>= 0.2.9)
 Suggests:
     DT,
+    grid,
     knitr,
     test.nest (>= 0.2.9),
     testthat (>= 2.0),

R/HermesData-class.R

@@ -55,9 +55,11 @@ NULL
 #' @importFrom S4Vectors setValidity2
 #'
 #' @examples
-#' # Convert to `SummarizedExperiment` using the default naive range mapper.
-#' se <- makeSummarizedExperimentFromExpressionSet(expression_set)
-#' # Then convert to `HermesData`.
+#' # Convert an `ExpressionSet` to a `RangedSummarizedExperiment`.
+#' ranged_summarized_experiment <- makeSummarizedExperimentFromExpressionSet(expression_set)
+#'
+#' # Then convert to `RangedHermesData`.
+#' HermesData(ranged_summarized_experiment)
 .HermesData <- setClass( # nolint
   "HermesData",
   contains = "SummarizedExperiment",
@@ -94,17 +96,15 @@ S4Vectors::setValidity2("AnyHermesData", function(object) {
 # HermesData-constructors ----
 
 #' @rdname HermesData-class
-#' @param object (`SummarizedExperiment`)\cr input to create [`HermesData`] from.
+#' @param object (`SummarizedExperiment`)\cr input to create the [`HermesData`] object from.
 #'   If this is a `RangedSummarizedExperiment`, then the result will be
 #'   [`RangedHermesData`].
 #' @export
 #' @examples
-#' # Create objects starting from a `SummarizedExperiment.`
+#'
+#' # Create objects starting from a `SummarizedExperiment`.
 #' hermes_data <- HermesData(summarized_experiment)
 #' hermes_data
-#' ranged_summarized_experiment <- as(summarized_experiment, "RangedSummarizedExperiment")
-#' ranged_hermes_data <- HermesData(ranged_summarized_experiment)
-#' ranged_hermes_data
 HermesData <- function(object) { # nolint
   assert_that(
     is_class(object, "SummarizedExperiment"),
@@ -143,13 +143,10 @@ HermesData <- function(object) { # nolint
 #'   is passed instead of `rowData`, then the result will be a [`RangedHermesData`] object.
 #' @export
 #' @examples
-#' # Create objects from a matrix and additional arguments.
+#'
+#' # Create objects from a matrix. Note that additional arguments are not required but possible.
 #' counts_matrix <- assay(summarized_experiment)
-#' HermesDataFromMatrix(
-#'   counts = counts_matrix,
-#'   rowData = rowData(summarized_experiment),
-#'   colData = colData(summarized_experiment)
-#' )
+#' counts_hermes_data <- HermesDataFromMatrix(counts_matrix)
 HermesDataFromMatrix <- function(counts, ...) { # nolint
   assert_that(is.matrix(counts))
 

R/HermesData-methods.R

@@ -7,27 +7,29 @@
 #' This method combines [`AnyHermesData`] objects with the same samples but different
 #' features of interest (rows in assays).
 #'
-#' @note Note that this just inherits
-#'   [SummarizedExperiment::rbind,SummarizedExperiment-method()]. When binding a
-#'   [`AnyHermesData`] object with a [`SummarizedExperiment::SummarizedExperiment`]
-#'   object, then the result will be a
-#'   [`SummarizedExperiment::SummarizedExperiment`] object (the more general
-#'   class).
+#' @note
+#'   - Note that this just inherits
+#'     [SummarizedExperiment::rbind,SummarizedExperiment-method()]. When binding a
+#'     [`AnyHermesData`] object with a [`SummarizedExperiment::SummarizedExperiment`]
+#'     object, then the result will be a
+#'     [`SummarizedExperiment::SummarizedExperiment`] object (the more general
+#'     class).
+#'   - Note that we need to have unique gene IDs (row names) and the same prefix
+#'     across the combined object.
 #'
 #' @name rbind
 #'
 #' @param ... (`AnyHermesData`)\cr objects to row bind.
 #'
 #' @return The combined [`AnyHermesData`] object.
 #'
+#' @seealso [`cbind`] to column bind objects.
+#'
 #' @examples
-#' a <- HermesData(summarized_experiment[1:2542])
-#' b <- HermesData(summarized_experiment[2543: 5085])
+#' a <- HermesData(summarized_experiment[1:2542, ])
+#' b <- HermesData(summarized_experiment[2543:5085, ])
 #' result <- rbind(a, b)
 #' class(result)
-#'
-#' result2 <- rbind(summarized_experiment, b)
-#' class(result2)
 NULL
 
 # cbind ----
@@ -39,27 +41,28 @@ NULL
 #' This method combines [`AnyHermesData`] objects with the same ranges but different
 #' samples (columns in assays).
 #'
-#' @note Note that this just inherits
-#'   [SummarizedExperiment::cbind,SummarizedExperiment-method()]. When binding a
-#'   [`AnyHermesData`] object with a [`SummarizedExperiment::SummarizedExperiment`]
-#'   object, then the result will be a
-#'   [`SummarizedExperiment::SummarizedExperiment`] object (the more general
-#'   class).
+#' @note
+#'   - Note that this just inherits
+#'     [SummarizedExperiment::cbind,SummarizedExperiment-method()]. When binding a
+#'     [`AnyHermesData`] object with a [`SummarizedExperiment::SummarizedExperiment`]
+#'     object, then the result will be a
+#'     [`SummarizedExperiment::SummarizedExperiment`] object (the more general
+#'     class).
+#'   - Note that the combined object needs to have unique sample IDs (column names).
 #'
 #' @name cbind
 #'
 #' @param ... (`AnyHermesData`)\cr objects to column bind.
 #'
 #' @return The combined [`AnyHermesData`] object.
 #'
+#' @seealso [`rbind`] to row bind objects.
+#'
 #' @examples
 #' a <- HermesData(summarized_experiment[, 1:10])
 #' b <- HermesData(summarized_experiment[, 11:20])
 #' result <- cbind(a, b)
 #' class(result)
-#'
-#' result2 <- cbind(summarized_experiment[, 1:10], b)
-#' class(result2)
 NULL
 
 # metadata ----
@@ -75,6 +78,7 @@ NULL
 #' @name metadata
 #'
 #' @param x (`AnyHermesData`)\cr object to access the metadata from.
+#' @param value (`list`)\cr the list to replace the current metadata with.
 #'
 #' @return The metadata which is a list.
 #' @importFrom S4Vectors `metadata<-`
@@ -100,7 +104,7 @@ NULL
 #' @rdname annotation
 #' @aliases annotation
 #'
-#' @param object (`AnyHermesData`)\cr object to access the counts from.
+#' @param object (`AnyHermesData`)\cr object to access the annotations from.
 #' @param ... not used.
 #'
 #' @return The [`S4Vectors::DataFrame`] with the gene annotations:
@@ -128,7 +132,7 @@ setMethod(
 )
 
 #' @rdname annotation
-#' @note - The returned column names are available in the exported
+#' @format The annotation column names are available in the exported
 #'   character vector `.row_data_annotation_cols`.
 #' @export
 .row_data_annotation_cols <- c(
@@ -142,9 +146,9 @@ setMethod(
   "ProteinTranscript"
 )
 
-#' @param value (`matrix`)\cr what should the counts assay be replaced with.
+#' @param value (`DataFrame`)\cr what should the annotations be replaced with.
 #'
-#' @note - When trying to replace the annotation with completely missing values for any genes,
+#' @note When trying to replace the annotation with completely missing values for any genes,
 #'   a warning will be given and the corresponding gene IDs will be saved in the
 #'   attribute `annotation.missing.genes`.
 #'
@@ -257,6 +261,8 @@ setGeneric("prefix", def = function(object, ...) {
 #'
 #' @return The character vector with the gene IDs.
 #'
+#' @seealso [samples()] to access the sample IDs.
+#'
 #' @export
 setGeneric("genes", def = function(object) standardGeneric("genes"))
 
@@ -289,6 +295,8 @@ setMethod(
 #' @rdname samples
 #' @aliases samples
 #'
+#' @seealso [genes()] to access the gene IDs.
+#'
 #' @importFrom Biobase samples
 #' @export
 #' @examples
@@ -317,12 +325,25 @@ setMethod(
 #' @name subset
 #'
 #' @param x (`AnyHermesData`)\cr object to subset from.
+#' @param subset (`expression`)\cr logical expression based on the `rowData` columns to
+#'   select genes.
+#' @param select (`expression`)\cr logical expression based on the `colData` columns to
+#'   select samples.
+#'
 #' @return The subsetted [`AnyHermesData`] object.
 #'
 #' @examples
 #' a <- HermesData(summarized_experiment)
 #' a
+#'
+#' # Subset both genes and samples.
 #' subset(a, subset = LowExpressionFlag, select = DISCSTUD == "N")
+#'
+#' # Subset only genes.
+#' subset(a, subset = Chromosome == "2")
+#'
+#' # Subset only samples.
+#'subset(a, select = AGE > 18)
 NULL
 
 # filter ----
@@ -353,6 +374,7 @@ setGeneric("filter", function(object, ...) standardGeneric("filter"))
 #' @return Named logical vector with one value for each gene in `object`, which is `TRUE` if all
 #'   required annotation columns are filled, and otherwise `FALSE`.
 #'
+#' @seealso [filter()] where this is used internally.
 #' @export
 #'
 #' @examples
@@ -392,13 +414,19 @@ h_has_req_annotations <- function(object,
 #' @examples
 #' a <- HermesData(summarized_experiment)
 #' dim(a)
+#'
 #' # Filter genes and samples on default QC flags.
 #' result <- filter(a)
 #' dim(result)
+#'
 #' # Filter only genes without low expression.
 #' result <- filter(a, what = "genes")
+#'
 #' # Filter only samples with low depth and technical failure.
 #' result <- filter(a, what = "samples")
+#'
+#' # Filter only genes, and require certain annotations to be present.
+#' result <- filter(a, what = "genes", annotation_required = c("StartBP", "EndBP", "WidthBP"))
 setMethod(
   f = "filter",
   signature = signature(object = "AnyHermesData"),
@@ -584,6 +612,7 @@ setMethod(
 #' @export
 #'
 #' @examples
+#'
 #' # Just calling the summary method like this will use the `show()` method.
 #' summary(object)
 setMethod(

R/HermesData-validate.R

@@ -106,7 +106,7 @@ validate_names <- function(object) {
 }
 
 #' @describeIn validate validates that the object prefix is a string
-#' without whitespace, special characters or digits.
+#'   and only contains alphabetic characters.
 validate_prefix <- function(object) {
   prefix <- object@prefix
   msg <- NULL

R/assertthat.R

@@ -5,54 +5,58 @@
 #' We provide additional assertion functions which can be used together with
 #' [assertthat::assert_that()].
 #'
+#' @param x an object to check.
+#'
 #' @name assertions
 #' @import assertthat
 NULL
 
 # is_class ----
 
 #' @describeIn assertions checks the class.
-#' @param object any object.
-#' @param class2 (`character` or class definition)\cr the class to which `object` could belong.
+#' @param class2 (`character` or class definition)\cr the class to which `x` could belong.
 #' @export
 #' @examples
+#' # Assert a general class.
 #' a <- 5
 #' is_class(a, "character")
-is_class <- function(object, class2) {
-  is(object, class2)
+is_class <- function(x, class2) {
+  is(x, class2)
 }
 
 on_failure(is_class) <- function(call, env) {
-  obj_name <- deparse(call$object)
+  obj_name <- deparse(call$x)
   class <- eval(call$class2, env)
   paste(obj_name, "is not of class", class)
 }
 
 # is_hermes_data ----
 
-#' @describeIn assertions checks the class.
-#' @param object any object.
+#' @describeIn assertions checks whether `x` is an [`AnyHermesData`] object.
 #' @export
 #' @examples
+#'
+#' # Assert a `AnyHermesData` object.
 #' is_hermes_data(HermesData(summarized_experiment))
 #' is_hermes_data(42)
-is_hermes_data <- function(object) {
-  is_class(object, "AnyHermesData")
+is_hermes_data <- function(x) {
+  is_class(x, "AnyHermesData")
 }
 
 on_failure(is_hermes_data) <- function(call, env) {
-  obj_name <- deparse(call$object)
+  obj_name <- deparse(call$x)
   paste(obj_name, "is not a HermesData or RangedHermesData object")
 }
 
 # is_counts_vector ----
 
 #' @describeIn assertions checks for a vector of counts (positive integers).
-#' @param x vector to check.
 #' @export
 #' @examples
-#' a <- 5
-#' is_class(a, "character")
+#'
+#' # Assert a counts vector.
+#' a <- 5L
+#' is_counts_vector(a)
 is_counts_vector <- function(x) {
   is.integer(x) && all(x > 0) && noNA(x) && not_empty(x)
 }
@@ -69,6 +73,8 @@ on_failure(is_counts_vector) <- function(call, env) {
 #' @importFrom utils.nest is_character_vector is_fully_named_list
 #' @export
 #' @examples
+#'
+#' # Assert a list containing certain elements.
 #' b <- list(a = 5, b = 3)
 #' is_list_with(b, c("a", "c"))
 #' is_list_with(b, c("a", "b"))
@@ -89,12 +95,14 @@ on_failure(is_list_with) <- function(call, env) {
 
 # one_provided ----
 
-#' @describeIn assertions checks that exactly one of two inputs is not `NULL`.
+#' @describeIn assertions checks that exactly one of the two inputs `one`, `two` is not `NULL`.
 #' @param one first input.
 #' @param two second input.
 #' @export
 #'
 #' @examples
+#'
+#' # Assert that exactly one of two arguments is provided.
 #' a <- 10
 #' b <- 10
 #' one_provided(a, b)
@@ -115,11 +123,13 @@ on_failure(one_provided) <- function(call, env) {
 
 # is_constant ----
 
-#' @describeIn assertions checks for a column being constant.
-#' @param x An object to check.
+#' @describeIn assertions checks whether the vector `x` is constant (only supports `numeric`, `factor`,
+#'   `character`, `logical`). `NA`s are removed first.
 #' @export
 #'
 #' @examples
+#'
+#' # Assert a constant vector.
 #' is_constant(c(1, 2))
 #' is_constant(c(NA, 1))
 #' is_constant(c("a", "a"))