RangedData-class {IRanges} | R Documentation |
RangedData
supports storing data, i.e. a set of
variables, on a set of ranges spanning multiple spaces
(e.g. chromosomes). Although the data is split across spaces, it can
still be treated as one cohesive dataset when
desired. In order to handle large datasets, the data values are
stored externally to avoid copying, and the rdapply
function facilitates the processing of each space separately (divide and
conquer).
A RangedData
object consists of two primary components:
a RangesList
holding the ranges over multiple
spaces and a parallel SplitXDataFrame
,
holding the split data. There is also an annotation
slot
for denoting the source (e.g. the genome) of the ranges and/or
data.
There are two different modes of interacting with a
RangedData
. The first mode treats the object as a contiguous
"data frame" annotated with range information. The accessors
start
, end
, and width
get the corresponding
fields in the ranges as atomic integer vectors, undoing the division
over the spaces. The [[
and matrix-style [,
extraction
and subsetting functions unroll the data in the same way. [[<-
does the inverse. The number
of rows is defined as the total number of ranges and the number of
columns is the number of variables in the data. It is often convenient
and natural to treat the data this way, at least when the data is
small and there is no need to distinguish the ranges by their space.
The other mode is to treat the RangedData
as a list, with an
element (a virtual Ranges
/XDataFrame
pair) for each
space. The length of the object is defined as the number of spaces and
the value returned by the names
accessor gives the names of
the spaces. The list-style [
subset function behaves
analogously. The rdapply
function provides a convenient and
formal means of applying an operation over the spaces separately. This
mode is helpful when ranges from different spaces must be treated
separately or when the data is too large to process over all spaces at
once.
In the code snippets below, x
is a RangedData
object.
The following accessors treat the data as a contiguous dataset, ignoring the division into spaces:
nrow(x)
: The number of ranges in x
.
ncol(x)
: The number of data variables in x
.
dim(x)
: An integer vector of length two, essentially
c(nrow(x), ncol(x))
.
rownames(x)
: Gets the names of the ranges in x
.
colnames(x)
: Gets the names of the variables in x
.
dimnames(x)
: A list with two elements, essentially
list(rownames(x), colnames(x))
.
Ranges
. For IRanges
, an integer
vector. Regardless, the number of elements is always equal to
nrow(x)
.
start(x)
: The start value of each range.
width(x)
: The width of each range.
end(x)
: The end value of each range.
These accessors make the object seem like a list along the spaces:
length(x)
:
The number of spaces (e.g. chromosomes) in x
.
names(x)
: The names of the spaces (e.g. "chr1"
).
NULL
or a character vector of the same length as x
.
names(x) <- value
: Set the names of the spaces, where
value
is either NULL
or a character vector of the same
length as x
.
Other accessors:
annotation(object)
: Here, object
is a
RangedData
object. Get the scalar string
identifying the source of the data in some way (e.g. genome,
experimental platform, etc).
ranges(x)
: Gets the ranges in x
as a
RangesList
.
values(x)
: Gets the data values in x
as a
SplitXDataFrame
.
RangedData(ranges = IRanges(), ..., splitter = NULL,
annotation = NULL)
:
Creates a RangedData
with the ranges in ranges
and
variables given by the arguments in ...
. See the
constructor XDataFrame
for how the ...
arguments are interpreted. If splitter
is NULL
, all
of the ranges and values are placed into the same space, resulting
in a single-space (length one) RangedData
. Otherwise, the
ranges and values are split into spaces according to
splitter
, which is treated as a factor, like the f
argument in split
. The annotation may be specified
as a scalar string by the annotation
argument.
as.data.frame(x, row.names=NULL, optional=FALSE, ...)
:
Copy the start, end, width of the ranges and all of the variables
as columns in a data.frame
. This is a bridge to existing
functionality in R, but of course care must be taken if the data
is large. Note that optional
and ...
are ignored.
as(from, "XDataFrame")
: Like as.data.frame
above,
except the result is an XDataFrame
and it
probably involves less copying, especially if there is only a
single space.
as(from, "RangedData")
: coerces from
to a
RangedData
, according to its class:
score
.
In the code snippets below, x
is a RangedData
object.
x[i]
:
Subsets x
by indexing into its spaces, so the
result is of the same class, with a different set of spaces.
i
can be numerical, logical, NULL
or missing.
x[i,j]
:
Subsets x
by indexing into its rows and columns. The result
is of the same class, with a different set of rows and columns.
Note that this differs from the subset form
above, because we are now treating x
as one contiguous dataset.
x[[i]]
:
Extracts a variable from x
, where i
can be
a character, numeric, or logical scalar that indexes into the
columns. The variable is unlisted over the spaces.
x[[i]] <- value
:
Sets value as column i
in x
, where i
can be
a character, numeric, or logical scalar that indexes into the
columns. The length of value
should equal
nrow(x)
. x[[i]]
should be identical to value
after this operation.
In the code snippets below, x
is a RangedData
object.
split(x, f, drop = FALSE)
: Split x
according to
f
, which should be of length equal to nrow(x)
. Note
that drop
is ignored here. The result is a
RangedDataList
where every element has the same
length (number of spaces) but different sets of ranges within each
space.
c(x, ..., recursive = FALSE)
: Combines x
with
arguments specified in ...
, which must all be
RangedData
instances. This combination acts as if x
is
a list of spaces, meaning that the result will contain the spaces
of the first concatenated with the spaces of the second, and so
on. This function is useful when creating RangedData
instances on a space-by-space basis and then needing to
combine them.
Michael Lawrence
RangedData-utils for utlities and the rdapply
function for applying a function to each space separately.
ranges <- IRanges(c(1,2,3),c(4,5,6)) filter <- c(1L, 0L, 1L) score <- c(10L, 2L, NA) ## constructing RangedData instances ## no variables rd <- RangedData() rd <- RangedData(ranges) ranges(rd) ## one variable rd <- RangedData(ranges, score) rd[["score"]] ## multiple variables rd <- RangedData(ranges, filter, vals = score) rd[["vals"]] # same as rd[["score"]] above rd[["filter"]] rd <- RangedData(ranges, score + score) rd[["score...score"]] # names made valid ## use an annotation rd <- RangedData(ranges, annotation = "hg18") annotation(rd) ## split some data over chromosomes range2 <- IRanges(start=c(15,45,20,1), end=c(15,100,80,5)) both <- c(ranges, range2) score <- c(score, c(0L, 3L, NA, 22L)) filter <- c(filter, c(0L, 1L, NA, 0L)) chrom <- paste("chr", rep(c(1,2), c(length(ranges), length(range2))), sep="") rd <- RangedData(both, score, filter, splitter = chrom, annotation = "hg18") rd[["score"]] # identical to score rd[1][["score"]] # identical to score[1:3] ## subsetting ## list style: [i] rd[numeric()] # these three are all empty rd[logical()] rd[NULL] rd[] # missing, full instance returned rd[FALSE] # logical, supports recycling rd[c(FALSE, FALSE)] # same as above rd[TRUE] # like rd[] rd[c(TRUE, FALSE)] rd[1] # numeric index rd[c(1,2)] rd[-2] ## matrix style: [i,j] rd[,NULL] # no columns rd[NULL,] # no rows rd[,1] rd[,1:2] rd[,"filter"] rd[1,] # now by the rows rd[c(1,3),] rd[1:2, 1] # row and column rd[c(1:2,1,3),1] ## repeating rows ## variable replacement count <- c(1L, 0L, 2L) rd <- RangedData(ranges, count, splitter = c(1, 2, 1)) ## adding a variable score <- c(10L, 2L, NA) rd[["score"]] <- score rd[["score"]] # same as 'score' ## replacing a variable count2 <- c(1L, 1L, 0L) rd[["count"]] <- count2 ## numeric index also supported rd[[2]] <- score rd[[2]] # gets 'score' ## removing a variable rd[[2]] <- NULL ncol(rd) # is only 1 ## combining/splitting rd <- RangedData(ranges, score, splitter = c(1, 2, 1)) c(rd[1], rd[2]) # equal to 'rd' rd2 <- RangedData(ranges, score) unlist(split(rd2, c(1, 2, 1))) # same as 'rd'