GRangesFactor-class {GenomicRanges} | R Documentation

## GRangesFactor objects

### Description

A GRangesFactor object is a Factor derivative where the levels are a GRanges object.

See `?Factor` and in the S4Vectors package for general information about Factor objects.

### Usage

    GRangesFactor(x, levels, index=NULL, ...)  # constructor function

### Arguments

`x, levels` | Like with the `Factor()` constructor function, at least one of `x` and `levels` must be specified. If `index` is `NULL`, both can be specified. When `x` and/or `levels` are specified, they must be GRanges objects or derivatives. In addition, `levels` cannot contain duplicate ranges (i.e. `anyDuplicated(levels)` must return 0). When `x` and `levels` are both specified, they should both be GRanges objects or GRanges derivatives of the same class, and all the elements in `x` must be represented in `levels` (i.e. the integer vector returned by `match(x, levels)` should contain no `NA`s).
`index` | `NULL` or an integer (or numeric) vector of valid positive indices (no `NA`s) into `levels`.
`...` | Optional metadata columns.

### Details

Like with the `Factor()` constructor function, there are 4 different ways to use the `GRangesFactor()` constructor function. See Details section in the man page for Factor objects for more information.

### Value

A GRangesFactor object.

### Accessors

GRangesFactor objects support the accessors documented in the man page for Factor objects.

In addition, the following getters are supported for convenience: `seqnames()`, `start()`, `end()`, `width()`, `strand()`, `seqinfo()`, `granges()`, and `ranges()`. When called on GRangesFactor object `x`, they all behave as if they were called on `unfactor(x)`.

### Decoding a Factor

Because a GRangesFactor object `x` is a Factor derivative, `unfactor(x)` can be used to decode it. `unfactor(x)` returns an object of the same class as `levels(x)` (i.e. a GRanges object or derivative) and same length as `x`.

See `?unfactor` for more information.

### Coercion

GRangesFactor objects support the coercions documented in the man page for Factor objects.

In addition, coercion back and forth between GRanges and GRangesFactor is supported via `as(x, "GRanges")` and `as(x, "GRangesFactor")`.

### Subsetting

A GRangesFactor object can be subsetted with `[`, like a Factor object.

### Concatenation

2 or more GRangesFactor objects can be concatenated with `c()`. The result of this concatenation is another GRangesFactor object.

See Concatenation section in `?Factor`.

### Comparing & ordering

See Comparing & Ordering section in `?Factor`.

### Author(s)

Hervé Pagès

### See Also

- GRanges objects.

- Factor objects in the S4Vectors package for the parent class of GRangesFactor.

- `anyDuplicated` in the BiocGenerics package.

### Examples

    showClass("GRangesFactor")  # GRangesFactor extends Factor

    ## ---------------------------------------------------------------------
    ## CONSTRUCTOR & ACCESSORS
    ## ---------------------------------------------------------------------
    set.seed(123)
    ir0 <- IRanges(sample(5, 8, replace=TRUE), width=10, names=letters[1:8])
    gr0 <- GRanges("chrA", ir0, ID=paste0("ID", 1:8))

    ## Use explicit levels:
    gr1 <- GRanges("chrA", IRanges(1:6, width=10))
    grf1 <- GRangesFactor(gr0, levels=gr1)
    grf1
    length(grf1)
    names(grf1)
    levels(grf1)  # gr1
    nlevels(grf1)
    as.integer(grf1)  # encoding

    ## If we don't specify the levels, they'll be set to unique(gr0):
    grf2 <- GRangesFactor(gr0)
    grf2
    length(grf2)
    names(grf2)
    levels(grf2)  # unique(gr0)
    nlevels(grf2)
    as.integer(grf2)

    ## ---------------------------------------------------------------------
    ## DECODING
    ## ---------------------------------------------------------------------
    unfactor(grf1)

    stopifnot(identical(gr0, unfactor(grf1)))
    stopifnot(identical(gr0, unfactor(grf2)))

    unfactor(grf1, use.names=FALSE)
    unfactor(grf1, ignore.mcols=TRUE)

    ## ---------------------------------------------------------------------
    ## COERCION
    ## ---------------------------------------------------------------------
    grf2b <- as(gr0, "GRangesFactor")  # same as GRangesFactor(gr0)
    stopifnot(identical(grf2, grf2b))

    as.factor(grf2)
    as.factor(grf1)

    as.character(grf1)  # same as unfactor(as.factor(grf1)),
                        # and also same as as.character(unfactor(grf1))

    ## ---------------------------------------------------------------------
    ## CONCATENATION
    ## ---------------------------------------------------------------------
    gr3 <- GRanges("chrA", IRanges(c(5, 2, 8:6), width=10))
    grf3 <- GRangesFactor(levels=gr3, index=2:4)
    grf13 <- c(grf1, grf3)
    grf13
    levels(grf13)

    stopifnot(identical(c(unfactor(grf1), unfactor(grf3)), unfactor(grf13)))

    ## ---------------------------------------------------------------------
    ## COMPARING & ORDERING
    ## ---------------------------------------------------------------------
    grf1 == grf2  # same as unfactor(grf1) == unfactor(grf2)

    order(grf1)   # same as order(unfactor(grf1))
    order(grf2)   # same as order(unfactor(grf2))

    ## The levels of the GRangesFactor influence the order of the table:
    table(grf1)
    table(grf2)

[Package GenomicRanges version 1.42.0 Index]