Package 'CVN' reference manual

Title:	Covariate-Varying Networks
Description:	Inferring high-dimensional Gaussian graphical networks that change with multiple discrete covariates. Louis Dijkstra, Arne Godt, Ronja Foraita (2024) <arXiv:2407.19978>.
Authors:	Ronja Foraita [aut, cre] , Louis Dijkstra [aut] , Lukas Burk [ctb] , DFG [fnd], Leibniz Institute for Prevention Research and Epidemiology - BIPS [cph] (02c22vc57)
Maintainer:	Ronja Foraita <[email protected]>
License:	GPL (>= 3)
Version:	1.1
Built:	2025-02-12 15:23:07 UTC
Source:	https://github.com/bips-hb/CVN

Covariate-varying Networks

Description

Inferring high-dimensional Gaussian graphical networks that change with multiple discrete covariates.

Author(s)

Maintainer: Ronja Foraita [email protected] (ORCID)

Authors:

Louis Dijkstra (ORCID)

Other contributors:

Lukas Burk (ORCID) [contributor]
DFG [funder]
Leibniz Institute for Prevention Research and Epidemiology - BIPS [email protected] (ROR) [copyright holder]

References

Dijkstra L, Godt A, Foraita R Inferring High-Dimensional Dynamic Networks Changing with Multiple Covariates (2024), Arxiv, https://arxiv.org/abs/2407.19978.

Examples


data(grid)
W <- create_weight_matrix(type = "grid", k=3, l=3, plot = FALSE)

cvn <- CVN(grid, W, lambda1 = 1, lambda2 = 1:2, 
           n_cores = 1,
           eps = 1e-2, maxiter = 1000, verbose = TRUE)
data(grid)
W <- create_weight_matrix(type = "grid", k=3, l=3, plot = FALSE)

cvn <- CVN(grid, W, lambda1 = 1, lambda2 = 1:2, 
           n_cores = 1,
           eps = 1e-2, maxiter = 1000, verbose = TRUE)

Combine CVN object with interpolated CVN object

Description

Combine an interpolated CVN to an original CVN

Usage

combine_cvn_interpolated(cvn, cvn_interpolated)
combine_cvn_interpolated(cvn, cvn_interpolated)

Arguments

`cvn`	A CVN fit with $m$ graphs
`cvn_interpolated`	A interpolated CVN from a fitted CVN model with $m$ graphs

Value

A 'cvn_interpolated' object (see interpolate).

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

interpolate <- interpolate(fit, c(0,0,0,0,0,0,0,0.5,0.5), truncate = 0.05)
fit10 <- combine_cvn_interpolated(fit, interpolate)

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

interpolate <- interpolate(fit, c(0,0,0,0,0,0,0,0.5,0.5), truncate = 0.05)
fit10 <- combine_cvn_interpolated(fit, interpolate)

Create a `data.frame` for the Edges for `visNetwork`

Description

In order to visualize a graph, we need to create a data.frame that can be used by the visNetwork package. This function returns the needed data.frame given a adjacency matrix.

Usage

create_edges_visnetwork(adj_matrix)
create_edges_visnetwork(adj_matrix)

Arguments

adj_matrix

A symmetric adjacency matrix

Value

Data frame that be used as input for visNetwork

Examples

nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges) 
nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)

Nodes for the `visNetwork` package

Description

Creates a data frame that can be used for the visNetwork package.

Usage

create_nodes_visnetwork(n_nodes, labels = 1:n_nodes)
create_nodes_visnetwork(n_nodes, labels = 1:n_nodes)

Arguments

`n_nodes`	Number of nodes in the graph
`labels`	The labels for the individual nodes (Default: `1:n_nodes`)

Value

Data frame with two columns: id and title

Examples

nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges) 
nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)

Different Weight Matrices

Description

This function generates different weight matrices for two external covariates, $W$ . There are several types:

full: All graphs are fully connected with weight 1
glasso: All graphs are disconnected with weight 0. This mimicks the GLASSO, where each graph is estimated independently
grid: A weight matrix for a $k \times l$ grid
uniform-random: Fully-connected, but the entries are drawn from a uniform distribution

Usage

create_weight_matrix(
  type = c("full", "glasso", "grid", "uniform-random"),
  k,
  l,
  plot = FALSE
)
create_weight_matrix(
  type = c("full", "glasso", "grid", "uniform-random"),
  k,
  l,
  plot = FALSE
)

Arguments

`type`	The type of weight matrix
`k`	Number of categories in the first external covariate
`l`	Number of categories in the second external covariate
`plot`	If TRUE, the weight matrix is plotted (default: FALSE)

Value

Weight matrix

Examples

W <- create_weight_matrix(type="grid", k=3, l=2)

W <- create_weight_matrix(type="grid", k=3, l=2)

Estimating a Covariate-Varying Network (CVN)

Description

Estimates a covariate-varying network model (CVN), i.e., $m$ Gaussian graphical models that change with (multiple) external covariate(s). The smoothing between the graphs is specified by the $(m \times m)$ -dimensional weight matrix $W$ . The function returns the estimated precision matrices for each graph.

Usage

CVN(
  data,
  W,
  lambda1 = 1:2,
  lambda2 = 1:2,
  gamma1 = NULL,
  gamma2 = NULL,
  rho = 1,
  eps = 1e-04,
  maxiter = 100,
  truncate = 1e-05,
  rho_genlasso = 1,
  eps_genlasso = 1e-10,
  maxiter_genlasso = 100,
  truncate_genlasso = 1e-04,
  n_cores = min(length(lambda1) * length(lambda2), detectCores() - 1),
  normalized = FALSE,
  warmstart = TRUE,
  minimal = FALSE,
  gamma_ebic = 0.5,
  verbose = TRUE
)
CVN(
  data,
  W,
  lambda1 = 1:2,
  lambda2 = 1:2,
  gamma1 = NULL,
  gamma2 = NULL,
  rho = 1,
  eps = 1e-04,
  maxiter = 100,
  truncate = 1e-05,
  rho_genlasso = 1,
  eps_genlasso = 1e-10,
  maxiter_genlasso = 100,
  truncate_genlasso = 1e-04,
  n_cores = min(length(lambda1) * length(lambda2), detectCores() - 1),
  normalized = FALSE,
  warmstart = TRUE,
  minimal = FALSE,
  gamma_ebic = 0.5,
  verbose = TRUE
)

Arguments

`data`	A list with matrices, each entry associated with a single graph. The number of columns should be the same for each matrix. Number of observations can differ
`W`	The $(m \times m)$ -dimensional symmetric weight matrix $W$
`lambda1`	Vector with different $\lambda_1$ . LASSO penalty terms (Default: `1:2`)
`lambda2`	Vector with different $\lambda_2$ . The global smoothing parameter values (Default: `1:2`)
`gamma1`	A vector of $\gamma_1$ 's LASSO penalty terms, where $\gamma_1 = \frac{2 \lambda_1}{m p (1 - p)}$ . If `gamma1` is set, the value of `lambda1` is ignored. (Default: `NULL`).
`gamma2`	A vector of $\gamma_2$ 's global smoothing parameters, where that $\gamma_2 = \frac{4 \lambda_2}{m(m-1)p(p-1)}$ . If `gamma2` is set, the value of `lambda2` is ignored.(Default: `NULL`).
`rho`	The $\rho$ penalty parameter for the global ADMM algorithm (Default: `1`)
`eps`	If the relative difference between two update steps is smaller than $\epsilon$ , the algorithm stops. (Default: `1e-4`)
`maxiter`	Maximum number of iterations (Default: `100`)
`truncate`	All values of the final $\hat{\Theta}_i$ 's below `truncate` will be set to `0`. (Default: `1e-5`)
`rho_genlasso`	The $\rho$ penalty parameter for the ADMM algorithm used to solve the generalized LASSO (Default: `1`)
`eps_genlasso`	If the relative difference between two update steps is smaller than $\epsilon$ , the algorithm stops. (Default: `1e-10`)
`maxiter_genlasso`	Maximum number of iterations for solving the generalized LASSO problem (Default: `100`)
`truncate_genlasso`	All values of the final $\hat{\beta}$ below `truncate_genlasso` will be set to `0`. (Default: `1e-4`)
`n_cores`	Number of cores used (Default: max. number of cores - 1, or the total number penalty term pairs if that is less)
`normalized`	Data is normalized if `TRUE`. Otherwise the data is only centered (Default: `FALSE`)
`warmstart`	If `TRUE`, use the `glasso` package for estimating the individual graphs first (Default: `TRUE`)
`minimal`	If `TRUE`, the returned `cvn` is minimal in terms of memory, i.e., `Theta`, `data` and `Sigma` are not returned (Default: `FALSE`)
`gamma_ebic`	Gamma value for the eBIC (Default: 0.5)
`verbose`	Verbose (Default: `TRUE`)

Value

A CVN object containing the estimates for all the graphs for each different value of $(\lambda_1, \lambda_2)$ . General results for the different values of $(\lambda_1, \lambda_2)$ can be found in the data frame results. It consists of multiple columns, namely:

`id`	The id. This corresponds to the indices of the lists
`lambda1`	$\lambda_1$ value
`lambda2`	$\lambda_2$ value
`gamma1`	$\gamma_1$ value
`gamma2`	$\gamma_2$ value
`converged`	whether algorithm converged or not
`value`	value of the negative log-likelihood function
`n_iterations`	number of iterations of the ADMM
`aic`	Aikake information criterion
`bic`	Bayesian information criterion
`ebic`	Extended Bayesian information criterion
`edges_median`	Median number of edges across the m estimated graphs
`edges_iqr`	Interquartile range of edges across the m estimated graphs

The estimates of the precision matrices and the corresponding adjacency matrices for the different values of $(\lambda_1, \lambda_2)$ can be found

`Theta`	A list with the estimated precision matrices $\{ \hat{\Theta}_i(\lambda_1, \lambda_2) \}_{i = 1}^m$ , (only if `minimal = FALSE`)
`adj_matrices`	A list with the estimated adjacency matrices corresponding to the estimated precision matrices in `Theta`. The entries are `1` if there is an edge, `0` otherwise. The matrices are sparse using package `Matrix`

In addition, the input given to the CVN function is stored in the object as well:

`Sigma`	Empirical covariance matrices $\{\hat{\Sigma}_i\}_{i = 1}^m$ , (only if `minimal = FALSE`)
`m`	Number of graphs
`p`	Number of variables
`n_obs`	Vector of length $m$ with number of observations for each graph
`data`	The `data`, but then normalized or centered (only if `minimal = FALSE`)
`W`	The $(m \times m)$ -dimensional weight matrix $W$
`maxiter`	Maximum number of iterations for the ADMM
`rho`	The $\rho$ ADMM's penalty parameter
`eps`	The stopping criterion $\epsilon$
`truncate`	Truncation value for $\{ \hat{\Theta}_i \}_{i = 1}^m$
`maxiter_genlasso`	Maximum number of iterations for the generarlzed LASSO
`rho_genlasso`	The $\rho$ generalized LASSO penalty parameter
`eps_genlasso`	The stopping criterion $\epsilon$ for the generalized LASSO
`truncate_genlasso`	Truncation value for $\beta$ of the generalized LASSO
`n_lambda_values`	Total number of $(\lambda_1, \lambda_2)$ value combinations
`normalized`	If `TRUE`, `data` was normalized. Otherwise `data` was only centered
`warmstart`	If `TRUE`, warmstart was used
`minimal`	If `TRUE`, `data`, `Theta` and `Sigma` are not added
`hits_border_aic`	If `TRUE`, the optimal model based on the AIC hits the border of $(\lambda_1, \lambda_2)$
`hits_border_bic`	If `TRUE`, the optimal model based on the BIC hits the border of $(\lambda_1, \lambda_2)$

Reusing Estimates

When estimating the graph for different values of $\lambda_1$ and $\lambda_2$ , we use the graph estimated (if available) for other $\lambda_1$ and $\lambda_2$ values closest to them.

Examples

data(grid)

#' Choice of the weight matrix W. Each of 2 covariates has 3 categories
#' (uniform random)
W <- create_weight_matrix("uniform-random", k = 3, l = 3)

# lambdas:
lambda1 = 1  # can also be lambda1 = 1:2 
lambda2 = 1

(fit <- CVN(data = grid, 
            W = W, 
            lambda1 = lambda1, lambda2 = lambda2, 
            n_cores = 1,
            eps = 1e-2, maxiter = 200, # fast but imprecise
            verbose = TRUE))
data(grid)

#' Choice of the weight matrix W. Each of 2 covariates has 3 categories
#' (uniform random)
W <- create_weight_matrix("uniform-random", k = 3, l = 3)

# lambdas:
lambda1 = 1  # can also be lambda1 = 1:2 
lambda2 = 1

(fit <- CVN(data = grid, 
            W = W, 
            lambda1 = lambda1, lambda2 = lambda2, 
            n_cores = 1,
            eps = 1e-2, maxiter = 200, # fast but imprecise
            verbose = TRUE))

Edge Overview

Description

Function that gives an overview about the number of edges in each subgraph over all fitted CVN models.

Usage

cvn_edge_summary(cvn)
cvn_edge_summary(cvn)

Arguments

cvn

A cvn object

Value

A data.frame showing the number of edges in each subgraph, the number of edges present in all graphs (core edges) and the number of edges that are unique for a subgraph

Examples

data(grid)
W <- create_weight_matrix("grid", 3, 3)

# lambdas:
lambda1 = c(1, 1.5)
lambda2 = .2

fit <- CVN(grid, W, lambda1 = lambda1, lambda2 = lambda2, n_cores = 1)

# Edge summary for a list of CVN models
cvn_edge_summary(fit)

# Edge summary for a single CVN
fit2 <- extract_cvn(fit, id = 2)
cvn_edge_summary(fit2)                 

data(grid)
W <- create_weight_matrix("grid", 3, 3)

# lambdas:
lambda1 = c(1, 1.5)
lambda2 = .2

fit <- CVN(grid, W, lambda1 = lambda1, lambda2 = lambda2, n_cores = 1)

# Edge summary for a list of CVN models
cvn_edge_summary(fit)

# Edge summary for a single CVN
fit2 <- extract_cvn(fit, id = 2)
cvn_edge_summary(fit2)

Information Criteria for a `cvn` object

Description

Determines a given information criteria for a cvn object, see CVN.

Usage

determine_information_criterion_cvn(cvn, gamma = 0.5)
determine_information_criterion_cvn(cvn, gamma = 0.5)

Arguments

`cvn`	A CVN object, see `CVN`
`gamma`	The gamma value for the eBIC (default: 0.5)

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
determine_information_criterion_cvn(fit, gamma = 0.7)
path <- system.file("cvnfit.RData", package = "CVN")
load(path)
determine_information_criterion_cvn(fit, gamma = 0.7)

Extract CVN

Description

Function that extracts one CVN if the CVN object contains more than one. Its helpful when just one tuning parameter constellation wants to be, e.g., plotted.

Usage

extract_cvn(cvn, id)
extract_cvn(cvn, id)

Arguments

`cvn`	A CVN object, see `CVN`
`id`	Integer; Which id from the CVN object should be extracted

Value

A CVN object

Examples

## Not run: 
# Example code of usage (not run because of longer running time)

data(grid)
W <- create_weight_matrix("grid", 3, 3)
fit <-  CVN(grid, W, n_cores = 1,
            lambda1 = c(0.5, 1), 
            lambda2 = c(0.1, 0.5)) 
(fit2 <- extract_cvn(fit, id = 2))

## End(Not run)


## Not run: 
# Example code of usage (not run because of longer running time)

data(grid)
W <- create_weight_matrix("grid", 3, 3)
fit <-  CVN(grid, W, n_cores = 1,
            lambda1 = c(0.5, 1), 
            lambda2 = c(0.1, 0.5)) 
(fit2 <- extract_cvn(fit, id = 2))

## End(Not run)

The Core Graph

Description

Finds the 'core graph', i.e., those edges that are present in all of the estimated graphs

Usage

find_core_graph(cvn)
find_core_graph(cvn)

Arguments

cvn

A cvn object

Value

A list of adjacency matrix, one for each value of (lambda1, lambda2)

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
find_core_graph(fit) 

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
find_core_graph(fit)

Unique Edges

Description

Function that finds edges that are only present in one subgraph of the CVN model.

Usage

find_unique_edges(cvn)
find_unique_edges(cvn)

Arguments

cvn

A cvn object

Value

A list of adjacency matrix, one for each value of (lambda1, lambda2), showing the edges that are unique for each single subgraph.

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
                  
ue <- find_unique_edges(fit)

# Graph 3 has unique edges
ue[[1]][[3]]

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
                  
ue <- find_unique_edges(fit)

# Graph 3 has unique edges
ue[[1]][[3]]

Generalized LASSO

Description

Solving Generalized LASSO with fixed $\lambda = 1$ Solves efficiently the generalized LASSO problem of the form

$\hat{\beta} = \text{argmin } \frac{1}{2} || y - \beta ||_2^2 + ||D\beta||_1$

where $\beta$ and $y$ are $m$ -dimensional vectors and $D$ is a $(c \times m)$ -matrix where $c \geq m$ . We solve this optimization problem using an adaption of the ADMM algorithm presented in Zhu (2017).

Usage

genlassoRcpp(Y, W, m, eta1, eta2, a, rho, max_iter, eps, truncate)
genlassoRcpp(Y, W, m, eta1, eta2, a, rho, max_iter, eps, truncate)

Arguments

`Y`	The $y$ vector of length $m$
`W`	The weight matrix $W$ of dimensions $m x m$
`m`	The number of graphs
`eta1`	Equals $\lambda_1 / rho$
`eta2`	Equals $\lambda_2 / rho$
`a`	Value added to the diagonal of $-D'D$ so that the matrix is positive definite, see `matrix_A_inner_ADMM`
`rho`	The ADMM's parameter
`max_iter`	Maximum number of iterations
`eps`	Stopping criterion. If differences are smaller than $\epsilon$ , algorithm is halted
`truncate`	Values below `truncate` are set to `0`

Value

The estimated vector $\hat{\beta}$

Author(s)

Louis Dijkstra

References

Zhu, Y. (2017). An Augmented ADMM Algorithm With Application to the Generalized Lasso Problem. Journal of Computational and Graphical Statistics, 26(1), 195–204. https://doi.org/10.1080/10618600.2015.1114491

Data for a grid of graphs (3 x 3)

Description

Data generated for 9 graphs in total, organized in a grid of (3x3). Each data set has 10 variables drawn from a multinormal distribution given 9 adjacency matrices reflecting a graph structure that follows an Erdös-Rényi graph with probability 0.5. The number of edges that are removed or added in each step of the 'x'- and 'y' direction is 2.

Usage

data(grid)
data(grid)

Structural Hamming Distance for a `cvn` Object

Description

Returns the structural Hamming distances

Usage

hamming_distance(cvn, verbose = TRUE)
hamming_distance(cvn, verbose = TRUE)

Arguments

`cvn`	A `cvn` object created by the `CVN` function
`verbose`	If `TRUE`, shows a progress bar

Value

A list of symmetric matrices. Each matrix contains the structural Hamming distances between the different graphs. Each item in the list corresponds to one $(\lambda_1, \lambda_2)$ pair

Structural Hamming Distance

Description

Returns the structural Hamming distance between multiple graphs

Usage

hamming_distance_adj_matrices(adj_matrices)
hamming_distance_adj_matrices(adj_matrices)

Arguments

adj_matrices

A list of adjacency matrices

Value

Matrix of Hamming distances

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

hamming_distance_adj_matrices(fit$adj_matrices[[1]])

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

hamming_distance_adj_matrices(fit$adj_matrices[[1]])

Heatmap Plot of the Weight Matrix

Description

Returns a heatmap of the weight matrix

Usage

hd_weight_matrix(
  W,
  title = "",
  legend_label = "weight",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8
)
hd_weight_matrix(
  W,
  title = "",
  legend_label = "weight",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8
)

Arguments

`W`	Weight matrix
`title`	Title plot (Default is none)
`legend_label`	Title of the legend (Default: "weight")
`add_counts_to_cells`	If `TRUE`, counts from the matrix are added to the plot (Default: `TRUE`)
`add_ticks_labels`	If `TRUE`, the number corresponding to the graph is add to the plot (Default: `TRUE`)
`t`	Distance between tick labels and x-axis (Default: -6)
`r`	Distance between tick labels and y-axis (Default: -8)

Value

A heatmap plot

Examples

W_uniform <- round(create_weight_matrix(type="uniform-random", 3, 2), 2)
hd_weight_matrix(W_uniform, title = "2 external covariates with 3 and 2 categories respectively")
            
W_uniform <- round(create_weight_matrix(type="uniform-random", 3, 2), 2)
hd_weight_matrix(W_uniform, title = "2 external covariates with 3 and 2 categories respectively")

Interpolation of a Graph

Description

Estimates a graph for which there are no observation based on a previously fitted CVN model

Usage

interpolate(cvn, weights, truncate = NULL)
interpolate(cvn, weights, truncate = NULL)

Arguments

`cvn`	A CVN fit with $m$ graphs
`weights`	A vector of length $m$ with the regression coefficients
`truncate`	Truncation value. When a value in the precision matrix is considered 0. If `NULL`, the same truncation is used as for the fitted CVN model (Default)

Value

A 'cvn_interpolated' object, which is a list with

`adj_matrices`	A list of adjacency matrix. One for each pair of $(\lambda_1, \lambda_2)$ values. The entries are `1` if there is an edge, `0` otherwise. The matrices are sparse using package `Matrix`
`m`	Number of graphs
`p`	Number of variables
`weights`	The weights used for interpolation
`truncate`	Truncation value
`n_lambda_values`	Total number of $(\lambda_1, \lambda_2)$ value combinations

results. It consists of two columns:

`lambda1`	$\lambda_1$ value
`lambda2`	$\lambda_2$ value

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

interpolate <- interpolate(fit, c(0,0,0,0,0,0,0,0.5,0.5), truncate = 0.05)
fit10 <- combine_cvn_interpolated(fit, interpolate)
fit10 <- visnetwork_cvn(fit10)

if (requireNamespace("htmltools", quietly = TRUE)) {
htmltools::browsable(htmltools::tagList(
  htmltools::div(style = "display: grid; grid-template-columns: repeat(3, 1fr); 
                 column-gap: 1px; row-gap: -10px",
    fit10$plots[[1]][8:10])))
} else {
plot10$plots[[1]][8:10]
} 
             
path <- system.file("cvnfit.RData", package = "CVN")
load(path)

interpolate <- interpolate(fit, c(0,0,0,0,0,0,0,0.5,0.5), truncate = 0.05)
fit10 <- combine_cvn_interpolated(fit, interpolate)
fit10 <- visnetwork_cvn(fit10)

if (requireNamespace("htmltools", quietly = TRUE)) {
htmltools::browsable(htmltools::tagList(
  htmltools::div(style = "display: grid; grid-template-columns: repeat(3, 1fr); 
                 column-gap: 1px; row-gap: -10px",
    fit10$plots[[1]][8:10])))
} else {
plot10$plots[[1]][8:10]
}

Determine matrix $A$ for inner-ADMM for the $Z$ -update step

Description

The $Z$ -update step requires us to solve a special Generalized LASSO problem of the form

$\hat{\beta} = \text{argmin } \frac{1}{2} || y - \beta ||_2^2 + ||D\beta||_1$

where $\beta$ and $y$ are $m$ -dimensional vectors and $D$ is a $(c \times m)$ -matrix where $c = (m^2 + m) / 2$ . We solve this optimization problem using an adaption of the ADMM algorithm presented in Zhu (2017). This algorithm requires the choice of a matrix $A$ such that $A - D'D$ is positive semidefinite. In order to optimize the ADMM, we choose the matrix $A$ to be diagonal with a fixed value $a$ . This function determines the smallest value of $a$ such that $A - D'D$ is indeed positive semidefinite. We do this be determining the largest eigenvalue

Usage

matrix_A_inner_ADMM(W, eta1, eta2)
matrix_A_inner_ADMM(W, eta1, eta2)

Arguments

`W`	Weight matrix $W$
`eta1`, `eta2`	The values $\eta_1 = \lambda_1 / \rho$ and $\eta_2 = \lambda_2 / \rho$

Value

Value of $a$

Author(s)

Louis Dijkstra

References

Zhu, Y. (2017). An Augmented ADMM Algorithm With Application to the Generalized Lasso Problem. Journal of Computational and Graphical Statistics, 26(1), 195–204.
doi:10.1080/10618600.2015.1114491

Heat Map of the Distances between Graphs

Description

Returns a heat map of the distance matrix for a particular CVN

Usage

plot_hamming_distances(
  distance_matrix,
  absolute = TRUE,
  limits = c(NA, NA),
  title = "",
  legend_label = "Hamming Distance",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8
)
plot_hamming_distances(
  distance_matrix,
  absolute = TRUE,
  limits = c(NA, NA),
  title = "",
  legend_label = "Hamming Distance",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8
)

Arguments

`distance_matrix`	Symmetric matrix with distances
`absolute`	If `FALSE`, rescaled to [0,1]
`limits`	The limits for the values of the Hamming distance
`title`	Title plot (Default is none)
`legend_label`	Title of the legend (Default: "Hamming Distance")
`add_counts_to_cells`	If `TRUE`, counts from the matrix are added to the plot (Default: `TRUE`)
`add_ticks_labels`	If `TRUE`, the number corresponding to the graph is add to the plot (Default: `TRUE`)
`t`	Distance between tick labels and x-axis (Default: -6)
`r`	Distance between tick labels and y-axis (Default: -8)

Value

A heatmap plot

Examples

         
path <- system.file("cvnfit.RData", package = "CVN")
load(path)
hd <- hamming_distance(fit, verbose = FALSE)

plot_hamming_distances(hd$distance[[1]])
path <- system.file("cvnfit.RData", package = "CVN")
load(path)
hd <- hamming_distance(fit, verbose = FALSE)

plot_hamming_distances(hd$distance[[1]])

Heatmaps for a CVN

Description

Creates all the heatmaps for a CVN, a heatmap for each pair of $(\lambda_1, \lambda_2)$

Usage

plot_hamming_distances_cvn(
  cvn,
  absolute = TRUE,
  same_range = TRUE,
  titles = rep("", cvn$n_lambda_values),
  legend_label = "Hamming Distance",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8,
  verbose = TRUE
)
plot_hamming_distances_cvn(
  cvn,
  absolute = TRUE,
  same_range = TRUE,
  titles = rep("", cvn$n_lambda_values),
  legend_label = "Hamming Distance",
  add_counts_to_cells = TRUE,
  add_ticks_labels = TRUE,
  t = -6,
  r = -8,
  verbose = TRUE
)

Arguments

`cvn`	A `cvn` object
`absolute`	If `FALSE`, rescaled to [0,1]
`same_range`	If `TRUE`, all heatmaps have the same range of values of the Hamming distance shown (Default: TRUE)
`titles`	Title of the plots (Default is none)
`legend_label`	Title of the legend (Default: "Hamming Distance")
`add_counts_to_cells`	If `TRUE`, counts from the matrix are added to the plot (Default: `TRUE`)
`add_ticks_labels`	If `TRUE`, the number corresponding to the graph is add to the plot (Default: `TRUE`)
`t`	Distance between tick labels and x-axis (Default: -6)
`r`	Distance between tick labels and y-axis (Default: -8)
`verbose`	If `TRUE`, shows progress bar (Default: `TRUE`)

Value

List of plots

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

plot_hamming_distances_cvn(fit)

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

plot_hamming_distances_cvn(fit)

Heat Map of an Information Criterion (AIC or BIC)

Description

Returns a heat map of the AIC or BIC for a fitted CVN

Usage

plot_information_criterion(
  cvn,
  criterion = c("bic", "aic", "ebic"),
  use_gammas = TRUE,
  show_minimum = TRUE,
  title = "",
  xlabel = NULL,
  ylabel = NULL,
  legend_label = NULL,
  limits = c(NA, NA)
)
plot_information_criterion(
  cvn,
  criterion = c("bic", "aic", "ebic"),
  use_gammas = TRUE,
  show_minimum = TRUE,
  title = "",
  xlabel = NULL,
  ylabel = NULL,
  legend_label = NULL,
  limits = c(NA, NA)
)

Arguments

`cvn`	Fitted CVN, see `CVN`
`criterion`	The information criterion, must be either `'aic'` or `'bic'`. Default: `'bic'`
`use_gammas`	If `TRUE`, plots the $\gamma$ -values. Otherwise, the $\lambda$ -values are used
`show_minimum`	If `TRUE`, an orange dot is put on the point with the minimum value of the information criterion is. If `FALSE`, no dot is added. Default: `TRUE`.
`title`	Title plot (Default is none)
`xlabel`	Label for the $x$ -axis. Default depends on `use_gammas`. If `use_gammas = TRUE`, then the label is 'gamma1'. Otherwise, 'lambda1'
`ylabel`	Label for the $x$ -axis. Default depends on `use_gammas`. If `use_gammas = TRUE`, then the label is 'gamma1'. Otherwise, 'lambda1'
`legend_label`	Title for the legend. Default depends on `criterion`. If `'aic'`, then the label is 'AIC'. Otherwise, 'BIC'.
`limits`	The limits for the values of the Hamming distance

Value

A heatmap plot

Examples

data(grid)
m <- 9

W <- create_weight_matrix(type="grid", 3, 3)
cvn <- CVN(grid, W, 
           lambda1 = 1:2, lambda2 = .5, n_cores = 1)
cvn$results          

# The smaller the IC value, the better the fit. 
plot_information_criterion(cvn, criterion = "aic")
plot_information_criterion(cvn, criterion = "bic")
plot_information_criterion(cvn, criterion = "ebic")


data(grid)
m <- 9

W <- create_weight_matrix(type="grid", 3, 3)
cvn <- CVN(grid, W, 
           lambda1 = 1:2, lambda2 = .5, n_cores = 1)
cvn$results          

# The smaller the IC value, the better the fit. 
plot_information_criterion(cvn, criterion = "aic")
plot_information_criterion(cvn, criterion = "bic")
plot_information_criterion(cvn, criterion = "ebic")

Plot weight matrix as a grid

Description

This function requires the igraph package to be installed.

Usage

plot_weight_matrix(W, k, l)
plot_weight_matrix(W, k, l)

Arguments

`W`	The weight matrix which equals an adjacency matrix
`k`	Number of categories in the first external covariate
`l`	Number of categories in the second external covariate

Value

An igraph object

Examples

# Requires to have the igraph package to be installed
W <- create_weight_matrix(type = "full", k = 2, l = 3)
plot_weight_matrix(W, k=2, l=3)

# Requires to have the igraph package to be installed
W <- create_weight_matrix(type = "full", k = 2, l = 3)
plot_weight_matrix(W, k=2, l=3)

Plot Function for CVN Object Class

Description

Custom plot method for CVN objects.

Usage

## S3 method for class 'cvn'
plot(x, ...)
## S3 method for class 'cvn'
plot(x, ...)

Arguments

`x`	`cvn` object
`...`	Additional arguments to pass to `visnetwork_cvn`

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
fit <- plot(fit) 
fit$plots[[1]][[4]]

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
fit <- plot(fit) 
fit$plots[[1]][[4]]

Print CVN

Description

Print contents of CVN object

Usage

## S3 method for class 'cvn'
print(x, ...)
## S3 method for class 'cvn'
print(x, ...)

Arguments

`x`	Object of classs 'CVN'
`...`	Additional arguments to pass

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

print(fit)

path <- system.file("cvnfit.RData", package = "CVN")
load(path)

print(fit)

The Relative Difference between two Precision Matrices

Description

Returns the relative $L1$ difference between precision matrix $\Theta(k+1)$ (parameter Theta_new) and $\Theta(k)$ (parameter Theta_old).

Usage

relative_difference_precision_matrices(Theta_new, Theta_old)
relative_difference_precision_matrices(Theta_new, Theta_old)

Arguments

`Theta_new`	A list with matrices with the updated values of $\Theta$
`Theta_old`	A list with matrices with the old values of $\Theta$

Details

This is used for checking whether the stopping condition has been met.

Value

The relative difference between $\Theta(k+1)$ and $\Theta(k)$

Add Attributes to Subset of Edges for `visNetwork`

Description

A subset of edges can be assign a different thickness or color.

Usage

set_attributes_to_edges_visnetwork(
  edges,
  subset_edges,
  width = c(NA, NA),
  color = c(NULL, NULL)
)
set_attributes_to_edges_visnetwork(
  edges,
  subset_edges,
  width = c(NA, NA),
  color = c(NULL, NULL)
)

Arguments

`edges`	A data.frame create by `create_edges_visnetwork`
`subset_edges`	A list with the elements `from` and `to`. Both `from` and `to` are vectors of the same length denoting the different edges
`width`	Vector with two values. The first is assigned to the edges in the subset given by `subset_edges`. The second value is assigned to the rest. If `width = c(NA,NA)`, no width is assigned
`color`	Vector with two values. The first is assigned to the edges in the subset given by `subset_edges`. The second value is assigned to the rest. If `color = c(NULL,NULL)`, no color is assigned

Value

A data frame that can be used by the visNetwork package

Examples

nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)
nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)

Strip CVN

Description

Function that removes most of the items to make the CVN object more memory sufficient. This is especially important when the graphs are rather larger

Usage

strip_cvn(cvn)
strip_cvn(cvn)

Arguments

cvn

Object of classs 'CVN'

Value

Reduced CVN where Theta, data and Sigma are removed

The $Z$ -update Step

Description

A C implementation of the $Z$ -update step. We solve a generalized LASSO problem repeatedly for each of the individual edges

Usage

updateZRcpp(m, p, Theta, Y, W, eta1, eta2, a, rho, max_iter, eps, truncate)
updateZRcpp(m, p, Theta, Y, W, eta1, eta2, a, rho, max_iter, eps, truncate)

Arguments

`m`	The number of graphs
`p`	The number of variables
`Theta`	A list of matrices with the $\Theta$ -matrices
`Y`	A list of matrices with the $Y$ -matrices
`W`	The weight matrix $W$ of dimensions $m x m$
`eta1`	Equals $\lambda_1 / rho$
`eta2`	Equals $\lambda_2 / rho$
`a`	Value added to the diagonal of $-D'D$ so that the matrix is positive definite, see `matrix_A_inner_ADMM`
`rho`	The ADMM's parameter
`max_iter`	Maximum number of iterations
`eps`	Stopping criterion. If differences are smaller than $\epsilon$ , algorithm is halted
`truncate`	Values below `truncate` are set to `0`

Value

The estimated vector $\hat{\beta}$

Author(s)

Louis Dijkstra

A `visNetwork` plot

Description

Creates a visNetwork plot given a list of nodes and edges. The nodes data frame can be created with create_nodes_visnetwork; the edges with create_edges_visnetwork. In order to highlight edges, you can use set_attributes_to_edges_visnetwork.

Usage

visnetwork(
  nodes,
  edges,
  node_titles = nodes$id,
  title = "",
  igraph_layout = "layout_in_circle"
)
visnetwork(
  nodes,
  edges,
  node_titles = nodes$id,
  title = "",
  igraph_layout = "layout_in_circle"
)

Arguments

`nodes`	A data frame with rows equal to the number of nodes with columns "id" and "title". Can be created with `create_nodes_visnetwork`.
`edges`	A data frame with columns "from" and "to. Each row represents an edge between two nodes (integer)
`node_titles`	Vector with title of the nodes (Default: `1:p`)
`title`	A list with `n_lambda_values` vectors. Each vector is of the lenght `m`. Regulates the titles of the graphs (Default: no title)
`igraph_layout`	igraph layout (default: layout_in_circle)

Value

A visNetwork plot

Examples

nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)
nodes <- create_nodes_visnetwork(n_nodes = 5, labels = LETTERS[1:5])

adj_matrix <- matrix(c(0, 1, 0, 1, 0,
                       1, 0, 1, 0, 0,
                       0, 1, 0, 0, 0,
                       1, 0, 0, 0, 1,
                       0, 0, 0, 1, 0), ncol = 5)

edges <- create_edges_visnetwork(adj_matrix)

shared_edges <- data.frame(from = c(1,2), to = c(4, 3))

edges <- set_attributes_to_edges_visnetwork(edges,
                                            subset_edges = shared_edges,
                                            width = c(3, .5),
                                            color = c("red", "blue"))

visnetwork(nodes, edges)

All `visNetwork` plots for a CVN object

Description

Creates all visNetwork plots, see visnetwork, for all graphs in a cvn object

Usage

visnetwork_cvn(
  cvn,
  node_titles = 1:cvn$p,
  titles = lapply(1:cvn$n_lambda_values, function(i) sapply(1:cvn$m, function(j) "")),
  show_core_graph = TRUE,
  width = c(3, 1),
  color = c("red", "blue"),
  igraph_layout = "layout_in_circle",
  verbose = TRUE
)
visnetwork_cvn(
  cvn,
  node_titles = 1:cvn$p,
  titles = lapply(1:cvn$n_lambda_values, function(i) sapply(1:cvn$m, function(j) "")),
  show_core_graph = TRUE,
  width = c(3, 1),
  color = c("red", "blue"),
  igraph_layout = "layout_in_circle",
  verbose = TRUE
)

Arguments

`cvn`	A `cvn` object, see `CVN`
`node_titles`	Vector with title of the nodes (Default: `1:p`)
`titles`	A list with `n_lambda_values` vectors. Each vector is of the lenght `m`. Regulates the titles of the graphs (Default: no title)
`show_core_graph`	Shall the core graph be visualized (Default = TRUE)
`width`	Edge width of the core graph
`color`	String vector with two colors. The first color marks the edges in the core graph (Default: c("red", "blue"))
`igraph_layout`	igraph layout (default: layout_in_circle)
`verbose`	Verbose (Default: `TRUE`)

Value

The cvn input which is extended by the list element 'plots'

Examples

path <- system.file("cvnfit.RData", package = "CVN")
load(path)
fit_plot <- visnetwork_cvn(fit)
fit_plot$plots[[1]][[1]]
path <- system.file("cvnfit.RData", package = "CVN")
load(path)
fit_plot <- visnetwork_cvn(fit)
fit_plot$plots[[1]][[1]]

Package 'CVN'

Help Index

Covariate-varying Networks

Description

Author(s)

References

See Also

Examples

Combine CVN object with interpolated CVN object

Description

Usage

Arguments

Value

Examples

Create a data.frame for the Edges for visNetwork

Description

Usage

Arguments

Value

Examples

Nodes for the visNetwork package

Description

Usage

Arguments

Value

Examples

Different Weight Matrices

Description

Usage

Arguments

Value

Examples

Estimating a Covariate-Varying Network (CVN)

Description

Usage

Arguments

Value

Reusing Estimates

Examples

Edge Overview

Description

Usage

Arguments

Value

Examples

Information Criteria for a cvn object

Description

Usage

Arguments

Examples

Extract CVN

Description

Usage

Arguments

Value

Examples

The Core Graph

Description

Usage

Arguments

Value

Examples

Unique Edges

Description

Usage

Arguments

Value

Examples

Generalized LASSO

Description

Usage

Arguments

Value

Author(s)

References

See Also

Data for a grid of graphs (3 x 3)

Description

Usage

Structural Hamming Distance for a cvn Object

Create a `data.frame` for the Edges for `visNetwork`

Nodes for the `visNetwork` package

Information Criteria for a `cvn` object

Structural Hamming Distance for a `cvn` Object

Determine matrix $A$ for inner-ADMM for the $Z$ -update step