interaction-accessors: Interaction accessors

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

Interaction accessors

Description

Methods to get and set fields in an InteractionSet or GInteractions object.

Usage

## S4 method for signature 'GInteractions'
anchors(x, type="both", id=FALSE)
## S4 method for signature 'InteractionSet'
anchors(x, type="both", id=FALSE)

## S4 method for signature 'GInteractions'
anchorIds(x, type="both")
## S4 method for signature 'InteractionSet'
anchorIds(x, type="both")

## S4 method for signature 'GInteractions'
first(x)
## S4 method for signature 'InteractionSet'
first(x)

## S4 method for signature 'GInteractions'
second(x)
## S4 method for signature 'InteractionSet'
second(x)

## S4 method for signature 'GInteractions'
regions(x)
## S4 method for signature 'InteractionSet'
regions(x)

## S4 method for signature 'GInteractions'
seqinfo(x)
## S4 method for signature 'InteractionSet'
seqinfo(x)

## S4 method for signature 'GInteractions'
show(x)
## S4 method for signature 'InteractionSet'
show(x)

## S4 replacement method for signature 'GInteractions'
anchorIds(x, type="both") <- value
## S4 replacement method for signature 'InteractionSet'
anchorIds(x, type="both") <- value

## S4 replacement method for signature 'GInteractions'
regions(x) <- value
## S4 replacement method for signature 'InteractionSet'
regions(x) <- value

## S4 replacement method for signature 'GInteractions'
seqinfo(x, new2old = NULL, 
    pruning.mode = c("error", "coarse", "fine", "tidy")) <- value
## S4 replacement method for signature 'InteractionSet'
seqinfo(x, new2old = NULL, 
    pruning.mode = c("error", "coarse", "fine", "tidy")) <- value

## S4 replacement method for signature 'GInteractions'
replaceRegions(x) <- value
## S4 replacement method for signature 'InteractionSet'
replaceRegions(x) <- value

## S4 replacement method for signature 'GInteractions'
appendRegions(x) <- value
## S4 replacement method for signature 'InteractionSet'
appendRegions(x) <- value

## S4 method for signature 'GInteractions'
reduceRegions(x)
## S4 method for signature 'InteractionSet'
reduceRegions(x)

## S4 method for signature 'GInteractions'
names(x)
## S4 method for signature 'InteractionSet'
names(x)

## S4 replacement method for signature 'GInteractions'
names(x) <- value
## S4 replacement method for signature 'InteractionSet'
names(x) <- value

## S4 replacement method for signature 'StrictGInteractions'
anchors(x, type="both") <- value
## S4 replacement method for signature 'ReverseStrictGInteractions'
anchors(x, type="both") <- value

## S4 method for signature 'GInteractions'
length(x)
## S4 method for signature 'GInteractions'
as.data.frame(x, row.names=NULL, optional=FALSE, ...)
## S4 method for signature 'GInteractions'
x$name
## S4 replacement method for signature 'GInteractions'
x$name <- value

## S4 method for signature 'InteractionSet'
interactions(x)
## S4 replacement method for signature 'InteractionSet'
interactions(x) <- value

## S4 method for signature 'InteractionSet'
mcols(x, use.names=FALSE)
## S4 replacement method for signature 'InteractionSet'
mcols(x) <- value

Arguments

x	An InteractionSet or GInteractions object.
type	a string specifying which anchors are to be extracted or replaced.
id	a scalar logical indicating whether indices or GRanges should be returned.
new2old, pruning.mode	Additional arguments to pass to seqinfo,GRanges-method.
name	a string indicating the field of mcols to be accessed or modified for a GInteractions object.
value	For anchorIds<- and type="first" or "second", an integer vector of length equal to the number of rows in x. For type="both", a list of two such vectors must be supplied. For regions<-, a GRanges object of length equal to that of regions(x). For replaceRegions<-, a GRanges object that is a superset of all entries in regions(x) involved in interactions. For appendRegions<-, a GRanges of any length containing additional regions. For seqinfo<-, a SeqInfo object containing chromosome length data for all regions. For interactions<-, a GInteractions object of length equal to that of interactions(x). For mcols<-, a DataFrame with number of rows equal to the length of x. For names<-, a character vector of length equal to that of x.
row.names, optional, ...	Additional arguments, see ?as.data.frame for more details.
use.names	A logical scalar, see ?mcols for more details.

Value

For the getters, values in various slots of x are returned, while for the setters, the slots of x are modified accordingly – see Details.

Anchor manipulations for GInteractions

The return value of anchors varies depending on type and id:

• If id=FALSE, a GRanges object is returned containing the regions specified by the anchor1 or anchor2 slots in x, for type=="first" or "second", respectively. The first and second methods are synonyms for anchors in these respective cases.

• If id=FALSE and type="both", a list is returned with two entries first and second, containing regions specified by anchor1 and anchor2 respectively.

• If id=TRUE and type="both", a list is returned containing the two integer vectors in the anchor1 or anchor2 slots of x. Otherwise, each vector is returned corresponding to the requested value of type.

Note that anchorIds is the same as calling anchors with id=TRUE.

Replacement in anchorIds<- requires anchor indices rather than a GRanges object. If type="both", a list of two integer vectors is required in value, specifying the indices of the interacting regions in regions(x). If type="first" or "second", an integer vector is required to replace the existing values in the anchor1 or anchor2 slot, respectively. If the object is a StrictGInteractions, indices are automatically swapped so that anchor1 >= anchor2 for each interaction. The opposite applies if the object is a ReverseStrictGInteractions.

Region manipulations for GInteractions

For regions, a GRanges is returned equal to the regions slot in x. For regions<-, the GRanges in value is used to replace the regions slot. Resorting of the replacement GRanges is performed automatically, along with re-indexing of the anchors. In addition, the replacement must be of the same length as the existing object in the regions slot.

The replaceRegions replacement method can take variable length GRanges, but requires that the replacement contain (at least) all ranges contained in anchors(x). The appendRegions replacement method appends extra intervals to the existing regions slot of x. This is more efficient than calling replaceRegions on a concatenated object with regions(x) and the extra intervals.

The reduceRegions method will return a GInteractions object where the regions slot is reduced to only those entries used in anchors(x). This may save some memory in each object by removing unused regions. However, this is not recommended for large workflows with many GInteractions objects. R uses a copy-on-write memory management scheme, so only one copy of the GRanges in regions should be stored so long as it is not modified in different objects.

Other methods for GInteractions

For access and setting of all other slots, see Vector-class for details on the appropriate methods. This includes mcols or metadata, to store interactions-specific or experiment-wide metadata, respectively. The length method will return the number of interactions stored in x.

The show method will print out the class, the number of pairwise interactions, and the total number of regions in the GInteractions object. The number and names of the various metadata fields will also be printed. The as.data.frame method will return a data.frame object containing the coordinates for the two anchor regions as well as any element-wise metadata.

The seqinfo method will return the sequence information of the GRanges in the regions slot. This can be replaced with the seqinfo<- method – see ?Seqinfo for more details.

Details for InteractionSet

Almost all InteractionSet methods operate by calling the equivalent method for the GInteractions object, and returning the resulting value. The only exception is interactions, which returns the GInteractions object in the interactions slot of the InteractionSet object. This slot can also be set by supplying a valid GInteractions object in interactions<-.

The show method will print information equivalent to that done for a SummarizedExperiment object. An additional line is added indicating the number of regions in the regions slot of the object.

For access and setting of all other slots, see SummarizedExperiment-class for details on the appropriate methods. This includes assays, colData, mcols or metadata, which can all be applied to InteractionSet objects.

Handling different metadata

Note that there are several options for metadata - experiment-wide metadata, which goes into metadata(x)<-; region-specific metadata (e.g., adjacent genes, promoter/enhancer identity, GC content), which goes into mcols(regions(x))<-; and interaction-specific metadata (e.g., interaction distance, interaction type), which goes directly into mcols(x)<-. This is applicable to both GInteractions and InteractionSet objects. In addition, library-specific data (e.g., library size) should be placed into colData(x)<- for InteractionSet objects.

Users should take care with the differences in the $ and $<- operators between these two classes. For GInteractions objects, this will access or modify fields in the mcols slot, i.e., for interaction-specific metadata. For InteractionSet objects, this will access or modify fields in the colData slot, i.e., for library-specific data. The difference in behaviour is due to the concept of libraries in the InteractionSet, which is lacking in the GInteractions class.

For InteractionSet objects, the mcols getter and setter functions operate on the GInteractions object stored in interactions slot, rather than accessing the elementMetadata slot of the SummarizedExperiment base class. This makes no difference for practical usage in the vast majority of cases, except that any metadata stored in this manner is carried over when the GInteractions object is extracted with interactions(x). Similarly, the names getter and setter will operate the names of the internal GInteractions object. However, the metadata getter and setter will operate on the SummarizedExperiment base class, not on the internal GInteractions object.

Author(s)

Aaron Lun

See Also

GInteractions-class, InteractionSet-class, Vector-class, SummarizedExperiment-class

Examples

example(GInteractions, echo=FALSE) # Generate a nice object.
show(gi)

# Accessing anchor ranges or indices:
anchors(gi)
anchors(gi, type="first")
anchors(gi, id=TRUE)

anchors(gi, id=TRUE, type="first")
anchors(gi, id=TRUE, type="second")

# Modifying anchor indices:
nregs <- length(regions(gi))
mod <- list(sample(nregs, length(gi), replace=TRUE),
            sample(nregs, length(gi), replace=TRUE))
anchorIds(gi) <- mod
anchors(gi, id=TRUE, type="first")
anchors(gi, id=TRUE, type="second")

anchorIds(gi, type="both") <- mod
anchorIds(gi, type="first") <- mod[[1]]
anchorIds(gi, type="first") <- mod[[2]]

# Accessing or modifying regions:
regions(gi)
reduceRegions(gi)
regions(gi)$score <- runif(length(regions(gi)))

new.ranges <- c(regions(gi), resize(regions(gi), fix="center", width=50))
try(regions(gi) <- new.ranges) # Fails
replaceRegions(gi) <- new.ranges # Succeeds

length(regions(gi))
appendRegions(gi) <- GRanges("chrA", IRanges(5:10+1000, 1100+5:10), score=runif(6))
length(regions(gi))

seqinfo(gi)
seqinfo(gi) <- Seqinfo(seqnames=c("chrA", "chrB"), seqlengths=c(1000, 2000))

# Accessing or modifying metadata.
gi$score <- runif(length(gi))
mcols(gi)
as.data.frame(gi)

#################
# Same can be done for an InteractionSet object:

example(InteractionSet, echo=FALSE)

anchors(iset)
regions(iset)
reduceRegions(iset)
regions(iset)$score <- regions(gi)$score
replaceRegions(iset) <- new.ranges

seqinfo(iset)
seqinfo(iset) <- Seqinfo(seqnames=c("chrA", "chrB"), seqlengths=c(1000, 2000))

# Standard SE methods also available:
colData(iset)
metadata(iset)
mcols(iset)

# Note the differences in metadata storage:
metadata(iset)$name <- "metadata for SE0"
metadata(interactions(iset))$name <- "metadata for GI"

iset$lib.size <- runif(ncol(iset))*1e6
colData(iset)
mcols(iset) # untouched by "$" operator

mcols(iset)$whee <- runif(nrow(iset))
mcols(iset)
mcols(interactions(iset)) # preserved

names(iset) <- paste0("X", seq_along(iset))
names(iset)
names(interactions(iset))

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