Interaction accessors {InteractionSet} | R Documentation

## 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))

[Package InteractionSet version 1.15.3 Index]