Last data update: 2014.03.03

 R: RangedSummarizedExperiment objects
RangedSummarizedExperiment-classR 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 ?SummarizedExperiment also work on a RangedSummarizedExperiment object. The methods documented below are additional methods that are specific to RangedSummarizedExperiment objects.

Usage


## Constructor

SummarizedExperiment(assays, ...)
## S4 method for signature 'SimpleList'
SummarizedExperiment(assays, rowData=NULL, rowRanges=GRangesList(),
    colData=DataFrame(), metadata=list())
## S4 method for signature 'ANY'
SummarizedExperiment(assays, ...)
## S4 method for signature 'list'
SummarizedExperiment(assays, ...)
## S4 method for signature 'missing'
SummarizedExperiment(assays, ...)

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

...

For SummarizedExperiment, S4 methods list and matrix, arguments identical to those of the SimpleList method.

For rowRanges, ignored.

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.

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 objects.

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

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(SummarizedExperiment)
Loading required package: GenomicRanges
Loading required package: BiocGenerics
Loading required package: parallel

Attaching package: 'BiocGenerics'

The following objects are masked from 'package:parallel':

    clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
    clusterExport, clusterMap, parApply, parCapply, parLapply,
    parLapplyLB, parRapply, parSapply, parSapplyLB

The following objects are masked from 'package:stats':

    IQR, mad, xtabs

The following objects are masked from 'package:base':

    Filter, Find, Map, Position, Reduce, anyDuplicated, append,
    as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
    get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
    match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
    rbind, rownames, sapply, setdiff, sort, table, tapply, union,
    unique, unsplit

Loading required package: S4Vectors
Loading required package: stats4

Attaching package: 'S4Vectors'

The following objects are masked from 'package:base':

    colMeans, colSums, expand.grid, rowMeans, rowSums

Loading required package: IRanges
Loading required package: GenomeInfoDb
Loading required package: Biobase
Welcome to Bioconductor

    Vignettes contain introductory material; view with
    'browseVignettes()'. To cite Bioconductor, see
    'citation("Biobase")', and for packages 'citation("pkgname")'.

> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/SummarizedExperiment/RangedSummarizedExperiment-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: RangedSummarizedExperiment-class
> ### Title: RangedSummarizedExperiment objects
> ### Aliases: class:RangedSummarizedExperiment
> ###   RangedSummarizedExperiment-class RangedSummarizedExperiment
> ###   SummarizedExperiment SummarizedExperiment,SimpleList-method
> ###   SummarizedExperiment,ANY-method SummarizedExperiment,list-method
> ###   SummarizedExperiment,missing-method
> ###   coerce,RangedSummarizedExperiment,SummarizedExperiment-method
> ###   coerce,SummarizedExperiment,RangedSummarizedExperiment-method
> ###   rowRanges rowRanges,RangedSummarizedExperiment-method rowRanges<-
> ###   rowRanges<-,SummarizedExperiment,GenomicRanges-method
> ###   rowRanges<-,SummarizedExperiment,GRangesList-method
> ###   names,RangedSummarizedExperiment-method
> ###   names<-,RangedSummarizedExperiment-method
> ###   dimnames,RangedSummarizedExperiment-method
> ###   dimnames<-,RangedSummarizedExperiment,list-method
> ###   Compare,ANY,RangedSummarizedExperiment-method
> ###   Compare,RangedSummarizedExperiment,ANY-method
> ###   Compare,RangedSummarizedExperiment,RangedSummarizedExperiment-method
> ###   pcompare,ANY,RangedSummarizedExperiment-method
> ###   pcompare,RangedSummarizedExperiment,ANY-method
> ###   pcompare,RangedSummarizedExperiment,RangedSummarizedExperiment-method
> ###   duplicated,RangedSummarizedExperiment-method
> ###   elementMetadata,RangedSummarizedExperiment-method
> ###   elementMetadata<-,RangedSummarizedExperiment-method
> ###   end,RangedSummarizedExperiment-method
> ###   end<-,RangedSummarizedExperiment-method
> ###   granges,RangedSummarizedExperiment-method
> ###   is.unsorted,RangedSummarizedExperiment-method
> ###   mcols,RangedSummarizedExperiment-method
> ###   mcols<-,RangedSummarizedExperiment-method
> ###   order,RangedSummarizedExperiment-method
> ###   ranges,RangedSummarizedExperiment-method
> ###   ranges<-,RangedSummarizedExperiment-method
> ###   rank,RangedSummarizedExperiment-method
> ###   seqinfo,RangedSummarizedExperiment-method
> ###   seqinfo<-,RangedSummarizedExperiment-method
> ###   seqnames,RangedSummarizedExperiment-method
> ###   sort,RangedSummarizedExperiment-method
> ###   split,RangedSummarizedExperiment-method
> ###   split,RangedSummarizedExperiment,ANY-method
> ###   start,RangedSummarizedExperiment-method
> ###   start<-,RangedSummarizedExperiment-method
> ###   strand,RangedSummarizedExperiment-method
> ###   strand<-,RangedSummarizedExperiment,ANY-method
> ###   subset,RangedSummarizedExperiment-method
> ###   width,RangedSummarizedExperiment-method
> ###   width<-,RangedSummarizedExperiment-method
> ###   updateObject,SummarizedExperiment-method
> 
> ### ** 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
class: RangedSummarizedExperiment 
dim: 200 6 
metadata(0):
assays(1): counts
rownames: NULL
rowData names(1): feature_id
colnames(6): A B ... E F
colData names(1): Treatment
> dim(rse)
[1] 200   6
> dimnames(rse)
[[1]]
NULL

[[2]]
[1] "A" "B" "C" "D" "E" "F"

> assayNames(rse)
[1] "counts"
> head(assay(rse))
             A        B         C         D         E         F
[1,]  247.4069 1154.466 2835.2760 5501.9503 2691.6858  532.7569
[2,] 1170.5513 8592.248 3439.3935 6329.1339 3453.6928 3929.5662
[3,] 5634.0339 5336.091 1364.3642 5851.8523  122.2751 4984.5100
[4,] 2975.9425 8105.029  684.6625  711.7588 1872.8639 9764.4094
[5,] 5710.7998 6949.351 5922.3405 1585.9983 9800.6678 4691.1308
[6,] 3898.8339 1957.751 2056.9608 9327.0136 7371.8619 2477.1258
> assays(rse) <- endoapply(assays(rse), asinh)
> head(assay(rse))
            A        B        C        D        E        F
[1,] 6.204186 7.744540 8.643042 9.306005 8.591070 6.971213
[2,] 7.758377 9.751763 8.836198 9.446066 8.840347 8.969432
[3,] 9.329728 9.275396 7.911591 9.367661 5.499437 9.207238
[4,] 8.691463 9.693387 7.222074 7.260887 8.228371 9.879647
[5,] 9.343262 9.539551 9.379634 8.062117 9.883353 9.146576
[6,] 8.961580 8.272699 8.322132 9.833817 9.598573 8.508001
> 
> rowRanges(rse)
GRanges object with 200 ranges and 1 metadata column:
        seqnames           ranges strand |  feature_id
           <Rle>        <IRanges>  <Rle> | <character>
    [1]     chr1 [130894, 130993]      + |       ID001
    [2]     chr1 [952309, 952408]      - |       ID002
    [3]     chr1 [432368, 432467]      + |       ID003
    [4]     chr1 [730934, 731033]      + |       ID004
    [5]     chr1 [711599, 711698]      + |       ID005
    ...      ...              ...    ... .         ...
  [196]     chr2 [577352, 577451]      - |       ID196
  [197]     chr2 [284839, 284938]      + |       ID197
  [198]     chr2 [567210, 567309]      - |       ID198
  [199]     chr2 [843932, 844031]      + |       ID199
  [200]     chr2 [833334, 833433]      - |       ID200
  -------
  seqinfo: 2 sequences from an unspecified genome; no seqlengths
> rowData(rse)  # same as 'mcols(rowRanges(rse))'
DataFrame with 200 rows and 1 column
     feature_id
    <character>
1         ID001
2         ID002
3         ID003
4         ID004
5         ID005
...         ...
196       ID196
197       ID197
198       ID198
199       ID199
200       ID200
> colData(rse)
DataFrame with 6 rows and 1 column
    Treatment
  <character>
A        ChIP
B       Input
C        ChIP
D       Input
E        ChIP
F       Input
> 
> rse[, rse$Treatment == "ChIP"]
class: RangedSummarizedExperiment 
dim: 200 3 
metadata(0):
assays(1): counts
rownames: NULL
rowData names(1): feature_id
colnames(3): A C E
colData names(1): Treatment
> 
> ## 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)
[1] 200   9
> dimnames(cmb1)
[[1]]
NULL

[[2]]
[1] "A" "B" "C" "D" "E" "F" "a" "b" "c"

> 
> ## 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)
[1] 250   6
> dimnames(cmb2)
[[1]]
  [1] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
 [19] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
 [37] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
 [55] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
 [73] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
 [91] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[109] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[127] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[145] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[163] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[181] ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  ""  "" 
[199] ""  ""  "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p"
[217] "q" "r" "s" "t" "u" "v" "w" "x" "y" "z" NA  NA  NA  NA  NA  NA  NA  NA 
[235] NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA  NA 

[[2]]
[1] "A" "B" "C" "D" "E" "F"

> 
> ## Coercion to/from SummarizedExperiment:
> se0 <- as(rse, "SummarizedExperiment")
> se0
class: SummarizedExperiment 
dim: 200 6 
metadata(0):
assays(1): counts
rownames: NULL
rowData names(1): feature_id
colnames(6): A B ... E F
colData names(1): Treatment
> 
> as(se0, "RangedSummarizedExperiment")
class: RangedSummarizedExperiment 
dim: 200 6 
metadata(0):
assays(1): counts
rownames: NULL
rowData names(0):
colnames(6): A B ... E F
colData names(1): Treatment
> 
> ## Setting rowRanges on a SummarizedExperiment object turns it into a
> ## RangedSummarizedExperiment object:
> se <- se0
> rowRanges(se) <- rowRanges
> se  # RangedSummarizedExperiment
class: RangedSummarizedExperiment 
dim: 200 6 
metadata(0):
assays(1): counts
rownames: NULL
rowData names(1): feature_id
colnames(6): A B ... E F
colData names(1): Treatment
> 
> ## 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)))
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>


Created & Maintained by Osamu Ogasawara (osamu.ogasawara@gmail.com) and IMSBIO