RaggedExperiment-class {RaggedExperiment}R Documentation

RaggedExperiment objects

Description

The RaggedExperiment class is a container for storing range-based data, including but not limited to copy number data, and mutation data. It can store a collection of GRanges objects, as it is derived from the GenomicRangesList.

Usage

RaggedExperiment(..., colData = DataFrame())

## S4 method for signature 'RaggedExperiment'
rowRanges(x, ...)

## S4 method for signature 'RaggedExperiment'
mcols(x, use.names = FALSE, ...)

## S4 replacement method for signature 'RaggedExperiment'
mcols(x, ...) <- value

## S4 method for signature 'RaggedExperiment'
rowData(x, ...)

## S4 replacement method for signature 'RaggedExperiment'
rowData(x, ...) <- value

## S4 method for signature 'RaggedExperiment'
dim(x)

## S4 method for signature 'RaggedExperiment'
dimnames(x)

## S4 replacement method for signature 'RaggedExperiment,list'
dimnames(x) <- value

## S4 method for signature 'RaggedExperiment'
length(x)

## S4 method for signature 'RaggedExperiment'
colData(x, ...)

## S4 replacement method for signature 'RaggedExperiment,DataFrame'
colData(x) <- value

## S4 method for signature 'RaggedExperiment,missing'
assay(x, i, ...)

## S4 method for signature 'RaggedExperiment,ANY'
assay(x, i, ..., withDimnames = TRUE)

## S4 method for signature 'RaggedExperiment'
assays(x, ..., withDimnames = TRUE)

## S4 method for signature 'RaggedExperiment'
assayNames(x, ...)

## S4 method for signature 'RaggedExperiment'
show(object)

## S4 method for signature 'RaggedExperiment,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'RaggedExperiment,Vector'
overlapsAny(query, subject, maxgap = 0L,
  minoverlap = 1L, type = c("any", "start", "end", "within", "equal"), ...)

## S4 method for signature 'RaggedExperiment,Vector'
subsetByOverlaps(x, ranges, maxgap = -1L,
  minoverlap = 0L, type = c("any", "start", "end", "within", "equal"),
  invert = FALSE, ...)

Arguments

...

Constructor: GRanges, list of GRanges, or GRangesList OR assay: Additional arguments for assay. See details for more information.

colData

A DataFrame describing samples. Length of rowRanges must equal the number of rows in colData

x

A RaggedExperiment object.

use.names

(logical default FALSE) whether to propagate rownames from the object to rownames of metadata DataFrame

value
  • dimnames: A list of dimension names

  • mcols: A DataFrame representing the assays

i

logical(1), integer(1), or character(1) indicating the assay to be reported. For [, i can be any supported Vector object, e.g., GRanges.

withDimnames

logical (default TRUE) whether to use dimension names in the resulting object

object

A RaggedExperiment object.

j

integer(), character(), or logical() index selecting columns from RaggedExperiment

drop

logical (default TRUE) whether to drop empty samples

query

A RaggedExperiment instance.

subject

Each of them can be an IntegerRanges (e.g. IRanges, Views) or IntegerRangesList (e.g. IRangesList, ViewsList) derivative. In addition, if subject or ranges is an IntegerRanges object, query or x can be an integer vector to be converted to length-one ranges.

If query (or x) is an IntegerRangesList object, then subject (or ranges) must also be an IntegerRangesList object.

If both arguments are list-like objects with names, each list element from the 2nd argument is paired with the list element from the 1st argument with the matching name, if any. Otherwise, list elements are paired by position. The overlap is then computed between the pairs as described below.

If subject is omitted, query is queried against itself. In this case, and only this case, the drop.self and drop.redundant arguments are allowed. By default, the result will contain hits for each range against itself, and if there is a hit from A to B, there is also a hit for B to A. If drop.self is TRUE, all self matches are dropped. If drop.redundant is TRUE, only one of A->B and B->A is returned.

maxgap

A single integer >= -1.

If type is set to "any", maxgap is interpreted as the maximum gap that is allowed between 2 ranges for the ranges to be considered as overlapping. The gap between 2 ranges is the number of positions that separate them. The gap between 2 adjacent ranges is 0. By convention when one range has its start or end strictly inside the other (i.e. non-disjoint ranges), the gap is considered to be -1.

If type is set to anything else, maxgap has a special meaning that depends on the particular type. See type below for more information.

minoverlap

A single non-negative integer.

Only ranges with a minimum of minoverlap overlapping positions are considered to be overlapping.

When type is "any", at least one of maxgap and minoverlap must be set to its default value.

type

By default, any overlap is accepted. By specifying the type parameter, one can select for specific types of overlap. The types correspond to operations in Allen's Interval Algebra (see references). If type is start or end, the intervals are required to have matching starts or ends, respectively. Specifying equal as the type returns the intersection of the start and end matches. If type is within, the query interval must be wholly contained within the subject interval. Note that all matches must additionally satisfy the minoverlap constraint described above.

The maxgap parameter has special meaning with the special overlap types. For start, end, and equal, it specifies the maximum difference in the starts, ends or both, respectively. For within, it is the maximum amount by which the subject may be wider than the query. If maxgap is set to -1 (the default), it's replaced internally by 0.

ranges

Each of them can be an IntegerRanges (e.g. IRanges, Views) or IntegerRangesList (e.g. IRangesList, ViewsList) derivative. In addition, if subject or ranges is an IntegerRanges object, query or x can be an integer vector to be converted to length-one ranges.

If query (or x) is an IntegerRangesList object, then subject (or ranges) must also be an IntegerRangesList object.

If both arguments are list-like objects with names, each list element from the 2nd argument is paired with the list element from the 1st argument with the matching name, if any. Otherwise, list elements are paired by position. The overlap is then computed between the pairs as described below.

If subject is omitted, query is queried against itself. In this case, and only this case, the drop.self and drop.redundant arguments are allowed. By default, the result will contain hits for each range against itself, and if there is a hit from A to B, there is also a hit for B to A. If drop.self is TRUE, all self matches are dropped. If drop.redundant is TRUE, only one of A->B and B->A is returned.

invert

If TRUE, keep only the ranges in x that do not overlap ranges.

Value

constructor returns a RaggedExperiment object

'rowRanges' returns a GRanges object summarizing ranges corresponding to assay() rows.

'mcols' returns a DataFrame object of the metadata columns

'assays' returns a SimpleList

'overlapsAny' returns a logical vector of length equal to the number of rows in the query; TRUE when the copy number region overlaps the subject.

'subsetByOverlaps' returns a RaggedExperiment containing only copy number regions overlapping subject.

Methods (by generic)

Constructors

RaggedExperiment(..., colData=DataFrame()): Creates a RaggedExperiment object using multiple GRanges objects or a list of GRanges objects. Additional column data may be provided as a DataFrame object.

Accessors

In the following, 'x' represents a RaggedExperiment object:

rowRanges(x):

Get the ranged data. Value is a GenomicRanges object.

assays(x):

Get the assays. Value is a SimpleList.

assay(x, i):

An alternative to assays(x)[[i]] to get the ith (default first) assay element.

mcols(x), mcols(x) <- value:

Get or set the metadata columns. For RaggedExperiment, the columns correspond to the assay ith elements.

rowData(x), rowData(x) <- value:

Get or set the row data. Value is a DataFrame object. Also corresponds to the mcols data.

Note for advanced users and developers. Both mcols and rowData setters may reduce the size of the internal RaggedExperiment data representation. Particularly after subsetting, the internal row index is modified and such setter operations will use the index to subset the data and reduce the "rows" of the internal data representation.

Subsetting

x[i, j]: Get ranges or elements (i and j, respectively) with optional metadata columns where i or j can be missing, an NA-free logical, numeric, or character vector.

Coercion

In the following, 'object' represents a RaggedExperiment object:

as(object, "GRangesList"):

Creates a GRangesList object from a RaggedExperiment.

as(from, "RaggedExperiment"):

Creates a RaggedExperiment object from a GRangesList, or GRanges object.

Examples

## Create an empty RaggedExperiment instance
re0 <- RaggedExperiment()
re0

## Create a couple of GRanges objects with row ranges names
sample1 <- GRanges(
    c(a = "chr1:1-10:-", b = "chr1:11-18:+"),
    score = 1:2)
sample2 <- GRanges(
    c(c = "chr2:1-10:-", d = "chr2:11-18:+"),
    score = 3:4)

## Include column data
colDat <- DataFrame(id = 1:2)

## Create a RaggedExperiment object from a couple of GRanges
re1 <- RaggedExperiment(sample1=sample1, sample2=sample2, colData = colDat)
re1

## With list of GRanges
lgr <- list(sample1 = sample1, sample2 = sample2)

## Create a RaggedExperiment from a list of GRanges
re2 <- RaggedExperiment(lgr, colData = colDat)

grl <- GRangesList(sample1 = sample1, sample2 = sample2)

## Create a RaggedExperiment from a GRangesList
re3 <- RaggedExperiment(grl, colData = colDat)

## Subset a RaggedExperiment
assay(re3[c(1, 3),])
subsetByOverlaps(re3, GRanges("chr1:1-5"))  # by ranges

[Package RaggedExperiment version 1.4.0 Index]