In charlotte-ngs/rgrm:

if (!require(rgrm))
  devtools::load_all()

Disclaimer

This document introduces the package rgrm.

Background

This package came out of a task that involved the search for row and column indices in a genetic relationship matrix (grm). The solution of this task was generalized into the topic of flattening lower (or upper) parts of symmetric matrices into vectors. From that flattened vector representation of the matrix, we want to search for special elements and we want to trace them back to their original location in the matrix.

Functionality

This package offers only a small number of functions. The main function that is offered is the function findMatrixElements() . This function accepts two arguments as inputs. First a vector of indices into the flattenend vector and second the flattened vector itself. Optionally a vector of IDs can be specified in case row and column indices are associated with special IDs. This is an optional argument which should only make identification of results easier and more convenient.

An Example

As a simple example, we are given the following matrix

set.seed(2143)
nNrInd <- 6
mGrmP <- matrix(runif(n = nNrInd * nNrInd), ncol = nNrInd)
mGrm <- crossprod(mGrmP)/nNrInd
diag(mGrm) <- 1+diag(mGrm)
print(mGrm)

in its flattened vector representation which stores only the lower triangular part of the matrix including the diagonal elements.

vFlatMatElem <- rgrm::flattenMatrixLowerTri(pMatrix = mGrm)
print(vFlatMatElem)

vInterestingElements <- c(8,13)

Let us assume, that we are interested in elements with indices r vInterestingElements[1] and r vInterestingElements[2] of the flattened vector corresponding to values r vFlatMatElem[vInterestingElements[1]] and r vFlatMatElem[vInterestingElements[2]], and we want to find where in the original matrix they occured, then the respective row and column indices can be computed as

<<InterestingElements>>
lSearchResult <- rgrm::findMatrixElements(vInterestingElements, vFlatMatElem) 
print(lSearchResult)

The result of this search is a list of lists. The length of the outer list corresponds to the number of elements that were specified as the first argument to function findMatrixElements(). Each component of the list of search results is a list with three components specifying the rowindex, the column index and the matrix value.

Convenience functions

So far we have assumed that the flattened representation of the GRM is given as a vector. In practice this vector is produced by software programs like GCTA and has to be read from binary files. The GCTA website (http://cnsgenomics.com/software/gcta/estimate_grm.html) gives an R-function called ReadGRMBin() that reads a GRM from a binary file and returns a list with diagonal elements, offdiagonals, a vector of ids and the total number of individuals.

This function is also available in this package rgrm under the same name. Furthermore, we have added a simpler function that just returs the flattened representation vector. This function is called readGRMBinToVector().

sInputPath <- system.file(package = "rgrm", file.path("extdata", "OmicKriging"))
sInputPrefix <- "ig_genotypes.grm"
lFlatMatElem <- rgrm::readGRMBinToVector(psInputPrefix = sInputPrefix, psInputPath = sInputPath)
vFlatMatElem <- lFlatMatElem$flatVec
length(vFlatMatElem)
head(vFlatMatElem)
nrow(lFlatMatElem$id)
head(lFlatMatElem$id)

A small search including Ids may look as follows

rgrm::findMatrixElements(1:3, vFlatMatElem, as.vector(lFlatMatElem$id[,2]))

Helper functions

Besides the main function findMatrixElements(), package rgrm contains a number of helper functions.

flattenMatrixLowerTri()

Takes a symmetric matrix and converts it into a flattened representation of the lower triangular part of the matrix.

findSingleMatElement()

Finds a single element of a flattened representation vector in the original matrix

nGetMatDim()

Computes the dimension of the symmetric matrix given the length of the flattened representation vector.

runCompleteTest()

Searches for all elements in a flattened representation vector

Session Info

sessionInfo()

charlotte-ngs/rgrm documentation built on May 13, 2019, 3:34 p.m.