estimateNetwork: Estimate a network structure

In bootnet: Bootstrap Methods for Various Network Estimation Routines

Estimate a network structure

Description

This function allows for flexible estimation of a network structure using various R packages and model frameworks. This is typically done by using one of the default sets. See details for manual specification. See also Epskamp, Borsboom and Fried (2016) for more details. IMPORTANT: THE ESTIMATOR FUNCTIONS (e.g., fun = bootnet_pcor) ARE NOT INTENDED TO BE USED MANUALY (see details).

Usage

estimateNetwork(data, default = c("none", "EBICglasso", "pcor",
                 "IsingFit", "IsingSampler", "huge", "adalasso", "mgm",
                 "relimp", "cor", "TMFG", "ggmModSelect", "LoGo",
                 "graphicalVAR", "piecewiseIsing", "SVAR_lavaan", "GGMncv"),
                 fun, labels, verbose = TRUE, .dots = list(), weighted = TRUE,
                 signed = TRUE, directed, datatype, checkNumeric = FALSE, ...,
                 .input, memorysaver = FALSE)

bootnet_EBICglasso(data, tuning = 0.5, corMethod = c("cor", "cov",
                    "cor_auto", "npn", "spearman"), missing =
                    c("pairwise", "listwise", "fiml", "stop"), sampleSize
                    = c("pairwise_average", "maximum", "minimum",
                    "pairwise_maximum", "pairwise_minimum",
                    "pairwise_average_v1.5", "pairwise_maximum_v1.5",
                    "pairwise_minimum_v1.5"), verbose = TRUE, corArgs =
                    list(), refit = FALSE, principalDirection = FALSE,
                    lambda.min.ratio = 0.01, nlambda = 100, threshold =
                    FALSE, unlock = FALSE, nonPositiveDefinite = c("stop",
                    "continue"), transform = c("none", "rank",
                    "quantile"), ...)

bootnet_pcor(data, corMethod = c("cor", "cov", "cor_auto", "npn",
                    "spearman"), missing = c("pairwise", "listwise",
                    "fiml", "stop"), sampleSize = c("pairwise_average",
                    "maximum", "minimum", "pairwise_maximum",
                    "pairwise_minimum", "pairwise_average_v1.5",
                    "pairwise_maximum_v1.5", "pairwise_minimum_v1.5"),
                    verbose = TRUE, corArgs = list(), threshold = 0, alpha
                    = 0.05, adjacency, principalDirection = FALSE, unlock
                    = FALSE, nonPositiveDefinite = c("stop", "continue"),
                    transform = c("none", "rank", "quantile"))

bootnet_cor(data, corMethod = c("cor", "cov", "cor_auto", "npn",
                    "spearman"), missing = c("pairwise", "listwise",
                    "fiml", "stop"), sampleSize = c("pairwise_average",
                    "maximum", "minimum", "pairwise_maximum",
                    "pairwise_minimum", "pairwise_average_v1.5",
                    "pairwise_maximum_v1.5", "pairwise_minimum_v1.5"),
                    verbose = TRUE, corArgs = list(), threshold = 0, alpha
                    = 0.05, principalDirection = FALSE, unlock = FALSE,
                    nonPositiveDefinite = c("stop", "continue"), transform
                    = c("none", "rank", "quantile"))

bootnet_IsingFit(data, tuning = 0.25, missing = c("listwise", "stop"),
                    verbose = TRUE, rule = c("AND", "OR"), split =
                    "median", principalDirection = FALSE,
                    min_sum = -Inf, unlock = FALSE)

bootnet_IsingSampler(data, missing = c("listwise", "stop"), verbose = TRUE,
                    split = "median", method = c("uni", "ll", "pl", "bi"),
                    principalDirection = FALSE, unlock = FALSE, threshold
                    = FALSE, alpha = 0.01, min_sum = -Inf, rule = c("AND",
                    "OR"))

bootnet_adalasso(data, missing = c("listwise", "stop"), verbose = TRUE,
                   nFolds = 10, principalDirection = FALSE, unlock =
                   FALSE, transform = c("none", "rank", "quantile"), ...)

bootnet_huge(data, tuning = 0.5, missing = c("listwise", "stop"),
                   verbose = TRUE, npn = TRUE, criterion = c("ebic",
                   "ric", "stars"), principalDirection = FALSE,
                   lambda.min.ratio = 0.01, nlambda = 100, unlock =
                   FALSE, transform = c("none", "rank", "quantile"), ...)

bootnet_mgm(data, type, level, tuning = 0.25, missing =
                   c("listwise", "stop"), verbose = TRUE, criterion =
                   c("EBIC", "CV"), nFolds = 10, order = 2, rule =
                   c("AND", "OR"), binarySign, unlock = FALSE, transform
                   = c("none", "rank", "quantile"), ...)

bootnet_relimp(data, normalized = TRUE, type = "lmg",
                   structureDefault = c("none", "custom", "EBICglasso",
                   "pcor", "IsingFit", "IsingSampler", "huge",
                   "adalasso", "mgm", "cor", "TMFG", "ggmModSelect",
                   "LoGo"), missing = c("listwise", "stop"), ..., verbose
                   = TRUE, threshold = 0, unlock = FALSE, transform =
                   c("none", "rank", "quantile"))

bootnet_TMFG(data, graphType = c("cor", "pcor"), corMethod =
                   c("cor", "cov", "cor", "npn", "cor_auto"), missing =
                   c("pairwise", "listwise", "fiml", "stop"), verbose =
                   TRUE, corArgs = list(), principalDirection = FALSE,
                   unlock = FALSE, transform = c("none", "rank",
                   "quantile"), ...)

bootnet_LoGo(data, corMethod = c("cor", "cov", "cor", "npn",
                   "cor_auto"), missing = c("pairwise", "listwise",
                   "fiml", "stop"), verbose = TRUE, corArgs = list(),
                   principalDirection = FALSE, unlock = FALSE, transform
                   = c("none", "rank", "quantile"), ...)

bootnet_graphicalVAR(data, tuning = 0.5, verbose = TRUE, principalDirection
                   = FALSE, missing = c("listwise", "stop"), unlock =
                   FALSE, transform = c("none", "rank", "quantile"), ...)

bootnet_ggmModSelect(data, tuning = 0, corMethod = c("cor", "cov",
                    "cor_auto", "npn", "spearman"), missing =
                    c("pairwise", "listwise", "fiml", "stop"), sampleSize
                    = c("pairwise_average", "maximum", "minimum",
                    "pairwise_maximum", "pairwise_minimum",
                    "pairwise_average_v1.5", "pairwise_maximum_v1.5",
                    "pairwise_minimum_v1.5"), verbose = TRUE, corArgs =
                    list(), principalDirection = FALSE, start =
                    c("glasso", "empty", "full"), stepwise = TRUE, nCores
                    = 1, unlock = FALSE, nonPositiveDefinite = c("stop",
                    "continue"), transform = c("none", "rank",
                    "quantile"), ...)

bootnet_piecewiseIsing(data, cutoff, missing = c("listwise", "stop"), verbose
                    = TRUE, IsingDefault = c("IsingSampler", "IsingFit",
                    "custom"), zeroThreshold = 1, minimalN = ncol(data) +
                    1, unlock = FALSE, ...)

bootnet_SVAR_lavaan(data, verbose = TRUE, principalDirection = FALSE,
                   missing = c("listwise", "stop"), criterion = "bic",
                   eqThreshold = 1e-04, tempWhitelist, tempBlacklist,
                   contWhitelist, contBlacklist, minimalModInd = 10,
                   unlock = FALSE, transform = c("none", "rank",
                   "quantile"), ...)

bootnet_GGMncv(data, penalty = c("atan", "selo", "exp", "log",
                    "sica", "scad", "mcp", "lasso"), corMethod = c("cor",
                    "cov", "cor_auto", "npn", "spearman"), missing =
                    c("pairwise", "listwise", "fiml", "stop"), sampleSize
                    = c("pairwise_average", "maximum", "minimum",
                    "pairwise_maximum", "pairwise_minimum",
                    "pairwise_average_v1.5", "pairwise_maximum_v1.5",
                    "pairwise_minimum_v1.5"), verbose = TRUE, corArgs =
                    list(), principalDirection = FALSE, unlock = FALSE,
                    nonPositiveDefinite = c("stop", "continue"), transform
                    = c("none", "rank", "quantile"), ...)

Arguments

data	A data frame or matrix containing the raw data. Must be numeric, integer or ordered factors.
default	A string indicating the method to use. Specifying a default sets default values to prepFun, prepArgs, estFun, estArgs, graphFun, graphArgs, intFun and intArgs. Setting a default can be omitted but that does require specifying all above mentioned arguments. Current options are: "EBICglasso" Gaussian Markov random field estimation using graphical LASSO and extended Bayesian information criterion to select optimal regularization parameter. Using EBICglasso from the qgraph package. Calls bootnet_EBICglasso. "IsingFit" Ising model estimation using LASSO regularized nodewise logistic regression and extended Bayesian information criterion to select optimal regularization parameter. Using IsingFit from the IsingFit package. Calls bootnet_IsingFit. "IsingSampler" Calls the EstimateIsing function from the IsingSampler package. "pcor" Partial correlation network (non-regularized Gaussian Markov random field), using cor2pcor from the corpcor package. Calls bootnet_pcor. "cor" Correlation network. "huge" Uses EBIC model selection of GGM networks estimated via the glasso algorithm as implemented in the huge package (as opposed to glasso and qgraph packages used in default = "EBICglasso"). Uses nonparanormal transformation in preparing the data and does not use polychoric correlations. Calls bootnet_huge. "mgm" Estimates a Mixed graphical model by using the the mgm (or mgmfit in older versions) function of the mgm package. Calls bootnet_mgm. "TMFG" Estimates a Triangulated Maximally Filtered Graph, using the function TMFG of the NetworkToolbox package. Calls bootnet_TMFG. Note that this estimates a *correlation network* by default (use the 'graphType' argument to estimate a partial correlation network instead). "LoGo" Estimates a Local/Global Sparse Inverse Covariance Matrix, using the function LoGo of the NetworkToolbox package. Calls bootnet_LoGo. "relimp" Estimates a (directed) relative importance network, using the function 'calc.relimp' of the 'relaimpo' package. The 'structureDefault' argument can be used to use a different default set for estimating the structure of the graph. Calls bootnet_relimp. "ggmModSelect" Estimates an unregularized GGM using the glasso algorithm and stepwise model selection, using the 'ggmModSelect' function from the qgraph package. Calls bootnet_ggmModSelect. "graphicalVAR" Estimates a graphical VAR model using the graphicalVAR package. This results in two networks which can be plotted using the 'graph' argument in the plot method. Calls bootnet_graphicalVAR. See details section for a more detailed description.
fun	A custom estimation function, when no default set is used. This must be a function that takes the data as input (first argument) and returns either a weights matrix or a list containing the elements "graph" for the weights matrix, "intercepts" for the intercepts (optional) and "results" for the full estimation results (optional).
tuning	EBIC tuning parameter, used in 'EBICglasso', 'IsingFit', 'huge', 'mgm' and 'ggmModSelect' default sets. Note that the default value differs: 'EBICglasso', 'huge' and 'mgm' use 0.5, 'IsingFit' uses 0.25 and 'ggmModSelect uses 0.
corMethod	Correlation method, used in 'EBICglasso' and 'pcor' default sets. "cor_auto" uses cor_auto for polychoric and polyserial correlations, "cov" uses the cov function for covariances, "cor" will use the cor function for correlations and "npn" will apply the nonparanormal transformation (via huge.npn) and then compute correlations.
missing	How to handle missing data? "pairwise" for pairwise deletion, "listwise" for listwise deletion, "fiml" for full-information maximum likelihood and "stop" to stop with an error.
sampleSize	How will sample size be computed in EBICglasso default set? The default "pairwise_average" will set the sample size to the average of sample sizes used for each individual correlation. Other options are "pairwise_maximum" (largest sample sized used for each individual correlation), "pairwise_minimum" (smallest sample sized used for each individual correlation), "maximum" (takes total number of rows including rows with NA), and "minimum" (takes total number of rows that contain no NA). The arguments "pairwise_average_v1.5", "pairwise_minimum_v1.5", and "pairwise_maximum_v1.5" can be used to mimic bootnet's behavior in version 1.5 and earlier (which also computed the sample size based on the sample sizes for the variances).
corArgs	A list with arguments for the function used defined by corMethod.
threshold	Thresholding to use in partial correlation networks. Can be a fixed number to threshold all absolute edges below this value, 'locfdr' for local FDR, or any option corresponding to adjustments in corr.p ('none', 'sig', 'holm', 'hochberg', 'hommel', 'bonferroni', 'BH', 'BY' or 'fdr')). Can also be used for default = "IsingSampler" but can only be set to a logical enabling or disabling significance thresholding.
refit	Logical used in EBICglasso default set: should the estimated model structure be refitted without LASSO regularization?
rule	The rule to use to select an edge in nodewise estimation. "AND" to only select in edge if both regression coefficients are nonzero and "OR" if only one is nonzero. Used in 'IsingFit' and 'mgm' default sets.
split	A function or character string ("median" or "mean") indicating how to binarize values when estimating an Ising model.
method	The estimation method used in the IsingSampler default set (see EstimateIsing).
npn	Logical, should nonparanormal be used in huge default set?
criterion	The criterion used in model selection. "ebic", "ric" or "stars" in the huge default set or "EBIC" or "CV" in the mgm default set.
nFolds	Number of folds used in k-fold cross-validation.
type	For mgm, see mgm or mgmfit; for relative importance networks, see calc.relimp
level	See mgm. Automatically set if not assigned.
order	Order up until including which interactions are included in the model. See mgm. Automatically set if not assigned.
binarySign	See mgm. Automatically set if not assigned.
normalized	Should normalized relative importance be used in relative importance networks?
structureDefault	In relative importance networks, default set used to compute the graph structure. Any other arguments used (using ...) are sent to the graph estimator function as well.
graphType	"cor" to estimate a correlation network and "pcor" to estimate a partial correlation network (GGM)
alpha	Significance level to test at.
principalDirection	Rescales variables according to the sign of the first eigen-vector. This will lead to most correlations to be positive (positive manifold), leading to negative edges to be substantively interpretable.
stepwise	Logical indicating if 'ggmModSelect' should use stepwise estimation.
start	See ggmModSelect
labels	A character vector containing the node labels. If omitted the column names of the data are used.
verbose	Logical, currently only used when default = "EBICglasso" in the cor_auto function.
weighted	Logical, should the analyzed network be weighted?
signed	Logical, should the analyzed network be signed?
directed	Logical, is the analyzed network directed? Usually does not have to be set and is detected automatically.
datatype	"normal" if the data argument is a data frame, or "graphicalVAR" if the data argument is a data list that can be used as input to the graphicalVAR package.
checkNumeric	Logical: should the data be checked to be numeric?
lambda.min.ratio	Minimal lambda ratio (LASSO tuning parameter)
nlambda	Number of LASSO tuning parameters to test
nCores	Number of cores to use in estimating networks
.dots	A list of arguments used in the estimation function set by a default set or by the fun argument.
...	A list of arguments used in the estimation function set by a default set or by the fun argument.
.input	Used internally in the bootnet function. Do not use.
memorysaver	Logical. If TRUE attempts to save memory (RAM) by removing some objects from the output. Used by bootnet by default for bootstraps.
cutoff	Cutoff score for sum-score to condition on when using default = "piecewiseIsing". This is *experimental*!
IsingDefault	Default set for Ising model structure estimation in piecewise Ising estimation. This is *experimental*!
zeroThreshold	Used in piecewise Ising estimation. Proportion of edges needed to be exactly 0 in pieces to set edge to zero in final network. This is *experimental*!
minimalN	Used in piecewise Ising estimation. Minimal sample sizes needed in piece estimation. This is *experimental*!
eqThreshold	Used in SVAR_lavaan estimation (stepup SVAR estimation). This is *experimental*! Maximum difference in criterion to decide if two models are equivalent (and select one at random).
tempWhitelist	Used in SVAR_lavaan estimation (step up SVAR estimation). This is *experimental*! Matrix with edges to be whitelisted in the temporal model. The matrix should contain two columns and a row for each edge. The elements should be characters indicating the variable names of each edge (from, to).
tempBlacklist	Used in SVAR_lavaan estimation (step up SVAR estimation). This is *experimental*! Matrix with edges to be blacklisted in the temporal model. The matrix should contain two columns and a row for each edge. The elements should be characters indicating the variable names of each edge (from, to).
contWhitelist	Used in SVAR_lavaan estimation (step up SVAR estimation). This is *experimental*! Matrix with edges to be whitelisted in the contemporaneous model. The matrix should contain two columns and a row for each edge. The elements should be characters indicating the variable names of each edge (from, to).
contBlacklist	Used in SVAR_lavaan estimation (step up SVAR estimation). This is *experimental*! Matrix with edges to be blacklisted in the contemporaneous model. The matrix should contain two columns and a row for each edge. The elements should be characters indicating the variable names of each edge (from, to).
minimalModInd	Minimal modification index to consider when adding parameters in SVAR search.
adjacency	An 'adjacency' matrix indicating the graph structure (zeroes indicate a missing edge).
nonPositiveDefinite	Set to "stop" to stop with an error when the input matrix is not positive definite, and to "continue" (old behavior) to continue anyway.
unlock	Set to TRUE to not result in a standard error. This is to prevent using the inner functions seperatly (see details below).
transform	Should data be transformed before estimate the network? "rank" will call rank_transformation and "quantile"" will call quantile_transformation.
penalty	Penalty to use in the GGMncv methods.
min_sum	The minimum sum score that is artifically possible in the dataset. Defaults to -Inf. Set this only if you know a lower sum score is not possible in the data, for example due to selection bias.
AND	Logical, should an AND-rule (both regressions need to be significant) or OR-rule (one of the regressions needs to be significant) be used?

Details

The user can manually specify an estimation method by assigning a custom function to the 'fun' argument. This function must take data as input and output an estimated network. Fhe functions bootnet_ correspond to the functions used when using default sets. E.g, default = "pcor" sets fun = bootnet_pcor. As the ... leads to any argument to estimateNetwork to be passed to the estimator function, the arguments described above in these estimator functions can be used for the appropriate default method. For example, if default = "pcor", the arguments of fun = bootnet_pcor can be used in estimateNetwork. IMPORTANT NOTE: DO NOT USE THE ESTIMATOR FUNCTIONS (e.g., fun = bootnet_pcor) YOURSELF, THEY ARE ONLY INCLUDED HERE TO SHOW WHICH ARGUMENTS YOU CAN USE IN estimateNetwork.

Author(s)

Sacha Epskamp <[e-mail]>

References

Epskamp, S., Borsboom, D., & Fried, E. I. (2016). Estimating psychological networks and their accuracy: a tutorial paper. arXiv preprint, arXiv:1604.08462.

See Also

bootnet

Examples

# BFI Extraversion data from psychTools package:
library("psychTools")
data(bfi)
bfiSub <- bfi[,1:25]

# Estimate network:
Network <- estimateNetwork(bfiSub, default = "EBICglasso")

## Not run: 
# Some pointers:
print(Network)

# Estimated network:
plot(Network, layout = 'spring')

# Centrality indices:
library("qgraph")
centralityPlot(Network)

# BIC model selection:
Network_BIC <- estimateNetwork(bfiSub, default = "EBICglasso", tuning = 0)

# Ising model:
Network_BIC <- estimateNetwork(bfiSub, default = "IsingFit")

## End(Not run)

bootnet documentation built on May 29, 2024, 8:38 a.m.