matSPACE

R-CMD-check

This is a README file of the R package matSPACE. Our package fits sparse partial correlation networks for matrix-variate data, i.e. observations that are themselves p x q matrices rather than a single vector of q measurements. We extend the SPACE (Sparse PArtial Correlation Estimation) joint estimation framework to a Kronecker-product precision structure, Omega = V %x% U, where V (q x q) is the column-wise precision matrix and U (p x p) is the row-wise precision matrix. All partial correlations are estimated jointly via an L1-penalized (lasso) shooting algorithm, which preserves symmetry of the estimated network and avoids the tuning-parameter selection difficulties of separate node-wise regressions.

Installation of the package

To install our package, you may simply execute the following codes:

install.packages("matSPACE")

# development version
# install.packages("pak")
pak::pak("kimhyew1/matSPACE")

A basic example of using the package

We give a toy example to apply the main function matSPACE, which estimates the Kronecker-structured row/column precision matrices U and V.

Generate data

We first generate simulated matrix-variate data. Columns 1-2 and columns 3-4 are correlated by construction, so there is real sparse structure for matSPACE to recover (pure noise data has no structure to penalize away, so the BIC-optimal fit is always the fully sparse one).

set.seed(1)
p = 5
q = 4
n = 20

library(matSPACE)
data = replicate(n, {mat = matrix(rnorm(p * q), p, q)
                     mat[, 2] = mat[, 2] + 0.8 * mat[, 1]
                     mat[, 4] = mat[, 4] + 0.8 * mat[, 3]
                     mat}, simplify = FALSE)

Model fitting

Applying matSPACE to the simulated data, a lasso penalty path is searched for V and U separately, and the BIC-minimizing fit is returned for each. By default the columns are weighted by their estimated residual precisions (f_type_V = f_type_U = "variance"), and at every penalty the reweighting is iterated until convergence (iter = 500, outer_tol = 1e-8) over a path of K = 80 penalties.

fit = matSPACE(data)
fit$V   # q x q column-wise precision matrix
#>            [,1]        [,2]        [,3]       [,4]
#> [1,]  1.0000000 -0.49410136  0.12114557 -0.1096305
#> [2,] -0.4941014  0.66081614 -0.06264098  0.0000000
#> [3,]  0.1211456 -0.06264098  1.03791174 -0.4934104
#> [4,] -0.1096305  0.00000000 -0.49341039  0.8061834
fit$U   # p x p row-wise precision matrix
#>            [,1]      [,2]       [,3]      [,4]       [,5]
#> [1,]  1.3444220 0.2122121 -0.3425416 0.0000000 -0.1820373
#> [2,]  0.2122121 1.6067464  0.0000000 0.2654804  0.1063301
#> [3,] -0.3425416 0.0000000  1.8489166 0.0000000 -0.1215758
#> [4,]  0.0000000 0.2654804  0.0000000 1.5704397  0.1701304
#> [5,] -0.1820373 0.1063301 -0.1215758 0.1701304  1.6366881

Visualization of the lambda path

The full lambda path behind this selection is attached as a "path" attribute, which lets us plot BIC against lambda without refitting.

path = attr(fit, "path")
plot(log(path$V$lambda), path$V$bic, type = "b",
     xlab = "log(lambda)", ylab = "BIC", main = "Column (V) lambda path")
i_min = which.min(path$V$bic)
points(log(path$V$lambda[i_min]), path$V$bic[i_min], col = "red", pch = 19)

Fitting with a single lasso penalty

If you already know the penalty you want, space fits a single lasso penalty directly, without searching a path.

fit_single = space(data, lam = 0.5)
fit_single$ParCor
#>            [,1]        [,2]       [,3]        [,4]
#> [1,]  1.0000000  0.62837905 -0.1669241  0.16732558
#> [2,]  0.6283791  1.00000000  0.1215284 -0.04533202
#> [3,] -0.1669241  0.12152840  1.0000000  0.56279861
#> [4,]  0.1673256 -0.04533202  0.5627986  1.00000000

Issues

We are happy to troubleshoot any issue with the package;