ug: Simulation of correlation matrices.
In gmat: Simulation of Graphical Correlation Matrices

Description Usage Arguments Details Value References Examples

Sample correlation matrices, possibly with a zero pattern constrained by an undirected graph.

port(N = 1, p = 3, d = 1, ug = NULL, rfun = stats::rnorm, ...)

port_chol(N = 1, p = 3, d = 1, ug = NULL, ...)

diagdom(N = 1, p = 3, d = 1, ug = NULL, rfun = stats::rnorm, ...)

`N`	Number of samples.
`p`	Matrix dimension. Ignored if `ug` is provided.
`d`	Number in `[0,1]`, the proportion of non-zero entries in the sampled matrices. Ignored if `ug` is provided.
`ug`	An igraph undirected graph specifying the zero pattern in the sampled matrices.
`rfun`	Function that generates the random entries in the initial factors, except for `port_chol()` which uses `mh_u()` to obtain it.
`...`	Additional parameters to be passed to `rfun` or to `mh_u()`.

Function port() uses the method described in Córdoba et al. (2018). In summary, it consists on generating a random matrix Q and performing row-wise orthogonalization such that if i and j are not adjacent in ug, then the rows corresponding to such indices are orthogonalized, without violating previous orthogonalizations and without introducing unwanted independences. The resulting matrix after the process has finished is the cross product of Q.

Function port_chol() uses the method described in Córdoba et al. (2019), combining uniform sampling with partial orthogonalization as follows. If the graph provided is not chordal, then a chordal cover is found using gRbase::triangulate(). Then uniform sampling for the upper Choleksy factor corresponding to such chordal cover is performed with mh_u(). Finally, it uses partial orthogonalization as port() to add the missing zeros (corresponding to fill-in edges in the chordal cover). The behaviour of this function is the same as port().

We also provide an implementation of the most commonly used in the literature diagdom(). By contrast, this method produces a random matrix M with zeros corresponding to missing edges in ug, and then enforces a dominant diagonal to ensure positive definiteness. Matrices produced by diagdom usually are better conditioned than those by port; however, they typically suffer from small off-diagonal entries, which can compromise model validation in Gaussian graphical models. This is avoided by port.

A three-dimensional array of length p x p x N.

Córdoba, I., Varando, G., Bielza, C. and Larrañaga, P. A partial orthogonalization method for simulation covariance and concentration graph matrices. Proceedings of Machine Learning Research (PGM 2018), vol. 72, pp. 61 - 72, 2018.

Córdoba, I., Varando, G., Bielza, C. and Larrañaga, P. On generating random Gaussian graphical models. International Journal of Approximate Reasoning , vol. 125, pp.240 - 250, 2020.

## Partial orthogonalization
# Generate a full matrix (default behaviour)
port()

# Generate a matrix with a percentage of zeros
port(d = 0.5)

# Generate a random undirected graph structure
ug <- rgraph(p = 3, d = 0.5)
igraph::print.igraph(ug)

# Generate a matrix complying with the predefined zero pattern
port(ug = ug)
## Diagonal dominance
# Generate a full matrix (default behaviour)
diagdom()

# Generate a matrix with a percentage of zeros
diagdom(d = 0.5)

# Generate a matrix complying with the predefined zero pattern
igraph::print.igraph(ug)
diagdom(ug = ug)