Type:	Package
Title:	Extracting and Visualizing Bayesian Graphical Models
Version:	0.2.1
Maintainer:	Karoline Huth <k.huth@uva.nl>
Description:	Fit and visualize the results of a Bayesian analysis of networks commonly found in psychology. The package supports fitting cross-sectional network models fitted using the packages 'BDgraph', 'bgms' and 'BGGM'. The package provides the parameter estimates, posterior inclusion probabilities, inclusion Bayes factor, and the posterior density of the parameters. In addition, for 'BDgraph' and 'bgms' it allows to assess the posterior structure space. Furthermore, the package comes with an extensive suite for visualizing results.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	https://github.com/KarolineHuth/easybgm
BugReports:	https://github.com/KarolineHuth/easybgm/issues
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	BDgraph, BGGM, bgms (≥ 0.1.3), dplyr, ggplot2, HDInterval, igraph, qgraph
Suggests:	testthat (≥ 3.0.0), vdiffr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-10-17 08:04:27 UTC; karolinehuth
Author:	Karoline Huth [aut, cre], Sara Keetelaar [ctb]
Repository:	CRAN
Date/Publication:	2024-10-17 08:30:02 UTC

Plot of interaction parameters and their 95% highest density intervals

Description

Plots the 95% highest density interval of the posterior distribution of the parameter estimates. The plot can be used to visualize the uncertainty of the partial association estimates. The x-axis indicates the strength of the partial association. The y-axis indicates the edge between nodes $i$ and $j$. The farther the posterior estimates (i.e., the points in the plot) are from zero, the stronger the partial association of the edge. The wider the highest density intervals (i.e., the error bar around the point), the less certain we are about the strength of the association.

Usage

plot_parameterHDI(output, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)


data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "ordinal",
              iter = 1000,  # for demonstration only (> 5e4 recommended)
              save = TRUE, edge_selection = TRUE)
plot_parameterHDI(fit)

Extract the results of a Bayesian analysis of networks

Description

Extract the results of a Bayesian analysis of networks

Usage

bgm_extract(fit, ...)

Arguments

Fit a Bayesian analysis of networks

Description

Fit a Bayesian analysis of networks

Usage

bgm_fit(fit, ...)

Arguments

Plot strength centralities and 95% highest density interval

Description

Visualize the strength centralities and their uncertainties. The centrality estimate can be obtained for each sample of the posterior distribution of the association parameters to obtain an estimate of the uncertainty of the strength centrality estimate.

Usage

plot_centrality(output, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "ordinal",
                iter = 1000,  # for demonstration only (> 5e4 recommended)
                save = TRUE, edge_selection = TRUE,
                centrality = TRUE)

plot_centrality(fit)

Plot posterior complexity probabilities

Description

Plots the posterior complexity probabilities of all visited structures, where complexity comprises the network density.

Usage

plot_complexity_probabilities(output, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "ordinal", save = TRUE, edge_selection = TRUE,
                iter = 1000  # for demonstration only (> 5e4 recommended)
                )

plot_complexity_probabilities(fit)

Fit a Bayesian analysis of networks

Description

Easy estimation of a Bayesian analysis of networks to obtain conditional (in)dependence relations between variables in a network.

Usage

easybgm(
  data,
  type,
  package = NULL,
  not_cont = NULL,
  iter = 10000,
  save = FALSE,
  centrality = FALSE,
  progress = TRUE,
  posterior_method = "model-averaged",
  ...
)

Arguments

Details

Users may oftentimes wish to deviate from the default, usually uninformative, prior specifications of the packages to informed priors. This can be done by simply adding additional arguments to the easybgm function. Depending on the package that is running the underlying network estimation, researcher can specify different prior arguments. We give an overview of the prior arguments per package below.

bgms:

• interaction_scale the scale of the Cauchy distribution that is used as a prior for the pairwise interaction parameters. The default is 2.5.

• edge_prior prior on the graph structure, which can be either "Bernoulli", "Beta-Bernoulli" or "Stochastic Block". The default is "Bernoulli".

• inclusion_probability prior edge inclusion probability for the "Bernoulli" distribution. The default is 0.5.

• beta_bernoulli_alpha and beta_bernoulli_alpha the parameters of the "Beta-Bernoulli" or "Stochastic Block" priors. The default is 1 for both.

• dirichlet_alpha The shape of the Dirichlet prior on the node-to-block allocation parameters for the Stochastic Block prior on the graph structure.

• threshold_alpha and threshold_beta the parameters of the beta-prime distribution for the threshold parameters. The defaults are both set to 1.

• variable_type What kind of variables are there in x? Can be a single character string specifying the variable type of all p variables at once or a vector of character strings of length p specifying the type for each variable in x separately. Currently, bgm supports ⁠ordinal'' and ⁠blume-capel”. Binary variables are automatically treated as “ordinal’’. Defaults to variable_type = "ordinal".

• reference_category he reference category in the Blume-Capel model. Should be an integer within the range of integer scores observed for the 'blume-capel' variable. Can be a single number specifying the reference category for all Blume-Capel variables at once, or a vector of length p where the i-th element contains the reference category for variable i if it is Blume-Capel, and bgm ignores its elements for other variable types. The value of the reference category is also recoded when bgm recodes the corresponding observations. Only required if there is at least one variable of type “blume-capel”.

BDgraph:

• df.prior prior on the parameters (i.e., inverse covariance matrix), degrees of freedom of the prior G-Wishart distribution. The default is set to 2.5.

• g.prior prior probability of edge inclusion. This can be either a scalar, if it is the same for all edges, or a matrix, if it should be different among the edges. The default is set to 0.5.

BGGM:

• prior_sd the standard deviation of the prior distribution of the interaction parameters, approximately the scale of a beta distribution. The default is 0.25.

We would always encourage researcher to conduct prior robustness checks.

Value

The returned object of easybgm contains several elements:

• parameters A p x p matrix containing partial associations.

• inc_probs A p x p matrix containing the posterior inclusion probabilities.

• BF A p x p matrix containing the posterior inclusion Bayes factors.

• structure Adjacency matrix of the median probability model (i.e., edges with a posterior probability larger 0.5).

In addition, for BDgraph and bgms, the function returns:

• structure_probabilities A vector containing the posterior probabilities of all visited structures, between 0 and 1.

• graph_weights A vector containing the number of times a particular structure was visited.

• sample_graphs A vector containing the indexes of a particular structure.

For all packages, when setting save = TRUE and centrality = TRUE, the function will return the following objects respectively:

• samples_posterior A k x iter matrix containing the posterior samples for each parameter (i.e., k = (p/(p-1))/2) at each iteration (i.e., iter) of the sampler.

• centrality A p x iter matrix containing the centrality of a node at each iteration of the sampler.

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)

# Fitting the Wenchuan PTSD data

fit <- easybgm(data, type = "continuous",
                iter = 1000 # for demonstration only (> 5e4 recommended)
                )

summary(fit)


# To extract the posterior parameter distribution
# and centrality measures

fit <- easybgm(data, type = "continuous",
                iter = 1000, # for demonstrative purposes, generally, 1e5 iterations are recommended
                save = TRUE,
                centrality = TRUE)

Edge evidence plot

Description

The edge evidence plot colors edges according to their hypothesis testing results: blue for included, red for excluded, and gray for inconclusive. This plot can be used to visualize the hypothesis testing results whether edge presence or absence. The edge evidence plot can aid researchers in deciding which edges provide robust inferential conclusions

Usage

plot_edgeevidence(
  output,
  evidence_thresh = 10,
  split = FALSE,
  show = "all",
  ...
)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "continuous",
                iter = 1000  # for demonstration only (> 5e4 recommended)
                )

plot_edgeevidence(fit)

oldpar <- par(mfrow = c(1,1))

par(mfrow = c(1, 2))
plot_edgeevidence(fit, split = TRUE)

#' par(mfrow = c(1, 3))
plot_edgeevidence(fit, show = "included")
plot_edgeevidence(fit, show = "inconclusive")
plot_edgeevidence(fit, show = "excluded")

par(oldpar)

Network plot

Description

The network plot visualizes the strength of interactions between two nodes, the partial associations. Solely edges with a posterior inclusion probability larger than the exc_prob argument (default = 0.5) are shown. Edge thickness and saturation represent the strength of the association; the thicker the edge, the stronger the association. Red edges indicate negative relations and blue edges indicate positive associations.

Usage

plot_network(output, exc_prob = 0.5, evidence_thresh = 10, dashed = FALSE, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "continuous",
                iter = 1000  # for demonstration only (> 5e4 recommended)
                )

plot_network(fit)

# Shows all edges with an inclusion probability larger than 0.1
plot_network(fit, exc_prob = 0.1)

# Indicate which edges have insufficient evidence for inclusion through a dashed line
plot_network(fit, dashed = TRUE, evidence_thresh = 10)

Print method for easybgm objects

Description

Used to print easybgm results. The nicest overview is created by first feeding it to summary()

Usage

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

Arguments

Value

Prints the output of a Bayesian cross-sectional network model fitted with 'easybgm'

Plot sensitivity to edge inclusion prior setting

Description

For a given list of easybgm outputs with different prior edge inclusion probabilities, the function plots the percentage of edges that are included, excluded, and inconclusive.

Usage

plot_prior_sensitivity(output, ...)

Arguments

Details

Prior sensitivity plot

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

#data <- na.omit(Wenchuan)
#fit1 <- easybgm(data, type = "ordinal",
#               iter = 1000  # for demonstration only (> 5e4 recommended),
#                inclusion_probability = .1
#               )
#fit2 <- easybgm(data, type = "ordinal",
#                  iter = 1000,
#                  inclusion_probability = .5
#             )
#fit3 <- easybgm(data, type = "ordinal",
#                iter = 1000, inclusion_probability = .9)              

#plot_prior_sensitivity(list(fit1, fit2, fit3))

Test for sparse against dense topologies

Description

The function tests if a network is sparse (i.e., few edges in between nodes) or dense (i.e., a lot of edges between nodes). It estimates the network model of a given data set under the hypothesis that it is sparse and that it is dense, and computes th Bayes factor.

Usage

sparse_or_dense(x, type, ...)

Arguments

Value

List containing results of the analysis:

• log.BF The log of the Bayes factor of the test of a sparse against a dense network structure. A value larger 0 indicates evidence for a sparse structure. Contrarily, a value smaller 0 indicates evidence for a dense structure.

• BF The Bayes factor of the test of a sparse against a dense network structure. A value larger 1 indicates evidence for a sparse structure. Contrarily, a value between 0 and 1 indicates evidence for a dense structure.

• relative.complexity.sparse The relative complexity under a sparse prior hypothesis, which is the proportion of estimated included edges relative to the total possible edges under the different hypotheses.

• relative.complexity.dense The relative complexity under a dense prior hypothesis.

• relative.complexity.uniform The relative complexity under a uniform prior hypothesis.

• no.hypotheses The number of hypotheses that are computed in the analysis. At least the sparse, dense and uniform are used, but sometimes additional bridge hypotheses have to be computed to be able to determine the Bayes factor.

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)

# Fitting the Wenchuan PTSD data

fit <- sparse_or_dense(data, type = "ordinal",
                iter = 1000 # for demonstration only (> 5e4 recommended)
                )
  
             

Structure plot

Description

The plot shows the resulting graph structure, i.e. all edges with some evidence of inclusion (i.e., inclusion Bayes factor greater than 1).

Usage

plot_structure(output, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "ordinal",
                iter = 1000  # for demonstration only (> 5e4 recommended)
               )

plot_structure(fit)

Plot Posterior Structure Probabilities

Description

Plots the posterior structure probabilities of all visited structures, sorted from the most to the least probable.

Usage

plot_structure_probabilities(output, as_BF = FALSE, ...)

Arguments

Value

Returns a plot

Examples

library(easybgm)
library(bgms)

data <- na.omit(Wenchuan)
fit <- easybgm(data, type = "ordinal", save = TRUE, edge_selection = TRUE,
                iter = 1000  # for demonstration only (> 5e4 recommended)
                )

plot_structure_probabilities(fit)

Summary method for easybgm objects

Description

Used to create a object of easybgm results and in turn print it

Usage

## S3 method for class 'easybgm'
summary(object, evidence_thresh = 10, ...)

Arguments

Value

Creates and prints the output of a Bayesian cross-sectional network analysis. The summary output has four parts. The first part lists the package used, the number of variables, and the data type. The second part is a matrix of edge-specific information. Each edge is listed in a row. This row contains the posterior parameter estimate, the posterior inclusion probability, the inclusion Bayes factor, and the categorization of the edge. The category encodes whether an edge is included, excluded, or inconclusive based on the inclusion Bayes factor. Users can set the threshold for the Bayes factor classification with the evidence threshold. By default, the threshold is set to $10$. The third part of the summary provides aggregated edge information. It lists the number of included, excluded, and inconclusive edges in the network, as well as the number of possible edges. This gives the user a quick overview of the robustness and density of the network. The higher the number of conclusive edges (i.e., classified as either included or excluded), the more robust the network. Conversely, if the network has a high percentage of inconclusive edges, the network is not robust. Researchers should refrain from making strong inferential conclusions. The final output section is a description of the structure uncertainty. It shows the number of structures visited, the number of possible structures, and the highest posterior structure probability. This last section can only be obtained for networks fitted with 'BDgraph' and 'bgms'.