diff --git a/R/MultiAssayExperiment-helpers.R b/R/MultiAssayExperiment-helpers.R index 021e3d7..876633a 100644 --- a/R/MultiAssayExperiment-helpers.R +++ b/R/MultiAssayExperiment-helpers.R @@ -10,47 +10,47 @@ NULL #' complete.cases,MultiAssayExperiment-method #' #' @description A set of helper functions were created to help clean and -#' manipulate a MultiAssayExperiment object. \code{intersectRows} also works -#' for \code{ExperimentList} objects. +#' manipulate a MultiAssayExperiment object. `intersectRows` also works +#' for `ExperimentList` objects. #' #' \itemize{ #' \item complete.cases: Returns a logical vector corresponding to 'colData' #' rows that have data across all experiments -#' \item isEmpty: Returns a logical \code{TRUE} value for zero length -#' \code{MultiAssayExperiment} objects +#' \item isEmpty: Returns a logical `TRUE` value for zero length +#' `MultiAssayExperiment` objects #' \item intersectRows: Takes all common rows across experiments, #' excludes experiments with empty rownames -#' \item intersectColumns: A wrapper for \code{complete.cases} to return a -#' \code{MultiAssayExperiment} with only those biological units that have +#' \item intersectColumns: A wrapper for `complete.cases` to return a +#' `MultiAssayExperiment` with only those biological units that have #' measurements across all experiments -#' \item replicated: Identifies, via logical vectors, \code{colname}s that +#' \item replicated: Identifies, via logical vectors, `colname`s that #' originate from a single biological unit within each assay -#' \item replicates: Provides the replicate \code{colname}s found with -#' the \code{replicated} function by their name, empty list if none +#' \item replicates: Provides the replicate `colname`s found with +#' the `replicated` function by their name, empty list if none #' \item anyReplicated: Whether the assay has replicate measurements #' \item showReplicated: Displays the actual columns that are replicated per #' assay and biological unit, i.e., \code{primary} value (\code{colData} -#' rowname) in the \code{sampleMap} +#' rowname) in the `sampleMap` #' \item mergeReplicates: A function that combines replicated / repeated #' measurements across all experiments and is guided by the replicated #' return value -#' \item longFormat: A \code{MultiAssayExperiment} method that -#' returns a small and skinny \link{DataFrame}. The \code{colDataCols} -#' arguments allows the user to append \code{colData} columns to the data. +#' \item longFormat: A `MultiAssayExperiment` method that +#' returns a small and skinny \link{DataFrame}. The `colDataCols` +#' arguments allows the user to append `colData` columns to the data. #' \item wideFormat: A function to reshape the data in a #' `MultiAssayExperiment` to a "wide" format \link{DataFrame}. Each row in #' the `DataFrame` represents an observation (corresponding to an entry in #' the `colData`). If replicates are present, their data will be appended at #' the end of the corresponding row and will generate additional `NA` data. #' It is recommended to remove or consolidate technical replicates with -#' `mergeReplicates`. Optional \code{colDataCols} can be added when the -#' original object is a \code{MultiAssayExperiment}. +#' `mergeReplicates`. Optional `colDataCols` can be added when the +#' original object is a `MultiAssayExperiment`. #' \item hasRowRanges: A function that identifies ExperimentList elements #' that have a \link[=RangedSummarizedExperiment-class]{rowRanges} method #' \item getWithColData: A convenience function for extracting an assay #' and associated colData #' \item renamePrimary: A convenience function to rename the primary -#' biological units as represented in the \code{rownames(colData)} +#' biological units as represented in the `rownames(colData)` #' \item renameColname: A convenience function to rename the colnames #' of a particular assay #' } @@ -114,10 +114,10 @@ setGeneric("replicated", function(x) standardGeneric("replicated")) #' @rdname MultiAssayExperiment-helpers #' -#' @details The \code{replicated} function finds replicate measurements in each +#' @details The `replicated` function finds replicate measurements in each #' assay and returns a list of \linkS4class{LogicalList}s. #' Each element in a single \linkS4class{LogicalList} corresponds to a -#' biological or \emph{primary} unit as in the \code{sampleMap}. Below is a +#' biological or \emph{primary} unit as in the `sampleMap`. Below is a #' small graphic for one particular biological unit in one assay, where the #' logical vector corresponds to the number of measurements/samples in the #' assay: @@ -127,14 +127,14 @@ setGeneric("replicated", function(x) standardGeneric("replicated")) #' (LogicalList str) '-- [[ "Biological Unit" ]] #' Replicated if sum(...) > 1 '-- TRUE TRUE FALSE FALSE #' } -#' \code{anyReplicated} determines if any of the assays have at least one +#' `anyReplicated` determines if any of the assays have at least one #' replicate. \emph{Note}. These methods are not available for the #' \code{ExperimentList} class due to a missing \code{sampleMap} structure #' (by design). #' \code{showReplicated} returns a list of \linkS4class{CharacterList}s where #' each element corresponds to the the biological or \emph{primary} units that #' are replicated in that assay element. The values in the inner list are -#' the \code{colnames} in the assay that are technical replicates. +#' the `colnames` in the assay that are technical replicates. #' #' @export setMethod("replicated", "MultiAssayExperiment", function(x) { @@ -191,9 +191,9 @@ setGeneric("replicates", function(x, ...) standardGeneric("replicates")) #' @rdname MultiAssayExperiment-helpers #' #' @details The \code{replicates} function (noun) returns the \code{colname}s -#' from the \code{sampleMap} that were identified as replicates. It returns a +#' from the `sampleMap` that were identified as replicates. It returns a #' list of \linkS4class{CharacterList}s for each assay present in the -#' \code{MultiAssayExperiment} and an inner entry for each biological unit +#' `MultiAssayExperiment` and an inner entry for each biological unit #' that has replicate observations in that assay. #' #' @export @@ -224,19 +224,19 @@ setGeneric("mergeReplicates", #' @rdname MultiAssayExperiment-helpers #' -#' @details The \code{mergeReplicates} function is a house-keeping method +#' @details The `mergeReplicates` function is a house-keeping method #' for a \code{MultiAssayExperiment} where only \code{complete.cases} are #' returned. This by-assay operation averages replicate measurements -#' (by default) and columns are aligned by the row order in \code{colData}. +#' (by default) and columns are aligned by the row order in `colData`. #' Users can provide their own function for merging replicates with the #' \code{simplify} functional argument. Additional inputs \code{\ldots} are #' sent to the 'simplify' function. #' #' @section mergeReplicates: -#' The \code{mergeReplicates} function makes use of the output from -#' \code{replicated} which will point out the duplicate measurements by -#' biological unit in the \code{MultiAssayExperiment}. This function will -#' return a \code{MultiAssayExperiment} with merged replicates. Additional +#' The `mergeReplicates` function makes use of the output from +#' `replicated` which will point out the duplicate measurements by +#' biological unit in the `MultiAssayExperiment`. This function will +#' return a `MultiAssayExperiment` with merged replicates. Additional #' arguments can be provided to the simplify argument via the ellipsis #' (\ldots). For example, when replicates "TCGA-B" and "TCGA-A" are found in #' the assay, the name of the first appearing replicate is taken (i.e., "B"). @@ -293,10 +293,10 @@ setMethod("mergeReplicates", "ExperimentList", #' @rdname MultiAssayExperiment-helpers #' -#' @details The \code{mergeReplicates} "ANY" method consolidates duplicate +#' @details The `mergeReplicates` "ANY" method consolidates duplicate #' measurements for rectangular data structures, returns object of the same -#' class (endomorphic). The ellipsis or \code{\ldots} argument allows the -#' user to provide additional arguments to the \code{simplify} functional +#' class (endomorphic). The ellipsis or `\ldots` argument allows the +#' user to provide additional arguments to the `simplify` functional #' argument. setMethod("mergeReplicates", "ANY", function(x, replicates = list(), simplify = BiocGenerics::mean, ...) { @@ -402,8 +402,8 @@ setMethod("mergeReplicates", "ANY", #' #' @aliases longFormat #' -#' @details The \code{longFormat} "ANY" class method, works with classes such as -#' \link{ExpressionSet} and \link{SummarizedExperiment} as well as \code{matrix} +#' @details The `longFormat` "ANY" class method, works with classes such as +#' \link{ExpressionSet} and \link{SummarizedExperiment} as well as `matrix` #' to provide a consistent long and skinny \link{DataFrame}. #' #' @section longFormat: @@ -411,15 +411,15 @@ setMethod("mergeReplicates", "ANY", #' in a \code{\link{MultiAssayExperiment}} and returns a uniform #' \code{\link{DataFrame}}. The resulting DataFrame has columns indicating #' primary, rowname, colname and value. This method can optionally include -#' columns of the MultiAssayExperiment colData named by \code{colDataCols} character +#' columns of the MultiAssayExperiment colData named by `colDataCols` character #' vector argument. (\code{MultiAssayExperiment} method only). The \code{i} argument #' allows the user to specify the assay value for the -#' \linkS4class{SummarizedExperiment} assay function's \code{i} argument. +#' \linkS4class{SummarizedExperiment} assay function's `i` argument. #' #' @param object Any supported class object #' #' @param colDataCols A \code{character}, \code{logical}, or \code{numeric} -#' index for \code{colData} columns to be included +#' index for `colData` columns to be included #' #' @param i longFormat: The i-th assay in #' \linkS4class{SummarizedExperiment}-like objects. A vector input is @@ -430,7 +430,7 @@ setMethod("mergeReplicates", "ANY", #' #' @param mode String indicating how \linkS4class{MultiAssayExperiment} #' column-level metadata should be added to the -#' \linkS4class{SummarizedExperiment} \code{colData}. +#' \linkS4class{SummarizedExperiment} `colData`. #' #' @export longFormat longFormat <- function(object, colDataCols = NULL, i = 1L) { @@ -508,21 +508,21 @@ longFormat <- function(object, colDataCols = NULL, i = 1L) { #' #' @section wideFormat: #' The \code{wideFormat} function returns standardized wide \link{DataFrame} -#' where each row represents a biological unit as in the \code{colData}. +#' where each row represents a biological unit as in the `colData`. #' Depending on the data and setup, biological units can be patients, tumors, #' specimens, etc. Metadata columns are #' generated based on the names produced in the wide format #' \linkS4class{DataFrame}. These can be accessed via the #' \link[=Vector-class]{mcols} function. #' See the \code{wideFormat} section for description of the \code{colDataCols} and -#' \code{i} arguments. +#' `i` arguments. #' #' @param check.names (logical default TRUE) Column names of the output -#' \code{DataFrame} will be checked for syntactic validity and made unique, +#' `DataFrame` will be checked for syntactic validity and made unique, #' if necessary #' #' @param collapse (character default "_") A single string delimiter for output -#' column names. In \code{wideFormat}, experiments and rownames (and when +#' column names. In `wideFormat`, experiments and rownames (and when #' replicate samples are present, colnames) are seperated by this delimiter #' #' @export wideFormat @@ -608,7 +608,7 @@ wideFormat <- function(object, colDataCols = NULL, check.names = TRUE, #' @aliases hasRowRanges #' #' @section hasRowRanges: -#' The \code{hasRowRanges} method identifies assays with associated ranged +#' The `hasRowRanges` method identifies assays with associated ranged #' row data by directly testing the method on the object. The result from the #' test must be a \linkS4class{GRanges} class object to satisfy the test. #' @@ -617,7 +617,7 @@ setGeneric("hasRowRanges", function(x) standardGeneric("hasRowRanges")) #' @rdname MultiAssayExperiment-helpers #' -#' @details The \code{hasRowRanges} method identifies assays that support +#' @details The `hasRowRanges` method identifies assays that support #' a \link[=RangedSummarizedExperiment-class]{rowRanges} method \emph{and} #' return a \linkS4class{GRanges} object. setMethod("hasRowRanges", "MultiAssayExperiment", function(x) { @@ -638,13 +638,13 @@ setMethod("hasRowRanges", "ExperimentList", function(x) { #' @aliases getWithColData #' #' @section getWithColData: -#' The \code{getWithColData} function allows the user to conveniently extract +#' The `getWithColData` function allows the user to conveniently extract #' a particular assay as indicated by the \strong{\code{i}} index argument. It #' will also attempt to provide the #' \code{\link[=SummarizedExperiment-class]{colData}} along with the -#' extracted object using the \code{colData<-} replacement +#' extracted object using the `colData<-` replacement #' method when possible. Typically, this method is available for -#' \linkS4class{SummarizedExperiment} and \code{RaggedExperiment} +#' \linkS4class{SummarizedExperiment} and `RaggedExperiment` #' classes. #' #' The setting of \code{mode} determines how the \code{\link{colData}} @@ -652,9 +652,9 @@ setMethod("hasRowRanges", "ExperimentList", function(x) { #' metadata is appended onto that of the \linkS4class{SummarizedExperiment}. #' If any fields are duplicated by name, the values in the #' \linkS4class{SummarizedExperiment} are retained, with a warning emitted if -#' the values are different. For \code{mode="replace"}, the +#' the values are different. For `mode="replace"`, the #' \linkS4class{MultiAssayExperiment} metadata replaces that of the -#' \linkS4class{SummarizedExperiment}, while for \code{mode="none"}, +#' \linkS4class{SummarizedExperiment}, while for `mode="none"`, #' no replacement or appending is performed. #' #' @export getWithColData @@ -711,17 +711,17 @@ getWithColData <- function(x, i, mode=c("append", "replace"), verbose = FALSE) { #' @aliases renamePrimary #' #' @section rename*: -#' The \code{renamePrimary} function allows the user to conveniently change the +#' The `renamePrimary` function allows the user to conveniently change the #' actual names of the primary biological units as seen in -#' \code{rownames(colData)}. \code{renameColname} allows the user to change the -#' names of a particular assay based on index \code{i}. \code{i} can either be -#' a single numeric or character value. See \code{colnames<-} method for -#' renaming multiple colnames in a \code{MultiAssayExperiment}. +#' `rownames(colData)`. `renameColname` allows the user to change the +#' names of a particular assay based on index `i`. `i` can either be +#' a single numeric or character value. See `colnames<-` method for +#' renaming multiple colnames in a `MultiAssayExperiment`. #' -#' @param value renamePrimary: A \code{character} vector of the same length as -#' the existing \code{rownames(colData)} to use for replacement, -#' renameColname: A \code{CharacterList} or \code{list} with matching -#' \code{lengths} to replace \code{colnames(x)} +#' @param value renamePrimary: A `character` vector of the same length as +#' the existing `rownames(colData)` to use for replacement, +#' renameColname: A `CharacterList` or `list` with matching +#' `lengths` to replace `colnames(x)` #' #' @examples #' @@ -789,7 +789,7 @@ renameColname <- function(x, i, value) { #' @aliases splitAssays #' #' @section splitAssays: -#' The \code{splitAssays} method separates columns in each of the assays based +#' The `splitAssays` method separates columns in each of the assays based #' on the \code{hitList} input. The \code{hitList} can be generated using #' the \code{makeHitList} helper function. To use the \code{makeHitList} #' helper, the user should input a list of patterns that will match on the @@ -800,7 +800,7 @@ renameColname <- function(x, i, value) { #' indicate groupings in the assays #' #' @param patternList a named \code{list} or \code{List} of atomic character -#' vectors that are the input to \code{grepl} for identifying groupings in +#' vectors that are the input to `grepl` for identifying groupings in #' the assays #' #' @export hasRowRanges