conversion: Convert between classes

In LTLA/InteractionSet: Base Classes for Storing Genomic Interaction Data

Convert between classes

Description

Inflate a GInteractions or InteractionSet into a ContactMatrix, or deflate a ContactMatrix to an InteractionSet.

Usage

## S4 method for signature 'GInteractions'
inflate(x, rows, columns, fill=TRUE, swap=TRUE, sparse=FALSE, ...)

## S4 method for signature 'InteractionSet'
inflate(x, rows, columns, assay=1L, sample=1L, fill, swap=TRUE, sparse=FALSE, ...)

## S4 method for signature 'ContactMatrix'
deflate(x, collapse=TRUE, extract, use.zero, use.na, ...)

Arguments

x	A GInteractions or InteractionSet object for inflate, or a ContactMatrix object for deflate.
rows, columns	An integer, logical or character vector, a GRanges object or NULL, indicating the regions of interest to be used as the rows or columns of the ContactMatrix.
assay	A numeric scalar indicating the assay of the InteractionSet object, from which values are extracted to fill the ContactMatrix.
sample	A numeric scalar indicating the sample (i.e., column) of the assay to extract values to fill the ContactMatrix.
fill	A vector (usually logical or numeric) of length equal to nrow(x), containing values with which to fill the ContactMatrix. If specified, this overrides extraction of assay values for inflate,InteractionSet-method.
swap	A logical scalar indicating whether filling should also be performed after swapping anchor indices.
sparse	A logical scalar indicating whether the inflated matrix should use a sparseMatrix representation.
collapse	A logical scalar indicating whether duplicated interactions should be removed from x prior to deflation.
extract	A logical vector or matrix indicating which entries of x to convert into pairwise interactions.
use.zero, use.na	A logical scalar indicating whether to convert zero or NA entries into pairwise interactions.
...	For inflate, additional arguments to pass to overlapsAny when rows or columns is a GRanges. For deflate, additional arguments to pass to the InteractionSet constructor.

Value

For inflate, a ContactMatrix is returned.

For deflate, an InteractionSet object is returned.

Inflating to a ContactMatrix

The inflate method will return a ContactMatrix where the rows and columns correspond to specified regions of interest in rows and columns. Regions can be specified by supplying an object of various types:

• If it is an integer vector, it is assumed to refer to intervals in the regions slot of the input object x. Values of the vector need not be sorted or unique, but must lie within [1, regions(x)].

• If it is a logical vector, it will subset to retain intervals in regions(x) that are TRUE.

• If it is a character vector, it is assumed to contain the names of the reference sequences of interest (i.e., chromosome names).

• If it is a GRanges object, overlapsAny will be called to identify the overlapping intervals of regions(x).

• If it is NULL, all regions in regions(x) will be used to construct that dimension of the ContactMatrix.

For the GInteractions method, values in the matrix are filled based on user-supplied values in fill. Each element of fill corresponds to an interaction in x and is used to set the matrix entry at the matching row/column. Some entries of the matrix will correspond to pairwise interactions that are not present in x - these are filled with NA values.

By default, filling is repeated after swapping the anchor indices. This means that the value of the matrix at (1, 2) will be the same as that at (2, 1), i.e., the matrix is symmetric around the diagonal of the interaction space. However, if swap=FALSE, filling is performed so that the first and second anchor indices correspond strictly to rows and columns, respectively. This may be preferable if the order of the anchors contains some relevant information. In all cases, if duplicated interactions are present in x (and redundant permutations, when swap=TRUE), one will be arbitrarily chosen to fill the matrix.

For the InteractionSet inflate method, entries in the matrix are filled in based on the values in the first sample of the first assay when fill is missing. For more complex x, values from different assays and samples can be extracted using the assay and sample arguments. Note that if fill is specified, it will override any extraction of values from the assays.

If sparse=TRUE, inflate will return a ContactMatrix containing a sparseMatrix in the matrix slot. Here, entries without a corresponding interaction in x are set to zero, not NA. See below for some considerations when interpreting zeroes and NAs in contact matrices.

The default fill=TRUE has the effect of producing a logical sparse matrix in the output ContactMatrix, indicating which pairs of regions were present in x.

Deflating from a ContactMatrix

The deflate method will return an InteractionSet where each relevant entry in the ContactMatrix is converted into a pairwise interaction. Relevant entries are defined as those that are non-zero, if use.zero is FALSE; and non-NA, if use.na is FALSE. If x contains a sparseMatrix representation, the former is set to FALSE while the latter is set to TRUE, if either are not specified. For all other matrices, use.zero=TRUE and use.na=FALSE by default.

If extract is specified, this overrides all values of use.zero and use.na. A typical application would be to deflate a number of ContactMatrix objects with the same extract matrix. This ensures that the resulting InteractionSet objects can be easily combined with cbind, as the interactions are guaranteed to be the same. Otherwise, different interactions may be extracted depending on the presence of zero or NA values.

The values of all matrix entries are stored as a one-sample assay, with each value corresponding to its pairwise interaction after conversion. Duplicate interactions are removed by default, along with redundant permutations of the anchor indices. These can be included in the returned object by setting collapse=FALSE. This setting will also store the pairs as a GInteractions object, rather than using the default StrictGInteractions object where duplicates are not stored.

Additional arguments can be used to specify the colData and metadata, which are stored in the ContactMatrix itself.

Interpreting zeroes in a sparse matrix

Storing data as a sparseMatrix may be helpful as it is more memory-efficient for sparse areas of the interaction space. However, users should keep in mind that the zero values in the sparseMatrix may not represent zeroes in fill. The majority of these values are likely to be zero just because there was no corresponding interaction in x to set it to a non-zero value.

Whether or not this is a problem depends on the application. For example, if fill represents count data and only interactions with non-zero counts are stored in x, then setting all other entries to zero is sensible. However, in other cases, it is not appropriate to fill entries corresponding to missing interactions with zero. If fill represents, e.g., log-fold changes, then setting missing entries to a value of zero will be misleading. One could simply ignore zeroes altogether, though this will also discard entries that are genuinely zero.

These problems are largely avoided with the default dense matrices, where missing entries are simply set to NA.

Author(s)

Aaron Lun

See Also

InteractionSet-class, GInteractions-class, ContactMatrix-class, sparseMatrix-class

Examples

example(InteractionSet, echo=FALSE)

inflate(iset, 1:10, 1:10)
inflate(iset, 1:10, 1:10, sparse=TRUE)
inflate(iset, 1:10, 1:5+10)
inflate(iset, "chrA", 1:5+10)
inflate(iset, "chrA", "chrB")
inflate(iset, "chrA", GRanges("chrB", IRanges(1, 10)))

y <- inflate(iset, 1:10, 1:10)
iset2 <- deflate(y)
iset2
assay(iset2)

y <- inflate(iset, 1:10, 1:10, swap=FALSE)
iset2 <- deflate(y)
iset2
assay(iset2)

# Testing with different fillings:
y <- inflate(iset, 1:10, 1:10, sample=2)
iset2 <- deflate(y)
assay(iset2)

y <- inflate(iset, 1:10, 1:10, fill=rowSums(assay(iset)))
iset2 <- deflate(y)
assay(iset2)

y2 <- inflate(interactions(iset), 1:10, 1:10, rowSums(assay(iset)))
identical(y, y2) # should be TRUE

# Effect of 'collapse'
y <- inflate(iset, c(8, 1:10), 1:10)
deflate(y)
deflate(y, collapse=FALSE)

LTLA/InteractionSet documentation built on July 3, 2023, 8:44 a.m.