psychnets

Written by Mohammed Saqr and Sonsoles López-Pernas

Provides clean-room implementations for estimating psychometric network models, including correlation and partial-correlation networks, Gaussian graphical models with extended Bayesian information criterion (EBIC) regularization, nonparanormal and stepwise selection variants, information-filtering networks (the triangulated maximally filtered graph and the local-global inverse covariance), relative-importance networks, and Ising and mixed graphical models (doi:10.3758/s13428-017-0862-1; doi:10.1007/978-3-031-54464-4_19). All methods are implemented from first principles in base R without compiled dependencies and return consistent, tidy outputs. Functions are designed to be transparent and report optimization diagnostics where applicable. For Gaussian graphical models, the graphical lasso stationarity (Karush-Kuhn-Tucker) residual quantifies the deviation of the estimated solution from the optimum of the corresponding convex optimization problem.

Overview

psychnets estimates psychometric networks and assesses how far they can be trusted. A psychometric network represents variables such as questionnaire items, symptoms or behaviours as nodes and the associations between them as edges; in a partial-correlation network an edge is the association between two variables that remains once all the others are taken into account (Epskamp & Fried, 2018). The network shows which variables are directly related, which hold a central position, and how the structure differs between groups. The package estimates Gaussian graphical models (regularized, unregularized and nonparanormal), information-filtering and relative-importance networks, Ising models for binary items, mixed graphical models, and the panel graphical VAR for a few waves of panel data. Each network can be bootstrapped, tested for the stability of its centralities and the reliability of its edges, and compared between groups.

Every estimator is written in base R. A regularized fit reports how far it is from the optimum of its objective (certificate()), so the network can be checked without a second solver.

Vignettes and guides

Vignettes

Guides

Installation

# from CRAN
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)

SRL_GPT regulation network

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:

certificate(net)
#>   method  certificate kind certified
#> 1 glasso 2.213347e-10  kkt      TRUE

Models and methods

The estimators, each fitted in base R; the regularized ones report a certificate (certificate()):

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
panel_gvar() panel graphical VAR: temporal, contemporaneous, and between-person networks (stationary random-intercept VAR(1), maximum likelihood; every edge with SE and p-value by default; optional Wald pruning + step-up, or EBIC lasso) continuous panel data, 3+ waves
psychnet() unified front door routing the cross-sectional estimators 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))

node centrality

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")

bootstrapped edge weights

Implementation and certificates

Every estimator is written in base R. The only package dependencies are stats, parallel, graphics and grDevices; the compiled solvers of glasso and glmnet, which qgraph, bootnet, IsingFit and mgm call, are not used.

A fitted network carries its own check. For a Gaussian graphical model, certificate() reports (and glasso_kkt() computes) the stationarity residual of the graphical-lasso objective; because that objective is strictly convex its minimizer is unique, so a near-zero residual shows that the network is the optimum, with no reference solver involved. The nodewise Ising and mixed graphical models are checked the same way through the penalized-likelihood score residual. Because each fit is solved to stationarity before the EBIC is computed, no edge is selected only because the optimization stopped early. A network changed after fitting, by a threshold or by pruning, reports NA, and printing it shows the residual of the fit before the change. External packages (qgraph, IsingFit, mgm, bootnet) serve as cross-checks, not as the definition of a correct fit.

Validation

psychnets is checked against the established reference packages in two ways, both reproducible from a fixed set of package versions. For the EBIC graphical lasso, the comparison limit is set by the convergence criterion of the glasso implementation used by qgraph, about 1e-4; psychnets solves its own optimization to tighter tolerances.

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
panel_gvar() psychonetrics::panelgvar 0.17.8 (+ prune; stepup supports also identical) stationary panel, n = 400, p = 3, 4 waves pruned edge set identical; max |Δ| = 1.4e-04 (psychonetrics’ stopping tolerance: its gradient 6.8e-04, ours 3.0e-13); psychnets reaches a lower ML objective (by 5.7e-08)
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