RangedSummarizedExperiment-class {SummarizedExperiment} | R Documentation

## RangedSummarizedExperiment objects

### Description

The RangedSummarizedExperiment class is a matrix-like container where rows represent ranges of interest (as a GRanges or GRangesList object) and columns represent samples (with sample data summarized as a DataFrame). A RangedSummarizedExperiment contains one or more assays, each represented by a matrix-like object of numeric or other mode.

RangedSummarizedExperiment is a subclass of SummarizedExperiment and, as such, all the methods documented in `class?SummarizedExperiment` also work on a RangedSummarizedExperiment object. The methods documented below are additional methods that are specific to RangedSummarizedExperiment objects.

### Usage

    ## Constructor

    SummarizedExperiment(assays=SimpleList(),
                         rowData=NULL, rowRanges=GRangesList(),
                         colData=DataFrame(),
                         metadata=list(),
                         checkDimnames=TRUE)

    ## Accessors

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

    ## Subsetting

    ## S4 method for signature 'RangedSummarizedExperiment'
    subset(x, subset, select, ...)

    ## rowRanges access
    ## see 'GRanges compatibility', below

### Arguments

`assays` | A `list` or `SimpleList` of matrix-like elements, or a matrix-like object (e.g. an ordinary matrix, a data frame, a DataFrame object from the S4Vectors package, a sparseMatrix derivative from the Matrix package, a DelayedMatrix object from the DelayedArray package, etc...). All elements of the list must have the same dimensions, and dimension names (if present) must be consistent across elements and with the row names of `rowRanges` and `colData`.
`rowData` | A DataFrame object describing the rows. Row names, if present, become the row names of the SummarizedExperiment object. The number of rows of the DataFrame must equal the number of rows of the matrices in `assays`.
`rowRanges` | A GRanges or GRangesList object describing the ranges of interest. Names, if present, become the row names of the SummarizedExperiment object. The length of the GRanges or GRangesList must equal the number of rows of the matrices in `assays`. If `rowRanges` is missing, a SummarizedExperiment instance is returned.
`colData` | An optional DataFrame describing the samples. Row names, if present, become the column names of the RangedSummarizedExperiment.
`metadata` | An optional `list` of arbitrary content describing the overall experiment.
`checkDimnames` | By default the rownames and colnames of the supplied assay(s) are checked for consistency with those of the SummarizedExperiment object (or derivative) to construct. More precisely, the rownames and colnames of each assay must be NULL or identical to those of the object. Use `checkDimnames=FALSE` to skip this check.
`x` | A RangedSummarizedExperiment object. The `rowRanges` setter will also accept a SummarizedExperiment object and will first coerce it to RangedSummarizedExperiment before it sets `value` on it.
`...` | Further arguments to be passed to or from other methods.
`value` | A GRanges or GRangesList object.
`subset` | An expression which, when evaluated in the context of `rowRanges(x)`, is a logical vector indicating 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.

### Details

The rows of a RangedSummarizedExperiment object represent ranges (in genomic coordinates) of interest. The ranges of interest are described by a GRanges or a GRangesList object, accessible using the `rowRanges` function, described below. The GRanges and GRangesList classes contains sequence (e.g., chromosome) name, genomic coordinates, and strand information. Each range can be annotated with additional data; this data might be used to describe the range or to summarize results (e.g., statistics of differential abundance) relevant to the range. Rows may or may not have row names; they often will not.

### Constructor

RangedSummarizedExperiment instances are constructed using the `SummarizedExperiment()` function with arguments outlined above.

### Accessors

In the following code snippets, `x` is a RangedSummarizedExperiment object.

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

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

### GRanges compatibility (rowRanges access)

Many GRanges and GRangesList operations are supported on RangedSummarizedExperiment objects, using `rowRanges`.

Supported operations include: `pcompare`, `duplicated`, `end`, `end<-`, `granges`, `is.unsorted`, `match`, `mcols`, `mcols<-`, `order`, `ranges`, `ranges<-`, `rank`, `seqinfo`, `seqinfo<-`, `seqnames`, `sort`, `start`, `start<-`, `strand`, `strand<-`, `width`, `width<-`.

See also `?shift`, `?isDisjoint`, `?coverage`, `?findOverlaps`, and `?nearest` for more GRanges compatibility methods.

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

### Subsetting

In the code snippets below, `x` is a RangedSummarizedExperiment object.

`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(rowData(x))`) and / or `select` referring to column names of `colData(x)`.

### Extension

RangedSummarizedExperiment is implemented as an S4 class, and can be extended in the usual way, using `contains="RangedSummarizedExperiment"` in the new class definition.

### Author(s)

Martin Morgan, mtmorgan@fhcrc.org

### See Also

- SummarizedExperiment-class

- shift, isDisjoint, coverage, findOverlaps, and nearest for more GRanges compatibility methods.

- GRanges objects in the GenomicRanges package.

### Examples

    nrows <- 200; ncols <- 6
    counts <- matrix(runif(nrows * ncols, 1, 1e4), nrows)
    rowRanges <- GRanges(rep(c("chr1", "chr2"), c(50, 150)),
                         IRanges(floor(runif(200, 1e5, 1e6)), width=100),
                         strand=sample(c("+", "-"), 200, TRUE),
                         feature_id=sprintf("ID%03d", 1:200))
    colData <- DataFrame(Treatment=rep(c("ChIP", "Input"), 3),
                         row.names=LETTERS[1:6])
    rse <- SummarizedExperiment(assays=SimpleList(counts=counts),
                                rowRanges=rowRanges, colData=colData)
    rse
    dim(rse)
    dimnames(rse)
    assayNames(rse)
    head(assay(rse))
    assays(rse) <- endoapply(assays(rse), asinh)
    head(assay(rse))

    rowRanges(rse)
    rowData(rse)  # same as 'mcols(rowRanges(rse))'
    colData(rse)

    rse[ , rse$Treatment == "ChIP"]

    ## cbind() combines objects with the same ranges but different samples:
    rse1 <- rse
    rse2 <- rse1[ , 1:3]
    colnames(rse2) <- letters[1:ncol(rse2)]
    cmb1 <- cbind(rse1, rse2)
    dim(cmb1)
    dimnames(cmb1)

    ## rbind() combines objects with the same samples but different ranges:
    rse1 <- rse
    rse2 <- rse1[1:50, ]
    rownames(rse2) <- letters[1:nrow(rse2)]
    cmb2 <- rbind(rse1, rse2)
    dim(cmb2)
    dimnames(cmb2)

    ## Coercion to/from SummarizedExperiment:
    se0 <- as(rse, "SummarizedExperiment")
    se0

    as(se0, "RangedSummarizedExperiment")

    ## Setting rowRanges on a SummarizedExperiment object turns it into a
    ## RangedSummarizedExperiment object:
    se <- se0
    rowRanges(se) <- rowRanges
    se  # RangedSummarizedExperiment

    ## Sanity checks:
    stopifnot(identical(assays(se0), assays(rse)))
    stopifnot(identical(dim(se0), dim(rse)))
    stopifnot(identical(dimnames(se0), dimnames(rse)))
    stopifnot(identical(rowData(se0), rowData(rse)))
    stopifnot(identical(colData(se0), colData(rse)))

[Package SummarizedExperiment version 1.24.0 Index]