|
L0ggmSmooth
|
This package estimates Gaussian graphical models (GGMs) using regularization penalties that approximate the
The package implements five continuous, differentiable approximations to the
The package also provides simulation tools for generating GGM data with realistic psychometric network structure. Two topology generators are included: simulate_smallworld() produces small-world networks via degree-weighted Watts-Strogatz rewiring, and simulate_sbm() produces community-structured networks via a stochastic block model. Both are calibrated to edge weight distributions empirically observed across 194 psychometric networks (Huth et al., 2025) through weibull_parameters(), a Seemingly Unrelated Regression model that predicts Weibull shape and scale from network size, sample size, and signal-to-noise ratio.
# Ensure {remotes} is installed
if(!"remotes" %in% row.names(installed.packages())){
install.packages("remotes")
}
# Install from GitHub
remotes::install_github("AlexChristensen/L0ggm")# Load package
library(L0ggm)
# Simulate smallworld data
basic_smallworld <- simulate_smallworld(
nodes = 20, # 20 nodes in the network
density = 0.30, # moderate initial lattice connectivity
rewire = 0.20, # 20% rewiring probability
sample_size = 1000 # number of cases = 1000
)
# Estimate network with default adaptive Weibull penalty
# with full LLA (iterate to convergence; recommended)
weibull_network <- network_estimation(data = basic_smallworld$data, LLA = TRUE)
# Get full output (network, precision matrix, selected lambda, etc.)
weibull_full <- network_estimation(data = basic_smallworld$data, network_only = FALSE)
# Use the Arctangent penalty
atan_network <- network_estimation(
data = basic_smallworld$data, penalty = "atan", LLA = TRUE
)
# Use the EXP penalty with fixed (non-adaptive) gamma
exp_network <- network_estimation(
data = basic_smallworld$data, penalty = "exp", LLA = TRUE, adaptive = FALSE
)Estimating a GGM requires finding a sparse precision matrix
where
The graphical LASSO (GLASSO; Friedman, Hastie, & Tibshirani, 2008) uses an
However,
The
Unlike
From $L_0$ to Tractable Approximations
Direct
{L0ggm} addresses this through continuous smooth approximations
-
$\rho(0; \lambda, \gamma) = 0$ — zero penalty at zero -
$\rho(x; \lambda, \gamma) \to \lambda$ as$|x| \to \infty$ — bounded, like$L_0$ -
$\rho(x; \lambda, \gamma) \to \lambda \cdot \mathbf{1}(x \neq 0)$ as$\gamma \to 0$ — converges to the$L_0$ step function
Because the approximations are differentiable, their derivatives can be used as adaptive, element-wise GLASSO penalty weights via the Local Linear Approximation (LLA; Fan & Li, 2001; Zou & Li, 2008). At iteration
which reduces each step to a re-weighted GLASSO problem. A single LLA pass (the default) is extremely fast and produces estimates with strong theoretical guarantees (Zou & Li, 2008). Full iterative LLA to convergence is also available via LLA = TRUE.
The five penalties available in {L0ggm} are:
| Penalty | Formula | |
|---|---|---|
"atan" (Wang & Zhu, 2016) |
0.01 | |
"exp" (Wang, Fan, & Zhu, 2018) |
0.01 | |
"gumbel" |
0.01 | |
"log" (Candes, Wakin, & Boyd, 2008) |
0.10 | |
"weibull" (default)
|
|
0.01 |
Note. The Gumbel penalty subtracts
Figure 1.
The Weibull Penalty
What makes it different
The Weibull penalty introduces a shape parameter
-
$k = 1$ : reduces exactly to the EXP penalty -
$k < 1$ : the penalty becomes less concave than exponential, with a wider rise near the origin and slower convergence to$\lambda$ — moving away from the$L_0$ step function (see Figure 1) -
$k \sim 0.40$ : approximates the Atan penalty -
$k > 1$ : the penalty becomes more concave than exponential, with a sharper threshold near the scale — moving closer to the$L_0$ step function
This variation in
Adaptive parameter estimation
When adaptive = TRUE (the default), both the shape
Step 1 — Fit Weibull to empirical partial correlations. Let
Step 2 — Set adaptive scale. The scale parameter
This is simply the Weibull quantile function evaluated at
The choice of the 10th percentile is grounded in a concrete calibration anchor. In practice, the Weibull MLE of absolute partial correlations tends to produce shape estimates near
This matches
The derivative used in the LLA is defined piecewise to ensure the penalty weight is always non-increasing in
where
Distributional foundations and extreme value theory
The EXP, Weibull, and Gumbel penalties are not arbitrary constructions — they form a mathematically unified family rooted in extreme value theory. The table below shows each penalty alongside its LLA derivative, which reveals the distributional structure underlying each:
| Distribution | Penalty (CDF) | Derivative (PDF) |
|---|---|---|
| Exponential | ||
| Weibull | ||
| Weibull |
||
| Gumbel |
||
| Gumbel |
The Weibull as the general case. The EXP penalty is the exact special case
The Gumbel–Weibull connection. Less obviously, the Gumbel and Weibull are also deeply related. The table shows that the Gumbel survival function
Generalized extreme value (GEV) distribution. The reason these distributions co-occur is the Fisher–Tippett–Gnedenko theorem (Fisher & Tippett, 1928; Gnedenko, 1943): the normalized maximum of
The tail index
-
$\xi = 0$ (Gumbel, Type I): the limit of exponential-class tails;$G(x) = \exp\left(-e^{-(x-\mu)/\sigma}\right)$ -
$\xi > 0$ (Fréchet, Type II): heavy-tailed, unbounded support -
$\xi < 0$ (Weibull, Type III): bounded support, arising from distributions with a finite right endpoint
Only Type I (Gumbel) and Type III (Weibull) are used as penalties in {L0ggm}. This is not coincidental: these are precisely the two GEV types whose CDFs are bounded above and approach 1 as
Why extreme value CDFs are ideal
The Weibull CDF in particular describes the distribution of the minimum of a large sample from distributions with polynomial density near zero. Because partial correlations are bounded in
The same structure governs the LLA derivative. For
{L0ggm} provides two functions for generating GGM data with realistic psychometric network structure. Both are calibrated to edge weight distributions observed across 194 empirical psychometric networks (Huth et al., 2025) via weibull_parameters(), with shared support for skewed data generation, positive-definiteness conditioning, and reproducible rejection diagnostics.
simulate_smallworld() — Small-world network structure
Generates GGM data from a small-world topology via a three-stage process closely aligned with empirical psychometric network properties.
Stage 1 — Ring lattice. A ring lattice is constructed with neighbors + 1 nearest-neighbor connections per node, where neighbors is derived from nodes and density. The extra neighbor ensures the lattice always has more edges than the target, guaranteeing pruning can proceed.
Stage 2 — Pruning. The lattice is randomly pruned to the target density by removing edges uniformly at random while maintaining graph connectivity. This creates degree heterogeneity before any rewiring, providing a non-uniform prior for the next stage.
Stage 3 — Degree-weighted rewiring. Each edge is independently rewired with probability rewire. Unlike standard Watts-Strogatz, the new endpoint is selected proportionally to
Edge weights. Retained lattice edges receive weights by neighbor-distance priority (nearer = stronger); rewired edges receive lowest priority. Absolute weights are drawn from a Weibull distribution via weibull_parameters().
| Argument | Description |
|---|---|
nodes |
Number of nodes (8–54 recommended) |
density |
Target edge density after pruning |
rewire |
Rewiring probability (small-world regime: ~0.01–0.30) |
snr |
Signal-to-noise ratio 1
|
negative_proportion |
Fraction of edges signed negative; default drawn from empirical distribution |
sample_size |
Number of observations to generate |
skew / skew_range
|
Per-variable skew in 0
|
Returns: a named list with data, parameters (including omega smallworldness), population (R, Omega), and convergence.
result <- simulate_smallworld(
nodes = 20, density = 0.30, rewire = 0.20, sample_size = 500
)simulate_sbm() — Stochastic block model structure
Generates GGM data with explicit community (block) structure, where edge density is controlled separately within and between communities via a blocks × blocks density matrix.
Structure. Nodes are partitioned into blocks communities of size nodes (scalar or per-block vector). For each pair of communities density_matrix[i, j]. The resulting graph is required to be connected; disconnected draws are rejected and resampled.
Edge weights and diffusion. Absolute weights are drawn from a Weibull distribution via weibull_parameters(). The diffusion parameter controls the minimum fraction of high-weight edges reserved for within-community positions: 1 - diffusion of within-community slots are filled from the top-ranked weight draws, with the remaining slots drawn randomly. Because random draws can also land within communities by chance, the actual within-community weight advantage typically exceeds 1 - diffusion. Newman-Girvan modularity parameters) summarizes the community contrast actually achieved.
Between-community sign. Each between-community edge is independently signed negative with probability negative_proportion, modeling inhibitory connections. Within-community edges are always positive.
| Argument | Description |
|---|---|
nodes |
Nodes per block (scalar or length-blocks vector; min 3 per block) |
blocks |
Number of community blocks |
density_matrix |
blocks × blocks symmetric matrix of edge probabilities |
snr |
Signal-to-noise ratio; default 1
|
negative_proportion |
Fraction of between-community edges signed negative; default from empirical distribution |
diffusion |
Minimum proportion of top edges placed outside communities; default 0.30
|
diffusion_range |
If provided, diffusion is drawn uniformly from this interval each call |
sample_size |
Number of observations to generate |
skew / skew_range
|
Per-variable skew in 0
|
Returns: a named list with data, parameters (including Q modularity and weibull edge weight parameters), population (R, Omega, membership), and convergence.
dm <- matrix(0.20, nrow = 3, ncol = 3)
diag(dm) <- 0.90
result <- simulate_sbm(
nodes = 6, blocks = 3, density_matrix = dm, sample_size = 500
)weibull_parameters() — Empirically calibrated edge weight distribution
Predicts the Weibull shape
Predictors. The two SUR equations have an asymmetric structure:
-
Shape is predicted from
snrandrlp$= 1/\log(p)$ , capturing the diminishing marginal effect of network size on weight concentration. Shape governs the spread of the edge weight distribution and is not affected by sampling precision. -
Scale is predicted from
snr,rlp, andscaling$= \sqrt{1/(n - p - 2)}$ (the standard error of partial correlations). Scale governs the typical magnitude of edge weights and is directly affected by estimation precision.
Model fit. Shape:
| Argument | Description |
|---|---|
nodes |
Number of nodes (8–54 to stay within empirical training range) |
sample_size |
Sample size of the dataset |
snr |
Signal-to-noise ratio 1
|
bootstrap |
If TRUE, adds a sampled SUR residual — use in simulation for replication-to-replication variability |
# Predicted parameters for a 15-node network, n = 300
weibull_parameters(nodes = 15, sample_size = 300)
# With bootstrapped residuals for Monte Carlo simulation
weibull_parameters(nodes = 15, sample_size = 300, bootstrap = TRUE)Simulation internals (helpers_simulation)
The shared simulation pipeline is implemented in helpers_simulation.R and handles tasks common to both simulate_smallworld() and simulate_sbm().
generate_edges() draws absolute edge weights from a Weibull distribution parameterized by weibull_parameters(). Draws are repeated until no weight exceeds the empirical maximum (
condition_network() recovers positive definiteness by adding a minimal ridge penalty uniroot(), targeting a user-specified condition number. Maximum shrinkage is capped at approximately 23% following Peeters et al. (2020).
simulate_data() generates multivariate normal observations via a Cholesky decomposition of the population correlation matrix skew_range is provided, per-variable skew is drawn uniformly from the interval.
Candes, E. J., Wakin, M. B., & Boyd, S. P. (2008). Enhancing sparsity by reweighted l1 minimization. Journal of Fourier Analysis and Applications, 14(5), 877–905. https://doi.org/10.1007/s00041-008-9045-x
Fisher, R. A., & Tippett, L. H. C. (1928). Limiting forms of the frequency distribution of the largest or smallest member of a sample. Mathematical Proceedings of the Cambridge Philosophical Society, 24(2), 180–190. https://doi.org/10.1017/S0305004100015681
Gnedenko, B. (1943). Sur la distribution limite du terme maximum d'une série aléatoire. Annals of Mathematics, 44(3), 423–453. https://doi.org/10.2307/1968974
Dicker, L., Huang, B., & Lin, X. (2013). Variable selection and estimation with the seamless-L0 penalty. Statistica Sinica, 23(2), 929–962. https://doi.org/10.5705/ss.2011.074
Fan, J., & Li, R. (2001). Variable selection via nonconcave penalized likelihood and its oracle properties. Journal of the American Statistical Association, 96(456), 1348–1360. https://doi.org/10.1198/016214501753382273
Friedman, J., Hastie, T., & Tibshirani, R. (2008). Sparse inverse covariance estimation with the graphical lasso. Biostatistics, 9(3), 432–441. https://doi.org/10.1093/biostatistics/kxm045
Huth, K. B. S., Haslbeck, J. M. B., Keetelaar, S., Van Holst, R. J., & Marsman, M. (2025). Statistical evidence in psychological networks. Nature Human Behaviour.
Peeters, C. F., van de Wiel, M. A., & van Wieringen, W. N. (2020). The spectral condition number plot for regularization parameter evaluation. Computational Statistics, 35(2), 629–646. https://doi.org/10.1007/s00180-019-00912-z
Wang, Y., Fan, Q., & Zhu, L. (2018). Variable selection and estimation using a continuous approximation to the
Wang, Y., & Zhu, L. (2016). Variable selection and parameter estimation with the Atan regularization method. Journal of Probability and Statistics, 2016, 1–12. https://doi.org/10.1155/2016/6495417
Williams, D. R. (2020). Beyond lasso: A survey of nonconvex regularization in Gaussian graphical models. PsyArXiv. https://doi.org/10.31234/osf.io/ad57p
Zou, H., & Li, R. (2008). One-step sparse estimates in nonconcave penalized likelihood models. Annals of Statistics, 36(4), 1509–1533. https://doi.org/10.1198/016214506000000735


