GRangesFactor-class: GRangesFactor objects

In Bioconductor/GenomicRanges: Representation and manipulation of genomic intervals

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 NAs).
index	NULL or an integer (or numeric) vector of valid positive indices (no NAs) 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)

Bioconductor/GenomicRanges documentation built on Nov. 2, 2024, 7:20 a.m.