Node matrix

Warning: Re-loading trees with node matrices into R, such as through RStudio, can cause fatal errors.

Although the TreeMan object is based around a node list, it is also possible to create a node matrix. When generated a node matrix can provided substantial speed-ups for certain computational tasks, particularly getting tasks. Generating a node matrix can lead to 2-3 times speed up for common get functions for the mammal tree. The node matrix, however, can take time to generate and takes up a lot of memory.

library(treeman)
data(mammals)
# add a node matrix
mammals2 <- addNdmtrx(mammals)
# in the R environment both objects appear to have the same size
object.size(mammals)
object.size(mammals2)
# but upon bringing the node matrix into the environment
# we can see it occupies ~20 times more memory
ndmtrx <- mammals2@ndmtrx[1:mammals@nall,
                          1:mammals@nall]
object.size(ndmtrx)

Node matrices are added to trees using either the addNdmtrx() function or specifying TRUE with the wndmtrx argument for a variety of functions.

How the node matrix works

The node matrix is a matrix of 0s and 1s of total number of nodes by total number of nodes. Rows indicate post-nodes and columns indicate pre-nodes. Calculating things like, the number of descending tips from a node is easier with the node matrix. It simply requires counting the number of 1s in the node's row that are tips. Achieving the same function with a node list would require looping.

tree <- randTree(4, wndmtrx=TRUE)
ndmtrx <- tree@ndmtrx[1:tree@nall, 1:tree@nall] 
colnames(ndmtrx) <- rownames(ndmtrx) <- tree@all

> print(ndmtrx)
   n1 n2 n3 t1 t2 t3 t4
n1  1  1  1  1  1  1  1
n2  0  0  0  0  0  1  1
n3  0  0  0  1  1  0  0
t1  0  0  0  0  0  0  0
t2  0  0  0  0  0  0  0
t3  0  0  0  0  0  0  0
t4  0  0  0  0  0  0  0

In the example above, n1 is the root because its row is full of 1s -- meaning all nodes descend from it. By convention root nodes are pre-nodes to themselves. We can see that n2 has just two descending tips: t3 and t4.

Bigmemory

Due to the potential large size of a node matrix (e.g. the mammalian node matrix is 6618x6618), treeman uses the bigmemory package to limit memory usage. Matrices generated with the bigmemory package (bigmatrices) are not held in the R environment. Instead, a bigmatrix is held as a C object and an R object acts as a pointer to it.

> tree@ndmtrx
An object of class "big.matrix"
Slot "address":
<pointer: 0x73f16b0>

For finer control over the bigmatrix, use the addNdmtrx() with the arguments as described in the bigmemory as.big.matrix() documentation. This would allow a user to make node matrices shared or use file-backing for very large trees where RAM is limited. See the bigmemory documentation.

Saving node matrices

A node matrix CANNOT be saved with writeTree() or writeTrmn(). It also CANNOT be saved using save(). In fact, loading a tree with a node matrix using the load() will cause a fatal error in R. Generally, it is advised to remove a node matrix from a tree before saving and re-generated the matrix upon re-loading the tree into R. Otherwise, there is the specific functions saveTreeMan() and loadTreeMan() which will save/load the node matrix as a special file next to the R Data file.

tree <- randTree(100, wndmtrx=TRUE)
saveTreeMan(tree, file='test.RData')
rm(tree)
tree <- loadTreeMan(file='test.RData')
file.remove('test.RData', 'testRData_ndmtrx')

A user can also directly access and save the node matrix using bigmemory functions. It is advised to read up on bigmemory before doing this.

tree@ndmtrx <- bigmemory::read.big.matrix(filename=ndmtrx_file,
                                          type='integer', shared=FALSE)

Next page: ndLabels()