use markdown in docs

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,24 +402,24 @@ 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:
 #' The 'longFormat' method takes data from the \code{\link{ExperimentList}}
 #' 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,23 +638,23 @@ 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}}
 #' is added. If \code{mode="append"}, the \linkS4class{MultiAssayExperiment}
 #' 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