DGraph-class: DGraph objects

In hpages/ugraph: Efficient graph representation and manipulation in Bioconductor

Description

The DGraph class is a container for representing and manipulating a directed graph. A DGraph object is a vector of edges, that is, the length of the object is its number of edges and the vector elements are the edges. Subsetting a DGraph object means selecting a particular subset of edges. This does not alter its set of nodes.

Usage

## Constructor function
DGraph(nodes, from=integer(0), to=integer(0), ...)

Arguments

nodes	A vector-like object containing the nodes. This can be any Vector derivative. This can also be an ordinary vector (e.g. a character vector), in which case it will get automatically wrapped in an AnnotatedIDs object (with AnnotatedIDs(nodes)). Passing a single number to nodes is treated as a special case: in that case the nodes get automatically generated with AnnotatedIDs(seq_len(nodes)).
from, to	Two parallel integer vectors describing the edges. By parallel we mean that the two vectors must have the same length. The values in each vector must be valid node indices. For each i between 1 and N (where N is the common length of the from and to vectors), the pair formed by from[i] and to[i] represents the i-th edge, which is an edge that goes from node nodes[from[i]] to node nodes[to[i]]. Note that there can be an arbitrary number of edges going in both directions between two given nodes.
...	Optional edge attributes. These must be vector-like objects parallel to the from and to vectors. They will be stored as the metadata columns of the DGraph object.

Details

TODO

Value

A DGraph object.

Accessors

Getters

Because DGraph objects are Vector derivatives, they support the length(), mcols(), and metadata() getters. Note that the length of the object is its number of edges and the mcols() getter returns the edge attributes in a DataFrame object with 1 row per edge and 1 column per attribute.

In addition DGraph objects support the following graph-specific getters:

• nodes(x): Get the nodes of x.

• nnode(x) and numNodes(x): Both return the number of nodes in x (i.e. length(nodes(x))). The numNodes getter is provided for compatibility with the graph package.

• from(x) and to(x): Get the from index and to index for each edge. More precisely, both getters return an integer vector that is parallel to x i.e. with one element per edge in x. The values in the 2 vectors are node indices. from(x)[i] and to(x)[i] are the indices of the from and to nodes of the i-th edge, respectively. Said otherwise: the i-th edge goes from node nodes(x)[from(x)[i]] to nodes(x)[to(x)[i]].

• edgeMatrix(x): Returns a 2-row matrix with 1 column per edge. The 1st row of the matrix contains the from indices and its 2nd row contains the to indices.

• fromNode(x) and toNode(x): Get the from node and to node for each edge. More precisely, both getters return a vector of nodes that is parallel to x. fromNode(x)[i] and toNode(x)[i] are the from and to nodes of the i-th edge, respectively. More formally, fromNode(x) and toNode(x) are just doing nodes(x)[from(x)] and nodes(x)[to(x)].

• isDirected(x): Indicates whether the object is directed or not.

• edgemode(x): Returns "directed" or "undirected".

Setters

Because DGraph objects are Vector derivatives, they support the mcols() and metadata() setters.

In addition they support the following setters:

• nodes(x) <- value: Replace the current nodes.

• edgemode(x) <- value: Set the edgemode.

Subsetting

A DGraph object can be subsetted with [, like any vector-like object. Note that this only subsets the set of edges i.e. all the nodes are preserved.

Coercion

TODO

Adjacency matrix

TODO

Connected components

TODO

Concatenation

TODO (not supported yet)

Comparing & Ordering

Comparing two DGraph objects (e.g. with ==, !=, <=, <, match()) is only supported between objects with the same set of nodes in the same order.

An edge in one object is considered to be equal (==) to an edge in the other object if the 2 edges go from the same two nodes. More formally, the i-th edge in DGraph object x is considered to be equal to the j-th edge in DGraph object y if from(x)[i] == from(y)[j] and to(x)[i] == to(y)[j].

To decide whether the i-th edge is lower (<) or greater (>) than the j-th edge, first from(x)[i] and from(y)[j] are compared and, if they are equal, then to(x)[i] and to(y)[j] are also compared to break the tie.

The same rules are used for comparing the edges within a DGraph object e.g. when computing their order (with order()), or sorting them (with sort()), or ranking them (with rank()). Note that for a DGraph object x, order(x) is equivalent to order(from(x), to(x)).

Compatibility with graphNEL objects

graphNEL objects are defined in the graph package. The graph4 package provides coercion methods for coercing a DGraph object to graphNEL and vice-versa.

Author(s)

Hervé Pagès

See Also

• AnnotatedIDs objects.

• SelfHits objects in the S4Vectors package for the parent class.

• graphNEL objects in the graph package.

• agopen in the Rgraphviz package.

Examples

showClass("DGraph")  # DGraph extends SelfHits

## ---------------------------------------------------------------------
## CONSTRUCTOR & ACCESSORS
## ---------------------------------------------------------------------

## A directed graph with 10 nodes and no edges:
dg0 <- DGraph(nodes=letters[1:10])
dg0

length(dg0)     # number of edges
nodes(dg0)
nnode(dg0)
outDegree(dg0)
inDegree(dg0)

## A directed graph with 8 nodes and 9 edges:
dg1 <- DGraph(nodes=8, c(1, 1:5, 6, 6, 6), c(6, 8:4, 1:2, 7),
                       weights=0.11*(1:9))
dg1

length(dg1)     # number of edges
mcols(dg1)      # metadata columns on the edges (1 row per edge)

nodes(dg1)      # the nodes
nnode(dg1)      # number of nodes (same as 'numNodes(dg1)')
from(dg1)
to(dg1)
outDegree(dg1)  # nb of edges starting from each node
inDegree(dg1)   # nb of edges ending on each node
degree(dg1)     # outDegree(dg1) + inDegree(dg1)

edgeMatrix(dg1)
fromNode(dg1)
toNode(dg1)

## Set some names and metadata columns on the nodes:
names(nodes(dg1)) <- LETTERS[1:8]
mcols(nodes(dg1))$score <- runif(8)
nodes(dg1)
degree(dg1)

## ---------------------------------------------------------------------
## COERCION
## ---------------------------------------------------------------------

## Coercing to data.frame or DataFrame looses the node information:
as.data.frame(dg1)
as(dg1, "DataFrame")

## ---------------------------------------------------------------------
## ADJACENCY MATRIX
## ---------------------------------------------------------------------

adjm <- adjacencyMatrix(dg1)
adjm

as(adjm, "DGraph")

## Note that if 'x' is a square ngCMatrix object,
## 'adjacencyMatrix(as(x, "DGraph"))' is guaranted to be
## identical to 'x' (modulo the dimnames).
stopifnot(identical(adjacencyMatrix(as(adjm, "DGraph")), adjm))

## ---------------------------------------------------------------------
## CONNECTED COMPONENTS
## ---------------------------------------------------------------------

connComp(dg1)

## ---------------------------------------------------------------------
## CONCATENATION
## ---------------------------------------------------------------------

## TODO

## ---------------------------------------------------------------------
## COMPARING & ORDERING
## ---------------------------------------------------------------------

## TODO

## ---------------------------------------------------------------------
## COMPATIBILITY WITH graphNEL OBJECTS
## ---------------------------------------------------------------------

## Coerce to a graphNEL instance from the graph package:
gnel1 <- as(dg1, "graphNEL")
gnel1

## The graphNEL instance can be used to plot the graph with the
## Rgraphviz package:
library(Rgraphviz)
plot(agopen(gnel1, "dg1"))
plot(agopen(gnel1, "dg1", recipEdges="distinct"))

## TODO: More coercions to come soon (to DGraph<->graphAM,
## DGraph<->graphBAM, DGraph<->igraph, etc...)

hpages/ugraph documentation built on March 17, 2021, 12:54 p.m.