boot_glasso() assesses how accurately an EBIC graphical lasso network
is estimated and how stable its centralities are, by resampling the
observations (Epskamp, Borsboom & Fried, 2018). One call runs a
nonparametric bootstrap, which gives percentile intervals and inclusion
probabilities for every edge, intervals for each node's centralities and
predictability, and bootstrap tests of the difference between every pair
of edges and every pair of nodes; and a case-dropping bootstrap, which
gives each centrality measure's correlation-stability (CS) coefficient.
It takes the raw data or a network built with method = "glasso".
An interval shows how precisely an edge weight is estimated: a wide one
means the weight changes a good deal between samples. Epskamp et al.
(2018) caution that, because the lasso shrinks estimates towards zero,
these intervals are not tests of whether an edge differs from zero; the
thresholded network (edges whose interval excludes zero) and the
"significant" count in print() read them that way, and the inclusion
probability (how often an edge is non-zero across resamples) is a
separate summary. The CS-coefficient is the largest proportion of cases
that can be dropped while more than 95% of the subsamples keep a
correlation above 0.7 with the original centralities; Epskamp et al.
(2018) suggest it should not be below 0.25 and preferably above 0.5
before the centrality order is interpreted, and print() labels the
values accordingly. The difference tests are not corrected for the
number of pairs compared.
Usage
boot_glasso(
x,
iter = 1000L,
cs_iter = 500L,
cs_drop = seq(0.1, 0.9, by = 0.1),
alpha = 0.05,
gamma = 0.5,
nlambda = 100L,
centrality = c("strength", "expected_influence", "betweenness", "closeness"),
centrality_fn = NULL,
cor_method = "pearson",
ncores = 1L,
seed = NULL
)
# S3 method for class 'boot_glasso'
print(x, ...)
# S3 method for class 'boot_glasso'
summary(object, type = "edges", ...)
# S3 method for class 'boot_glasso'
plot(x, type = "edges", measure = NULL, ...)Arguments
- x
The data: a data frame or numeric matrix with one row per observation and one column per variable, cleaned as in
build_glasso(): non-numeric columns and a column namedridare set aside; columns with non-syntactic names, all-missing and constant columns, and rows with a missing value are dropped, each with a message; fewer than 2 variables or 3 complete rows, or no more rows than variables, raise an error. A square symmetric matrix with matching row and column names is read as a correlation or covariance matrix and refused (classnestimate_bad_input): it has no observations to resample. Or anetobject(orcograph_network) built withmethod = "glasso", whose data are resampled; anygamma,nlambdaorcor_methodset in itsparamsreplaces the arguments of the same name, and itslambda.min.ratio,penalize.diagonalandrefitare used too, sooriginal_pcoris the network's weights. Any other network raises an error. A correlation or covariance matrix is not accepted: a matrix is always read as data, its rows as observations. For theprint()andplot()methods: aboot_glasso.- iter
The number of nonparametric bootstrap resamples, at least 2. Default
1000.- cs_iter
The total number of case-dropping iterations, at least 1. Default
500. As in bootnet, each iteration draws one proportion fromcs_dropat random, so the iterations are spread across the proportions (aboutcs_iter / length(cs_drop)each) rather than repeatedcs_itertimes at each one.- cs_drop
The proportions of cases to drop, each in (0, 1). Default
seq(0.1, 0.9, by = 0.1).- alpha
The significance level: the intervals run from the
alpha / 2to the1 - alpha / 2quantile, andprint()and the"edge_diff"/"centrality_diff"plots mark the difference tests' p-values below it as differing. Default0.05.- gamma
The EBIC hyperparameter; larger values give sparser networks. Default
0.5. Replaced by the value stored in anetobject.- nlambda
The number of lambda values in the regularisation path, at least 2. Default
100. Replaced by the value stored in anetobject.- centrality
The centrality measures to compute. Default all four built-in ones:
"strength"(sum of absolute edge weights),"expected_influence"(sum of signed edge weights),"betweenness"and"closeness"(on shortest paths with distance 1 / |weight|). Withoutcentrality_fn, names may be abbreviated. Any other name needscentrality_fn, which then computes it; the built-in measures are always computed internally.- centrality_fn
A function for measures beyond the four built-in ones: it is called as
centrality_fn(mat)on the partial correlation matrix and returns a named list of centrality vectors, such aslist(my_metric = ...). DefaultNULL; a measure incentralitythat is neither built in nor returned by it raises an error.- cor_method
The correlation method:
"pearson"(default),"spearman"or"kendall". Replaced by the value stored in anetobject.- ncores
The number of cores for the resampling, used through
parallel::mclapply(), which forks the R process; on Windows it accepts only 1, and any larger value raises an error. Default1(sequential).- seed
A seed for reproducible resampling; the session's random state is restored when the call returns. Default
NULLuses the current random stream. Withncores > 1the resamples are reproducible only underRNGkind("L'Ecuyer-CMRG").- ...
For the
plot()method withtype = "edge_diff"or"centrality_diff":order,"sample"(default) to sort the edges by their absolute weight or the nodes by their centrality, or"id"to sort them alphabetically; withtype = "edge_diff"alsopos_colorandneg_color, the fills for a cell where the edge on the x-axis has a larger or a smaller mean bootstrap weight than the edge on the y-axis (defaults"#C0392B"and"#2C6E8A"). Ignored otherwise, and by theprint()andsummary()methods.- object
For the
summary()method: aboot_glasso.- type
What to return or draw. For the
summary()method:"edges"(default), the edge intervals sorted by decreasing absolute weight;"centrality", the centrality intervals;"cs", the case-dropping table;"predictability", the predictability intervals; or"all", the four together. For theplot()method:"edges"(default), each edge's weight and interval;"stability", the mean correlation with the original centralities against the proportion dropped, with a dashed line at 0.7;"edge_diff", a heatmap of the mean bootstrap difference between every pair of edges, faint where the pair does not differ atalphaand starred where it does, with the edge weights on the diagonal;"centrality_diff", a heatmap of which node pairs differ onmeasure, with the node values on the diagonal; or"inclusion", each edge's inclusion probability, with a dashed line at 0.5.- measure
For the
plot()method withtype = "centrality_diff": the centrality measure to compare, one of those computed (names may be abbreviated). DefaultNULL, the first measure computed.
Value
A boot_glasso object. print() reports the data size,
alpha and gamma, the number of edges whose interval excludes zero,
the mean inclusion probability, the failed resamples when there are
any, each measure's CS-coefficient with its
label, the number of edge pairs that differ, and the timing;
summary() returns the table chosen by type (edges, centralities,
case-dropping results or predictability; described at the end of this
section); plot() draws one figure chosen by type. The object's
fields:
- original_pcor
The partial correlation matrix of the original data.
- original_precision
The precision matrix of the original data.
- original_centrality
A named list with one vector of node values per centrality measure.
- original_predictability
A named vector of each node's R-squared.
- edge_ci
A data frame with one row per edge:
edge,weight,ci_lower,ci_upperandinclusion.- edge_inclusion
A named vector of edge inclusion probabilities.
- thresholded_pcor
The partial correlation matrix with every edge whose interval includes zero set to zero.
- centrality_ci
A named list with one data frame per centrality measure:
node,value,ci_lower,ci_upper.- cs_coefficient
A named vector with the CS-coefficient of each centrality measure.
- cs_data
A data frame of the case-dropping results, one row per drop proportion and measure:
drop_prop,measure,mean_cor,prop_above(the share of that proportion's iterations correlating above 0.7) andn_samples(the iterations that drew that proportion).- edge_diff_p
A symmetric matrix of the edge-difference p-values;
NULLwhen the network has more than 500 edges.- centrality_diff_p
A named list with one symmetric matrix of node-difference p-values per centrality measure.
- predictability_ci
A data frame with one row per node:
node,r2,ci_lower,ci_upper.- boot_edges
An
iterx edges matrix of the bootstrap edge weights.- boot_centrality
A named list with one
iterx nodes matrix of bootstrap values per centrality measure.- boot_predictability
An
iterx nodes matrix of bootstrap R-squared values.- nodes
The node names.
- n
The sample size.
- p
The number of variables.
- iter, cs_iter, cs_drop, alpha, gamma, nlambda
The settings used.
- centrality_measures
The centrality measures computed.
- cor_method
The correlation method used.
- lambda_path
The lambda path used for every fit.
- lambda_selected
The lambda selected on the original data.
- n_failed, cs_n_failed
The numbers of bootstrap and case-dropping resamples whose estimation failed and that were left out.
- timing
A named vector of elapsed seconds:
total,phase1(the original fit),bootstrap,case_dropandstatistics.
print() returns its input invisibly. summary() returns a data
frame: for type = "edges" the edge_ci table (edge, weight,
ci_lower, ci_upper, inclusion) sorted by decreasing absolute
weight, for "cs" the cs_data table and for "predictability" the
predictability_ci table; "centrality" returns a named list with one
data frame per measure (node, value, ci_lower, ci_upper), and
"all" a named list of the four (edges, centrality, cs,
predictability). plot() returns a ggplot object, which is drawn
when the call is made at the top level. The edge-difference plot raises
an error when the test was skipped (more than 500 edges).
Details
The network is estimated as build_glasso() estimates it: with a
netobject, with its own params (lambda.min.ratio,
penalize.diagonal, refit); with data, with that function's defaults
(smallest lambda 0.01 times the largest, no penalty on the diagonal, the
selected penalty re-solved exactly, no unregularised refit). The lambda
path is set once from the original data and reused for every resample,
which is fitted with the same settings; the penalty is chosen on it by
EBIC with gamma. Strength is the sum of a node's absolute edge weights and
expected influence the sum of its signed weights; betweenness and
closeness use shortest paths with distance 1 / |weight|, computed
without igraph. Predictability is \(1 - 1 / \Theta_{ii}\), from the
diagonal of the precision matrix, bounded to 0–1.
The case-dropping bootstrap follows bootnet: each of the cs_iter
iterations draws one proportion from cs_drop at random, keeps that
share of the rows (at least p + 1 of them) without replacement, and
correlates the subsample's centralities with the original ones; a
centrality that is constant across nodes counts as a correlation of 0.
The difference tests give, for each pair, the two-sided bootstrap p-value
2 * min(P(d >= 0), P(d <= 0)) of the difference d between the two
edges or nodes, capped at 1, with ties counted in both tails. The
edge-difference test is skipped for networks with more than 500 edges. A
resample whose estimation fails (for example, a variable constant in the
resample) is kept as missing and left out of the intervals and the
case-dropping results; the failures are counted in n_failed and
cs_n_failed, shown by print(), and reported in a warning of class
nestimate_resample_failed. The function was written as a faster, single-call
alternative to running bootnet several times.
Methods
plot()draws one figure of the bootstrap results per call, chosen withtype.
References
Epskamp, S., Borsboom, D., & Fried, E. I. (2018). Estimating psychological networks and their accuracy: A tutorial paper. Behavior Research Methods 50(1), 195-212. doi:10.3758/s13428-017-0862-1 (source of the CS-coefficient and of the case-dropping, edge-difference and centrality-difference procedures reproduced here.)
Examples
set.seed(1)
dat <- as.data.frame(matrix(rnorm(60), ncol = 3))
net <- build_network(dat, method = "glasso")
bg <- boot_glasso(net, iter = 10, cs_iter = 5, centrality = "strength")
# \donttest{
set.seed(42)
mat <- matrix(rnorm(60), ncol = 4)
colnames(mat) <- LETTERS[1:4]
net <- build_network(as.data.frame(mat), method = "glasso")
# iter = 20 keeps the example fast; a real analysis uses 1000 or more.
boot <- boot_glasso(net, iter = 20, cs_iter = 10, seed = 42,
centrality = c("strength", "expected_influence"))
print(boot)
#> GLASSO Bootstrap (20 iterations, 10 case-drop iterations)
#> Data: 15 x 4 | Alpha: 0.05 | Gamma: 0.50
#> Edges: 0/6 significant (CI excludes zero)
#> Mean inclusion probability: 0.34
#>
#> Centrality Stability (CS-coefficient):
#> strength: 0.00 [Unstable]
#> expected_influence: 0.00 [Unstable]
#>
#> Edge differences: 0/15 pairs significantly different
#> Timing: 1.0s (bootstrap: 0.6s, case-drop: 0.3s)
summary(boot, type = "edges")
#> edge weight ci_lower ci_upper inclusion
#> 1 A -- B 0 -0.11158199 0.2237159 0.35
#> 2 A -- C 0 -0.35185567 0.0000000 0.45
#> 3 B -- C 0 -0.30946900 0.2065199 0.25
#> 4 A -- D 0 0.00000000 0.3570903 0.50
#> 5 B -- D 0 -0.15048304 0.3105727 0.35
#> 6 C -- D 0 -0.03724162 0.1787669 0.15
# }