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:

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

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.

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:

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