IndexedRelations: The IndexedRelations class

In LTLA/IndexedRelations: Representing Indexed Relationships Between Features

Description

The IndexedRelations class is designed to represent relationships between feature sets (e.g., genes, genomic regions, proteins). Each entry in a IndexedRelations object corresponds to a relationship between any number of “partners” from different feature sets. All entries in a single IndexedRelations object should have the same number, ordering and type of partners involved in the relationship.

This class aims to provide an efficiency boost in the case where one feature is a partner in multiple relationships. Rather than storing the same feature multiple times, this class stores it once and simply refers to that feature in each relationship. This reduces the memory usage and enables more efficient processing by algorithms that are aware of this redundancy.

Constructor

IndexedRelations(x, featureSets=NULL) will return a IndexedRelations object given a list or data.frame of partners in x.

Partners can be represented by any Vector-like data type in each element of x. Parallel Vectors in x represent partners involved in a single relationship, i.e., the first element of x[[1]] is in a relationship with the first element of x[[2]] and so on. Thus, all partner vectors in x should be of the same length.

If featureSets is specified, this should contain a list of feature sets. Again, any Vector-like data type is supported, but in this case, x should only contain integer indices. This specifies the partners involved in each relationship by indexing the relevant feature set. Each partner vector in x is assumed to point to the corresponding feature set in featureSets, i.e., indices in x[[1]] refer to the elements in featuresSets[[1]] and so on.

If x is a IndexedRelations object, it is returned without further modification.

Getter methods for partners

In the following code snippets, x is a IndexedRelations object.

partners(x):

Returns a DataFrame of partner indices. Each row represents a relationship and each column represents a partner. The ith column contains an integer index that points to the corresponding feature set in featureSets.

partnerNames(x):

Returns a character vector of names used for each parter in a relationship. This may be NULL if the partners are not named.

partnerFeatures(x, type):

Returns the partners as features, by using the indices to subset the feature set. type is an integer scalar specifying which partners to return. Alternatively, it can be a string if the partners are named.

npartners(x):

Returns an integer scalar specifying the number of partners per relationship in x.

Other getters

featureSets(x) returns a List of all feature sets, given an IndexedRelations object x. Each feature set corresponds to and is pointed at by the column of partners(x) with the same name.

Getter methods applicable to Vector subclasses can be used here, e.g., length, names, mcols, metadata.

Element-wise metadata can be conveniently retrieved for an IndexedRelations object x with the field name by using x$name.

Setter methods for partners

In the following code snippets, x is a IndexedRelations object.

partners(x) <- value:

Replaces the partner indices with a DataFrame value. value should have the same number of columns as partners(x), and should contain integer indices that point to valid entries of the corresponding feature set.

partnerNames(x) <- value:

Replaces the names used for each partner with value, a character vector or NULL.

partnerFeatures(x, type, ...) <- value:

Replaces the partners specified by type with new features in value. type can be an integer scalar or a string if the partners are named. Values in ... are ignored.

Other setter methods

featureSets(x) <- value replaces the feature sets in an IndexedRelations instance x with the List value. value should have the same length as the original featureSets(x).

Setter methods applicable to Vector subclasses are applicable to IndexedRelations instances, e.g., names<-, mcols<-, metadata<-.

Element-wise metadata can be conveniently set for an IndexedRelations object x with the field name by using x$name <- value, where value is a vector-like object recycled to the length of x.

Subsetting and combining

An IndexedRelations instance behaves like a one-dimensional Vector during subsetting. This will operate on the relations as vector elements.

It is always possible to combine IndexedRelations objects with the same feature set classes, even if the entries in the feature sets differ between objects. In such cases, an IndexedRelations object will be produced where each feature set is a union of the corresponding sets in the input. The same principle applies for subset assignment.

Miscellaneous

show(x) will show information about an IndexedRelations x, including a preview of the first and last relationships. Note that the feature classes must have methods implemented for showAsCell in order for correct display of the partner features.

Names and metadata in feature sets

Particular functions may not preserve names and metadata in the feature set. This occurs when an operation needs to consolidate two different feature sets into one, e.g., when combining two IndexedRelations that do not have identical feature sets, In such cases, a warning will be issued if information is likely to be lost such that the results are not as expected. Users wanting to modify names or metadata of the feature sets should do so via the featureSets<- method.

Author(s)

Aaron Lun

Examples

#####################
#### Constructor ####
#####################

library(GenomicRanges)
promoters <- GRanges("chrA", IRanges(1:10*20, 1:10*20+10))
enhancers <- GRanges("chrA", IRanges(1:20*10, 1:20*10+10))

# You can construct from supplying features:
partner1 <- sample(length(promoters), 100, replace=TRUE)
partner2 <- sample(length(enhancers), 100, replace=TRUE)
rel <- IndexedRelations(
    list(
        promoter=promoters[partner1],
        enhancer=enhancers[partner2]
    )
)

# But it's more efficient to just supply indices, where possible:
rel <- IndexedRelations(
    list(promoter=partner1, enhancer=partner2),
    featureSets=list(promoters=promoters, enhancers=enhancers)
)

IndexedRelations(rel) # does nothing.

#################
#### Getters ####
#################

partners(rel)
partnerNames(rel)
partnerFeatures(rel, "promoter")
partnerFeatures(rel, 1)
partnerNames(rel)

featureSets(rel)

#################
#### Setters ####
#################

rel2 <- rel
partners(rel2)$promoter <- rev(partners(rel2)$promoter)
partners(rel2)

partnerNames(rel2) <- c("P", "E")
partnerNames(rel2)

partnerFeatures(rel2, "P") <- rev(partnerFeatures(rel2, "P")) # by feature
partners(rel2)

featureSets(rel2)$P <- resize(featureSets(rel2)$P, width=25)
featureSets(rel2)$P

##################################
#### Subsetting and combining ####
##################################

c(rel, rel)
rel[1:5]
rel3 <- rel
rel3[1:10] <- rel[10:1]
rel3

LTLA/IndexedRelations documentation built on June 2, 2019, 10:03 p.m.