psychnets

Clean-room, self-certifying estimation of cross-sectional psychometric network models in base R.

— by Mohammed Saqr

psychnets implements the principal cross-sectional estimators used in psychometric network analysis entirely in base R. The package provides correlation and partial-correlation networks, the EBIC-regularized Gaussian graphical model (graphical lasso), together with its nonparanormal and unregularized stepwise variants, information-filtering networks including the Triangulated Maximally Filtered Graph (TMFG) and Local–Global inverse covariance estimation, relative-importance networks, the Ising model for binary variables, and the mixed graphical model. Whereas these estimators are conventionally accessed through high-level R packages that delegate numerical optimization to compiled Fortran or C/C++ libraries, psychnets reimplements the complete estimation procedures directly in R. In particular, graphical lasso estimation is commonly performed through qgraph and bootnet, which invoke the Fortran implementation provided by glasso, while Ising and mixed graphical models are typically estimated through IsingFit and mgm, both of which rely on the compiled optimization routines of glmnet. psychnets invokes none of these packages or their underlying compiled numerical libraries. Its only package dependencies are the standard R distributions stats, parallel, graphics, and grDevices.

For fitted regularized optimization models, psychnets reports a numerical certificate in the form of the Karush–Kuhn–Tucker (KKT) residual associated with the objective defining the estimator. The KKT residual quantifies the degree to which the necessary first-order optimality conditions are satisfied and therefore provides a direct measure of convergence. Residual values approaching zero indicate that the numerical solution is effectively stationary with respect to the objective function. Because this diagnostic is computed directly from the fitted solution, its evaluation is independent of external optimization software and does not require comparison with reference implementations. Post-estimation transformations and methods without an applicable residual report an unavailable certificate rather than a successful one.

The implementation philosophy of psychnets is based on four complementary design principles. First, the estimation procedure is fully transparent, as both the statistical methodology and the numerical optimization algorithms are implemented explicitly in R, allowing every computational step to be inspected and reproduced without reference to opaque compiled libraries. Second, estimation is reproducible because convergence behaviour is determined by user-accessible numerical criteria rather than by implementation-specific tolerances embedded within precompiled binaries. Third, the package maintains a minimal dependency structure by avoiding external numerical libraries such as glasso, glmnet, qgraph, and Matrix, together with their associated compiled dependency chains, including Rcpp and RcppArmadillo. Finally, estimation is directly auditable because fitted optimization solutions are accompanied by an optimality certificate that quantifies its numerical accuracy with respect to the objective function being minimized. Consequently, the correctness of a fitted optimization can be assessed directly rather than inferred through agreement with an independent software implementation.

Because each optimization problem is solved to numerical stationarity and model selection is performed using the standard formulation of the Extended Bayesian Information Criterion (EBIC), network recovery reflects the theoretical properties of the estimator rather than artefacts of incomplete optimization. As a consequence, edge selection is not influenced by premature termination of the numerical algorithm, thereby avoiding the inclusion of edges that may arise solely from insufficient convergence of the underlying optimization procedure.

Validation uses simulated data with known generating models and published psychometric datasets. Agreement with reference packages is assessed using method-appropriate criteria: exact or near-numerical agreement where objective and solver conventions coincide, and support, sign, or structural agreement where penalty paths or diagonal conventions differ. For the EBIC graphical lasso, the comparison limit is determined by the convergence criterion of the glasso implementation used by qgraph, approximately (10^{-4}). psychnets solves its native optimization to tighter tolerances. If post-estimation thresholding changes a returned graph, certificate() reports NA for that graph and retains the fitted model's residual as $fit_kkt.

Installation

# from CRAN (once released)
install.packages("psychnets")

# development version
# install.packages("pak")
pak::pak("mohsaqr/psychnets")

A worked example

psychnets estimates an EBIC-regularized Gaussian graphical model from data or a correlation matrix and reports its certificate on printing. The example uses SRL_GPT, one of the self-regulated-learning datasets shipped with the package (five MSLQ constructs).

library(psychnets)

net <- ebic_glasso(SRL_GPT)   # EBIC graphical lasso of the five MSLQ constructs
net                           # edges, lambda, gamma, and the KKT residual
#> <psychnet> glasso network
#>   nodes: 5   edges: 10   (undirected)
#>   lambda: 0.00861   gamma: 0.5
#>   optimality (KKT residual): 2.21e-10

net_centralities(net)         # strength and expected influence, tidy
#>   node  strength expected_influence
#> 1  CSU 1.1984512         1.19845117
#> 2   IV 1.0012765         1.00127649
#> 3   SE 0.8492185         0.84921854
#> 4   SR 1.2314317         0.53172852
#> 5   TA 0.6082238        -0.09147935

The network is drawn through cograph::splot():

cograph::splot(net, layout = "spring", edge_labels = FALSE, legend = TRUE)

The certificate is available directly, so the distance of the fit from the unique optimum of its objective can be read without an external reference:

glasso_kkt(net$precision, net$cor_matrix, net$lambda)
#> [1] 2.213367e-10

Models and methods

The estimators, each fitted in base R and — where regularized — self-certified:

Verb	Model	Data
cor_network()	correlation network (with significance thresholding)	continuous
pcor_network()	partial-correlation network	continuous
ebic_glasso()	EBIC-regularized Gaussian graphical model (graphical lasso)	continuous
huge_network()	nonparanormal Gaussian graphical model	continuous
ggm_modselect()	unregularized stepwise Gaussian graphical model	continuous
tmfg_network()	Triangulated Maximally Filtered Graph	continuous
logo_network()	Local–Global sparse inverse covariance	continuous
relimp_network()	relative-importance network (LMG / Shapley)	continuous
ising_fit()	Ising model, L1-penalized	binary
ising_sampler()	Ising model, unregularized	binary
mgm_fit()	mixed graphical model	Gaussian + binary; multi-level categorical with native = FALSE
psychnet()	unified front door routing all of the above	—

The framework verbs operate on any fitted network, and on event logs and grouped data through psychnet():

Verb	Purpose
net_centralities(), net_bridge(), net_edge_betweenness()	node, bridge, and edge centrality
net_clustering(), net_smallworld()	weighted clustering coefficients and the small-world index
net_predict()	node predictability (variance explained; classification accuracy)
net_boot(), difference_test()	bootstrapped accuracy and within-network difference tests
net_stability(), net_casedrop_reliability(), net_split_reliability()	case-dropping stability and split-half reliability
net_compare()	the permutation Network Comparison Test
redundancy(), net_aggregate()	redundant-node detection and community aggregation

psychnet() additionally constructs networks directly from event logs — one row per action — computing action frequencies and separating within- from between-actor variation, and estimates a separate network per group on request. Every fitted network inherits the cograph plotting classes, and each result object carries a base-graphics plot() method.

Node centrality plots directly from its result object:

plot(net_centralities(net))

net_boot() resamples the data, re-estimates, and returns bootstrapped edge-weight confidence intervals; edges whose interval excludes zero are drawn in the accent colour:

set.seed(1)
plot(net_boot(SRL_GPT, method = "glasso", n_boot = 500), type = "edges")

Self-certification

psychnets treats correctness as a measured quantity rather than as agreement with a second implementation. For a Gaussian graphical model, glasso_kkt() returns the stationarity residual of the graphical-lasso objective; because that objective is strictly convex its minimizer is unique, so a near-zero residual certifies the global optimum with no reference solver involved. The nodewise Ising and mixed graphical models are certified analogously through the penalized-likelihood score residual. External packages (qgraph, IsingFit, mgm, bootnet) serve as cross-checks at independent-solver precision, never as the definition of correct.

Validation

psychnets is checked against the established reference packages in two ways, both reproducible from a fixed set of package versions.

Estimator equivalence versus the reference packages

Each model is fitted by psychnets and its reference package on the same data. The table reports the observed comparison criterion; it is not a claim that every independent implementation returns numerically identical weights.

psychnets estimator	Reference package	Data	Observed difference
ebic_glasso()	qgraph::EBICglasso 1.9.8	AR(1) chain, n = 1000, p = 8	edge set identical; max |Δ| = 2.2e-06; KKT = 1.5e-10
ising_fit()	IsingFit::IsingFit 0.4	AR(1) latent, n = 2000, p = 6, binarized	edge set identical; max |Δ| = 4.6e-03; threshold r = 1.000
mgm_fit()	mgm::mgm 1.2.15	mixed Gaussian + binary, n = 3000, p = 4	edge set identical; max |Δ| = 1.6e-03; KKT = 1.1e-09
cor_auto()	psych::polychoric / qgraph::cor_auto	four-level Likert, n = 1000, p = 4	max |Δ| = 2.0e-05 (psych), 1.7e-07 (qgraph)
.pbivnorm() (bivariate normal CDF)	mvtnorm::pmvnorm 1.2	five (h, k, ρ) points	max |Δ| = 5.6e-17

Validation databases (published instruments)

On real questionnaire and ability data the psychnets EBIC graphical lasso reproduces the qgraph edge set exactly — structure agreement equals 1 on every instrument, with a largest edge-weight difference of 0.008 — and the Ising model matches IsingFit on binary batteries. The instruments, all loaded from installed CRAN packages so the comparison downloads nothing:

Instrument	Source	Items	n	Reference	max |Δ|
qgraph::big5	Dolan, Oort, Stoel & Wicherts (2009)	240	500	qgraph	3.6e-05
psych::bfi	Revelle, Wilt & Rosenthal (2010)	25	2760	qgraph	3e-06
psych::sat.act	Revelle (psych)	6	700	qgraph	2e-06
psychTools::msq	Revelle & Anderson (1998)	50	3876	qgraph	1.2e-05
psychTools::epi.bfi	Eysenck & Eysenck (1964)	13	231	qgraph	8.0e-03
psychTools::epi	Eysenck Personality Inventory	50	3476	qgraph	6e-06
psychTools::sai	Spielberger State Anxiety	22	5282	qgraph	3.5e-05
psychTools::tai	Spielberger Trait Anxiety	21	3016	qgraph	7e-06
psychTools::spi	Condon (2018), SAPA Inventory	50	4000	qgraph	1.6e-05
psychTools::blot	Bond’s Logical Operations Test	35	150	qgraph	0
mgm::Fried2015	Fried et al. (2015)	11	515	qgraph	8e-06
mgm::PTSD_data	McNally et al. (2015)	6	344	qgraph	1.9e-05
mgm::B5MS	Haslbeck & Waldorp (mgm)	5	500	qgraph	0
mgm::symptom_data	Haslbeck & Waldorp (mgm)	48	1476	qgraph	1.5e-05
NetworkToolbox::neoOpen	Christensen, Cotter & Silvia (2019)	48	802	qgraph	4e-06
networktools::depression	Jones (networktools)	9	1000	qgraph	6.5e-05
networktools::social	Jones (networktools)	16	350	qgraph	7e-06
EGAnet::optimism	Golino & Christensen (EGAnet)	10	272	qgraph	6e-06
EGAnet::intelligenceBattery	Golino & Christensen (EGAnet)	50	1152	qgraph	2.2e-05
psychTools::ability	Revelle; ICAR ability items	16	1248	IsingFit	5.9e-02
psychTools::iqitems	Condon & Revelle; ICAR	11	1523	IsingFit	1.2e-02

Where the truth is known — data drawn from a known sparse precision matrix — the psychnets and qgraph estimators recover the generating structure at the same F-measure. The full derivation, the worked graphical-lasso case, and the complete tables are given in the package’s technical report.

Learn more

• Articles — worked tutorials for the Gaussian graphical, information-filtering, Ising, mixed, and relative-importance models, network reliability, and building networks from event data.
• Website — https://pak.dynasite.org/psychnets
• Source — https://github.com/mohsaqr/psychnets