Simulation of Graphically Constrained Matrices

Simulation of positive definite matrices constrained by an undirected or acyclic directed graph structure.


An R package for simulating positive definite matrices constrained by acyclic directed and undirected graphs.

Build Status codecov Lifecycle: maturing CRAN downloads CRAN status

Installation

The package is available on CRAN, to get the latest stable version use:

install.packages("gmat")

Alternatively, using the R package devtools one may install the development version:

devtools::install_github("irenecrsn/gmat")

The only R package required for gmat is igraph, which can also be installed from CRAN.

An example of use

First, we generate a random undirected graph with 3 nodes and density 0.5. Then we generate, using our port() function, 2 matrices consistent with such random graphical structure.

library(gmat)
 
ug <- rgraph(p = 3, d = 0.5)
igraph::print.igraph(ug)
#> IGRAPH 75df7f1 U--- 3 1 -- Erdos renyi (gnp) graph
#> + attr: name (g/c), type (g/c), loops (g/l), p (g/n)
#> + edge from 75df7f1:
#> [1] 1--3
port(N = 2, ug = ug)
#> , , 1
#> 
#>           [,1]      [,2]      [,3]
#> [1,] 1.2329616 0.0000000 0.6513035
#> [2,] 0.0000000 0.1578579 0.0000000
#> [3,] 0.6513035 0.0000000 0.5332192
#> 
#> , , 2
#> 
#>          [,1]      [,2]     [,3]
#> [1,] 1.787082 0.0000000 1.296915
#> [2,] 0.000000 0.0465929 0.000000
#> [3,] 1.296915 0.0000000 1.214313

We appreciate how the zero pattern is shared by all of the simulated matrices. The return value is an array, and so the individual matrices can be accessed as matrices[, , n], where n is the index of the matrix we want to retrieve from the sample, ranging from 1 to N.

We may also sample correlation matrices using i.i.d. coefficients in their upper Cholesky factor U.

chol_iid(N = 2)
#> , , 1
#> 
#>            [,1]      [,2]       [,3]
#> [1,]  1.0000000  0.201973 -0.4340289
#> [2,]  0.2019730  1.000000 -0.6814360
#> [3,] -0.4340289 -0.681436  1.0000000
#> 
#> , , 2
#> 
#>            [,1]       [,2]       [,3]
#> [1,]  1.0000000 -0.3758306 -0.1389546
#> [2,] -0.3758306  1.0000000 -0.6183038
#> [3,] -0.1389546 -0.6183038  1.0000000

A specific zero pattern can be enforced in U using an acyclic digraph.

dag <- rgraph(p = 3, d = 0.5, dag = TRUE)
m <- chol_iid(dag = dag)[, , 1]
L <- t(chol(anti_t(m)))
U <- t(anti_t(L))
igraph::print.igraph(dag)
#> IGRAPH fdee8a0 D--- 3 1 -- 
#> + edge from fdee8a0:
#> [1] 2->3
print(U)
#>      [,1]      [,2]       [,3]
#> [1,]    1 0.0000000  0.0000000
#> [2,]    0 0.9836563 -0.1800561
#> [3,]    0 0.0000000  1.0000000
print(m)
#>      [,1]       [,2]       [,3]
#> [1,]    1  0.0000000  0.0000000
#> [2,]    0  1.0000000 -0.1800561
#> [3,]    0 -0.1800561  1.0000000

See more examples and paper references at the documentation website for the package.

News

gmat 0.2.0

In this version the functionality of gmat has been significantly extended. In addition to the functionality already available for sampling covariance matrices, possibly with a zero pattern specified by an undirected graph, now the package also allows sampling correlation matrices with zero entries on their Cholesky factor, represented by an acyclic digraph.

Breaking changes

Arguments for port() and diagdom() have been refactored in order to unify the approaches for undirected graphs and the new functions for acyclic digraphs. This has had some consequences in terms of the behaviour of the two functions.

  • The arguments have been reordered taking into account their relative importance. In particular, ug is now the fourth argument, instead of the second one, for both functions.
  • Now the function does not generate an undirected graph if parameter ug is not provided, unless explicitly stating a parameter d < 1.
  • The default values for p and d have been changed. Now by default one 3 x 3 full matrix is returned.
  • The argument rentries has been removed for both functions. In the future maybe this argument is reintroduced with a more complete checking of its validity depending on the properties of the function.
  • The argument k has been removed from diagdom(), and its functionality is now implemented by the utility function set_cond_number().

New features

The main addition in this version are functions for correlation matrix sampling, possibly with constraints on the upper Cholesky factorization, which correspond to an acyclic digraph representation. Some side utility functions are also provided.

  • Added functions chol_mh(), chol_iid() and chol_polar(). These three functions return a sample of correlation matrices, possibly with an average percentage of zeros in their upper Cholesky factor, which can be also predefined by a given acyclic digraph. See more details at their documentation.
  • Functions mh_sphere() and mh_u(), used by chol_mh(), allows to sample the upper Cholesky factor of a correlation matrix by sampling vectors on hemispheres of different dimensions. More information on their documentation.
  • Added utility function rgraph(), which is a simple wrapper of some functionality in package igraph for random graph generation.
  • New function anti_t() computes the anti transpose of a matrix. This is mainly useful for testing, since it is involved in the acyclic digraph representation of the upper and lower Cholesky factors.
  • Utility function vectorize() for extracting the upper/lower triangle in a covariance/correlation matrix sample as returned by the functions in the package.

Minor improvements

  • Updated documentation and examples for port() and diagdom().
  • Now igraph package is not imported into the NAMESPACE, but instead explicitly called throughout the package using ::.
  • Removed a seemingly unnecessary package registration.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("gmat")

0.2.0 by Irene Córdoba, 7 months ago


https://github.com/irenecrsn/gmat


Report a bug at https://github.com/irenecrsn/gmat/issues


Browse source code at https://github.com/cran/gmat


Authors: Irene Córdoba [aut, cre] , Gherardo Varando [aut] , Concha Bielza [ths] , Pedro Larrañaga [ths]


Documentation:   PDF Manual  


GPL (>= 2) license


Imports igraph, stats

Suggests testthat, covr


See at CRAN