RangedData-class {IRanges} | R Documentation

## Data on ranges

### Description

IMPORTANT NOTE: `RangedData` objects will be deprecated in BioC 3.7! The use of `RangedData` objects has been discouraged in favor of GRanges or GRangesList objects since BioC 2.12, that is, since 2014. The GRanges and GRangesList classes are defined in the GenomicRanges package. See `?GRanges` and `?GenomicRanges` (after loading the GenomicRanges package) for more information about these classes. PLEASE MIGRATE YOUR CODE TO USE GRanges OR GRangesList OBJECTS INSTEAD OF `RangedData` OBJECTS AS SOON AS POSSIBLE. Don't hesitate to ask on the bioc-devel mailing list (https://bioconductor.org/help/support/#bioc-devel) if you need help with this.

`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 and extends `DataTable`.

### Details

A `RangedData` object consists of two primary components: a `IntegerRangesList` holding the ranges over multiple spaces and a parallel `SplitDataFrameList`, holding the split data. There is also an `universe` 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 `IntegerRanges`/`DataFrame` 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.

### Accessor methods

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:

  Array accessors:

    `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)`, `rownames(x) <- value`: Gets or sets the names of the ranges in `x`.

    `colnames(x)`, `colnames(x) <- value`: Gets the names of the variables in `x`.

    `dimnames(x)`: A list with two elements, essentially `list(rownames(x), colnames(x))`.

    `dimnames(x) <- value`: Sets the row and column names, where value is a list as described above.

    `columnMetadata(x)`: Get the `DataFrame` of metadata along the value columns, i.e., where each column in `x` is represented by a row in the metadata. Note that calling `mcols(x)` returns the metadata on each space in `x`.

    `columnMetadata(x) <- value`: Set the `DataFrame` of metadata for the columns.

    `within(data, expr, ...)`: Evaluates `expr` within `data`, a `RangedData`. Any values assigned in `expr` will be stored as value columns in `data`, unless they match one of the reserved names: `ranges`, `start`, `end`, `width` and `space`. Behavior is undefined if any of the range symbols are modified inconsistently. Modifications to `space` are ignored.

  Range accessors. The type of the return value depends on the type of `IntegerRanges`. For `IRanges`, an integer vector. Regardless, the number of elements is always equal to `nrow(x)`.

    `start(x), start(x) <- value`: Get or set the starts of the ranges. When setting the starts, `value` can be an integer vector of `length(sum(elementNROWS(ranges(x))))` or an IntegerList object of length `length(ranges(x))` and names `names(ranges(x))`.

    `end(x), end(x) <- value`: Get or set the ends of the ranges. When setting the ends, `value` can be an integer vector of `length(sum(elementNROWS(ranges(x))))` or an IntegerList object of length `length(ranges(x))` and names `names(ranges(x))`.

    `width(x), width(x) <- value`: Get or set the widths of the ranges. When setting the widths, `value` can be an integer vector of `length(sum(elementNROWS(ranges(x))))` or an IntegerList object of length `length(ranges(x))` and names `names(ranges(x))`.

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)`, `names(x) <- value`: Get or set the names of the spaces (e.g. `"chr1"`). `NULL` or a character vector of the same length as `x`.

Other accessors:

  `universe(x)`, `universe(x) <- value`: Get or set the scalar string identifying the scope of the data in some way (e.g. genome, experimental platform, etc). The universe may be `NULL`.

  `ranges(x), ranges(x) <- value`: Gets or sets the ranges in `x` as a `IntegerRangesList`.

  `space(x)`: Gets the spaces from `ranges(x)`.

  `values(x), values(x) <- value`: Gets or sets the data values in `x` as a `SplitDataFrameList`.

  `score(x), score(x) <- value`: Gets or sets the column representing a "score" in `x`, as a vector. This is the column named `score`, or, if this does not exist, the first column, if it is numeric. The get method return `NULL` if no suitable score column is found. The set method takes a numeric vector as its value.

### Constructor

  `RangedData(ranges = IRanges(), ..., space = NULL, universe = NULL)`: Creates a `RangedData` with the ranges in `ranges` and variables given by the arguments in `...`. See the constructor `DataFrame` for how the `...` arguments are interpreted.

  If `ranges` is a `IntegerRanges` object, the `space` argument is used to split of the data into spaces. If `space` is `NULL`, all of the ranges and values are placed into the same space, resulting in a single-space (length one) `RangedData` object. Otherwise, the ranges and values are split into spaces according to `space`, which is treated as a factor, like the `f` argument in `split`.

  If `ranges` is a `IntegerRangesList` object, then the supplied `space` argument is ignored and its value is derived from `ranges`.

  If `ranges` is not a `IntegerRanges` or `IntegerRangesList` object, this function calls `as(ranges, "RangedData")` and returns the result if successful.

  The universe may be specified as a scalar string by the `universe` argument.

### Coercion

  `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, "DataFrame")`: Like `as.data.frame` above, except the result is an `DataFrame` and it probably involves less copying, especially if there is only a single space.

  `as(from, "RangedData")`: Coerce `from` to a `RangedData`, according to the type of `from`:

  `Rle`, `RleList`

    Converts each run to a range and stores the run values in a column named "score".

  `RleViewsList`

    Creates a `RangedData` using the ranges given by the runs of `subject(from)` in each of the windows, with a value column `score` taken as the corresponding subject values.

  `IntegerRanges`

    Creates a `RangedData` with only the ranges in `from`; no data columns.

  `IntegerRangesList`

    Creates a `RangedData` with the ranges in `from`. Also propagates the inner metadata columns of the `IntegerRangesList` (accessed with `mcols(unlist(from))`) to the data columns (aka values) of the `RangedData`. This makes it a lossless coercion and the exact reverse of the coercion from `RangedData` to `IntegerRangesList`.

  `data.frame` or `DataTable`

    Constructs a `RangedData`, using the columns “start”, “end”, and, optionally, “space” columns in `from`. The other columns become data columns in the result. Any “width” column is ignored.

  `as(from, "IntegerRangesList")`: Creates a `CompressedIRangesList` (a subclass of `IntegerRangesList`) made of the ranges in `from`. Also propagates the data columns (aka values) of the `RangedData` to the inner metadata columns of the `IntegerRangesList`. This makes it a lossless coercion and the exact reverse of the coercion from `IntegerRangesList` to `RangedData`.

  `as.env(x, enclos = parent.frame())`: Creates an `environment` with a symbol for each variable in the frame, as well as a `ranges` symbol for the ranges. This is efficient, as no copying is performed.

### Subsetting and Replacement

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. The row index `i` can either treat `x` as a flat table by being a character, integer, or logical vector or treat `x` as a partitioned table by being a `IntegerRangesList`, `LogicalList`, or `IntegerList` of the same length as `x`.

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

  For convenience, values of `"space"` and `"ranges"` are equivalent to `space(x)` and `unlist(ranges(x))` respectively.

  `x$name`: similar to above, where `name` is taken literally as a column name in the data.

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

  For convenience, `i="ranges"` is equivalent to `ranges(x) <- value`.

  `x$name <- value`: similar to above, where `name` is taken literally as a column name in the data.

### Splitting and Combining

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

  `rbind(...)`: Matches the spaces from the `RangedData` objects in `...` by name and combines them row-wise.

  `c(x, ..., recursive = FALSE)`: Combines `x` with arguments specified in `...`, which must all be `RangedData` objects. 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` objects on a space-by-space basis and then needing to combine them.

### Applying

An `lapply` method is provided to apply a function over the spaces of a `RangedData`:

  `lapply(X, FUN, ...)`: Applies `FUN` to each space in `X` with extra parameters in `...`.

### Author(s)

Michael Lawrence

### See Also

DataTable, the parent of this class, with more utilities.

### Examples

      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$vals
      rd[["filter"]]
      rd <- RangedData(ranges, score + score)
      rd[["score...score"]] # names made valid

      ## 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, space = chrom)
      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

      ## dimnames

      colnames(rd)[2] <- "foo"
      colnames(rd)
      rownames(rd) <- head(letters, nrow(rd))
      rownames(rd)

      ## space names

      names(rd)
      names(rd)[1] <- "chr1"

      ## variable replacement

      count <- c(1L, 0L, 2L)
      rd <- RangedData(ranges, count, space = 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
      rd$score2 <- score

      ## combining

      rd <- RangedData(ranges, score, space = c(1, 2, 1))
      c(rd[1], rd[2]) # equal to 'rd'
      rd2 <- RangedData(ranges, score)

      ## applying

      lapply(rd, `[[`, 1) # get first column in each space

[Package IRanges version 2.14.12 Index]