MethPat-class: MethPat instances

In PeteHaitch/MethylationTuples: Tools for analysing methylation patterns at genomic tuples

Description

The MethPat class is a matrix-like container where rows represent genomic tuples of interest and columns represent samples (with sample data summarized as a DataFrame-class). A MethPat object contains the counts of how many times each methylation pattern is observed for that genomic tuple in each sample. For example, there are four possible methylation patterns at 2-tuples: MM, MU, UM and UU.

The MethPat class extends the SummarizedExperiment class. The key differences are:

• The rowRanges must be a MTuples object rather than a GRanges object.

• Certain assays are required. See assays argument below.

Arguments

assays	A list or SimpleList of matrix elements. All elements of the list must have the same dimensions, and dimension names (if present) must be consistent across elements and with row names of rowRanges and colData. Specifically, for a MethPat object containing the methylation patterns at genomic tuples of size = m, there are 2^m required assays. For example, for 2-tuples there are 4 required assays that must be named MM, MU, UM and UU (M = methylated, U = unmethylated). TODO: Should the .makeMethPatNames function be exported and referenced here?
rowRanges	A MTuples instance describing the genomic tuple of the methylation loci. Row names, if present, become the row names of the MethPat. The length of the MTuples must equal the number of rows of the matrices in assays.
colData	An optional, but recommended, DataFrame describing the samples. Row names, if present, become the column names of the MethPat.
exptData	An optional SimpleList of arbitrary content describing the overall experiment.
...	For MethPat, S4 methods list and matrix, arguments identical to those of the SimpleList method. For assay, ... may contain withDimnames, which is forwarded to assays. For cbind, rbind, ... contains MethPat objects to be combined. For other accessors, ignored.
verbose	A logical(1) indicating whether messages about data coerction during construction should be printed.
x,	object An instance of MethPat.
i,j	For assay, assay<-, i is an integer or numeric scalar; see 'Details' for additional constraints. For [,MethPat, [,MethPat<-, i, j are instances that can act to subset the underlying rowRanges, colData, and matrix elements of assays. For [[,MethPat, [[<-MethPat, i is a scalar index (e.g. character(1), or integer(1)) into a column of colData.
subset	An expression which, when evaluated in the context of rowRanges(x), is a logical vector indiciating elements or rows to keep: missing values are taken as false.
select	An expression which, when evaluated in the context of colData(x), is a logical vector indicating elements or rows to keep: missing values are taken as false.
name	A symbol representing the name of a column of colData.
withDimnames	A logical(1), indicating whether dimnames should be applied to extracted assay elements (this argument is ignored for the setter assays<-).
drop	A logical(1), ignored by these methods.
value	An instance of a class specified in the S4 method signature or as outlined in 'Details'.
deparse.level	See cbind for a description of this argument.

Constructor

Instances are constructed using the MethPat function with arguments outlined aboved.

Accessors

In the following code snippets, x is a MethPat instance.

assays(x), assays(x) <- value:

Get or set the assays. value is a list or SimpleList, each element of which is a matrix with the same dimensions as x.

assay(x, i), assay(x, i) <- value:

A conventient alternative (to assays(x)[[i]], assays(x)[[i]] <- value) to get or set the ith (default first) assay element. value must be a matrix of the same dimensions as x, and with dimension names NULL or consistent with those of x.

rowRanges(x), rowRanges(x) <- value:

Get or set the row data. value is a MTuples instance. Row names of value must be NULL or consistent with the existing row names of x.

colData(x), colData(x) <- value:

Get or set the column data. value is a DataFrame instance. Row names of value must be NULL or consistent with the existing columns of x.

exptData(x), exptData(x) <- value:

Get or set the experiment data. value is a list or SimpleList instance, with arbitrary content.

dim(x):

Get the dimensions (tuples x samples) of the MethPat object.

dimnames(x), dimnames(x) <- value:

Get or set the dimension names. value is usually a list of length 2, containing elements that are either NULL or vectors of appropriate length for the corresponding dimension. value can be NULL, which removes dimension names. This method implies that rownames, rownames<-, colnames, and colnames<- are all available.

MTuples/GTuples compatibility (rowRanges access)

Since an MTuples classes (used in the rowRanges) slot) extends the GTuples, many GTuples operations are supported on MetPath and derived instances, using rowRanges.

WARNING: The preferred getter/setter of tuple information is tuples(x)/tuples(x) <- value. In short, the use of granges(x), coderanges(x), ranges(x) <- value, start(x), start(x) <- value, end(x), end(x) <- value, width(x) and width(x) <- value is generally not what is really desired or required when working with MethPat objects; see GTuples for further discussion.

Supported operations include: compare, countOverlaps, distance, distanceToNearest, duplicated, end (not recommended, see above), end<- (not recommended, see above), findOverlaps, follow, granges (not recommended, see above), IPD, match, mcols, mcols<-, nearest, order, overlapsAny, precede, ranges (not recommended, see above), ranges<- (not recommended, see above), rank, relistToClass, restrict, seqinfo, seqinfo<-, seqnames, shift, size, sort, split, start (not recommended, see above), start<- (not recommended, see above), strand, strand<-, subsetByOverlaps, tuples, tuples<-, width (not recommended, see above), width<- (not recommended, see above).

Not all GTuples operations are supported, because they do not make sense for MethPat objects (e.g., length, name, as.data.frame, c, splitAsList), involve non-trivial combination or splitting of rows (e.g., unique), or have not yet been implemented (window, window<-).

Additionally, all MTuples-specific methods are also defined, such as methinfo and methtype.

Subsetting

x[i, j], x[i, j] <- value:

Create or replace a subset of x. i, j can be numeric, logical, character, or missing. value must be a MethPat instance with dimensions, dimension names, and assay elements consistent with the subset x[i, j] being replaced.

subset(x, subset, select):

Create a subset of x using an expression subset referring to columns of rowRanges(x) (including seqnames, start, end, width, strand, and names(mcols(x))) and / or select referring to column names of colData(x).

Additional subsetting accessors provide convenient access to colData columns

x$name, x$name <- value

Access or replace column name in x.

x[[i, ...]], x[[i, ...]] <- value

Access or replace column i in x.

Combining

In the code snippets below, x, y and ... are MethPat instances to be combined. All MethPat instances must have the same size tuples and have compatible seqinfo.

cbind(...), rbind(...):

cbind combines objects with identical tuples (rowRanges) but different samples (columns in assays). The colnames in colData must match or an error is thrown. Duplicate columns of mcols(rowRanges(MethPat)) must contain the same data.

rbind combines objects with different tuples (rowRanges) and the same subjects in (columns in assays). Duplicate columns of colData must contain the same data.

exptData from all objects are combined into a SimpleList with no name checking.

combine(x, y, ...):

combine combines objects with different tuples (rowRanges) and different samples (columns in assays) using an "incomplete" union strategy. Please read combine for the difference between the union and intersection strategies; the current method is "incomplete" because it requires that the samples (columns in assays) are distinct across x, y and .... This behaviour may change in future versions so that data from the same sample that is stored across multiple objects can be safely combined.

The colnames in colData must match or an error is thrown. Duplicate columns of mcols(rowRanges(MethPat)) must contain the same data.

exptData from all objects are combined into a SimpleList with no name checking.

Author(s)

Peter Hickey, building on all the real work of Martin Morgan for the SummarizedExperiment class.

See Also

SummarizedExperiment

Examples

## TODO

PeteHaitch/MethylationTuples documentation built on May 8, 2019, 1:30 a.m.