Getting started with prCGGM

prCGGM estimates prior-informed conditional Gaussian graphical models (Mapelli et al., 2026), in which the conditional dependencies among \(p\) features are allowed to change with sample-level covariates, and prior knowledge on the network guides its estimation.

The model

Consider, for example, the expression levels of \(p\) proteins \(Y = (Y_1, \ldots, Y_p)^T\), \(q\) covariates \(X = (X_1, \ldots, X_q)^T\) that may influence them, and prior knowledge on the protein interactions, such as ‘STRING’ confidence scores, collected in a weight matrix \(W \in [0, 1]^{p \times p}\). The model assumes that the expression data follow a multivariate Gaussian distribution given the covariates, with a mean and a precision matrix that both depend linearly on \(X\): \[ Y \mid X \sim N_p\big(B (1, X^T)^T,\, \Omega(X)^{-1}\big), \qquad \Omega(X) = \Delta_0 + \sum_{h=1}^q X_h \Delta_h , \] where \(B\) is the \(p \times (q + 1)\) matrix of covariate effects on the means, \(\Delta_0\) is the \(p \times p\) baseline network and \(\Delta_h\), \(h = 1, \ldots, q\), are the \(p \times p\) covariate-specific components, which describe how covariate \(h\) modulates the edges.

A zero entry \(\Omega_{jk}(X) = 0\) means that features \(j\) and \(k\) are conditionally independent given all the others. The network of an individual is therefore given by the non-zero entries of \(\Omega(X)\), which combines the baseline network with the covariate-specific components according to the individual’s covariates.

Note. Numeric covariates are standardised and factors are dummy coded with the first level as the reference, so \(\Delta_0\) is the network of the reference group at the mean of the numeric covariates. Use factor() or relevel() to choose the reference level.

Estimation

The model is estimated by node-wise penalised regressions, in two steps:

  1. Mean. Each feature is regressed on the covariates with a lasso penalty to estimate \(B\); the residuals are kept for the next step.
  2. Network. For each node \(j\), the residuals of node \(j\) are regressed on the residuals of the other nodes and on their interactions with the covariates, using the sparse-group lasso penalty \[ \alpha\lambda \|(1 - W_{j,-j}) \odot d_j^0\|_1 + \vartheta\alpha\lambda \|d_j^{-0}\|_1 + (1 - \alpha)\lambda \sum_{h=1}^q \|d_j^h\|_2 , \] where \(d_j^0\) and \(d_j^h\) are the coefficients from which \(\Delta_0\) and \(\Delta_h\) are respectively estimated.

The prior weights \(W\) enter only the first term, so edges with strong prior support (\(W_{jk} \approx 1\)) are penalised less in the baseline network, while the covariate-specific changes are learnt from the data alone. The penalty depends on three hyperparameters: \(\lambda\) sets the overall sparsity, \(\alpha\) balances element-wise and group sparsity, and \(\vartheta\) sets the penalty on covariate-specific effects relative to the baseline (see Hyperparameters). The node-wise estimates are finally combined into symmetric networks. The full estimation procedure is described in Mapelli et al. (2026).

library(prCGGM)

Example data

The package ships a small simulated data set with 1000 subjects, 10 proteins, one binary covariate and a prior weight matrix.

data(prcggm_example)
x <- prcggm_example$x
covariates <- prcggm_example$covariates
prior <- prcggm_example$prior
dim(x)
#> [1] 1000   10
table(covariates$x1)
#> 
#>   0   1 
#> 531 469
prior[1:5, 1:5]
#>       Prot1 Prot2 Prot3 Prot4 Prot5
#> Prot1     0     1     1     0     0
#> Prot2     1     0     0     0     0
#> Prot3     1     0     0     1     1
#> Prot4     0     0     1     0     0
#> Prot5     0     0     1     0     0

One function, four models

prcggm() fits the model that matches the inputs you provide:

Inputs Model
x only neighbourhood-selection GGM (lasso)
x, prior prior-weighted GGM
x, covariates conditional GGM
x, covariates, prior prior-informed conditional GGM
set.seed(1)
fit_ggm <- prcggm(x)
fit_ggm
#> Prior-informed conditional Gaussian graphical model
#>   Subjects: 1000  Features: 10  Covariates: 0 
#>   Prior knowledge: no  Symmetrisation: OR 
#>   Network components: Baseline
fit_full <- prcggm(x, covariates = covariates, prior = prior, tune = FALSE)
fit_full
#> Prior-informed conditional Gaussian graphical model
#>   Subjects: 1000  Features: 10  Covariates: 1 
#>   Prior knowledge: yes  Symmetrisation: OR 
#>   Network components: Baseline, x1_1

Both fits return a "prcggm" object. Its main elements are:

  • mean_effects: the estimated covariate effects on the means (\(\hat B\), one row per feature, intercept first);
  • precision: the estimated precision matrix components "Baseline" for \(\Delta_0\) followed by one covariate-specific component per encoded covariate \(\Delta_h\); the model without covariates only has the baseline;
  • networks: the corresponding estimated networks as symmetric adjacency matrices of partial-correlation-type edge weights.
  • tuning: the hyperparameters selected for each node.

See the Value section of ?prcggm for all the elements.

Note. Call set.seed() before prcggm() to make the results reproducible.

Hyperparameters

For each node, the overall penalty \(\lambda\) is chosen by cross-validation (lambda.min by default; set lambda_prec_type = "1se" for sparser networks). The balance \(\alpha\) between element-wise and group sparsity and the relative penalty \(\vartheta\) on covariate-specific effects are chosen by minimising the node-wise BIC over alpha_grid and theta_grid. With tune = FALSE the first value of each grid is used.

set.seed(1)
fit <- prcggm(x, covariates = covariates, prior = prior,
              alpha_grid = c(0.5, 0.9), theta_grid = c(1, 1.3))
fit$tuning
#>      node       lambda alpha theta         bic        time
#> 1   Prot1 0.0090812190   0.5   1.3 -582.541601 0.002817039
#> 2   Prot2 0.0010958768   0.9   1.0 -177.288412 0.003455170
#> 3   Prot3 0.0252354865   0.5   1.0   -4.915761 0.002471153
#> 4   Prot4 0.0007696949   0.9   1.0 -320.697407 0.003044327
#> 5   Prot5 0.0023545886   0.9   1.0 -521.428701 0.002942272
#> 6   Prot6 0.0017554372   0.9   1.3 -647.490500 0.002857308
#> 7   Prot7 0.0006100839   0.9   1.0 -790.913647 0.003008286
#> 8   Prot8 0.0009996079   0.9   1.3 -508.038645 0.002912541
#> 9   Prot9 0.0029798359   0.5   1.0 -464.349515 0.002916873
#> 10 Prot10 0.0005850918   0.9   1.0 -673.225814 0.003067307

For large grids, random_search = TRUE evaluates a random proportion p_random of the combinations at each node.

The cross-validation folds (shared by all nodes and hyperparameter values) and the random-search subsets are drawn from the random number generator before any model is fitted, which is why set.seed() makes the results reproducible, also when running in parallel.

Inspecting the fit

summary(fit)
#> Prior-informed conditional Gaussian graphical model
#>   Subjects: 1000  Features: 10  Covariates: 1 
#>   Prior knowledge: yes  Symmetrisation: OR 
#> 
#> Network components:
#>  component edges density mean_abs_weight
#>   Baseline    12   0.267          0.4858
#>       x1_1    11   0.244          0.0627
#> 
#> Selected (alpha, theta) across nodes:
#>      theta
#> alpha 1 1.3
#>   0.5 2   1
#>   0.9 5   2

fit$networks contains the symmetric adjacency matrices: "Baseline" and one matrix per covariate effect, named after the encoded covariate. Factors are dummy coded with the first level as the reference, so "x1_1" is the change in the network for subjects with x1 = 1 compared with x1 = 0. Use factor() or relevel() to choose the reference level.

plot(fit)

plot(fit, component = "x1_1")

Personalised networks

The network of a new individual is the baseline plus the covariate effects weighted by the individual’s covariates. predict() applies the same standardisation and dummy coding as in the estimation data.

new_subjects <- data.frame(x1 = factor(c("0", "1")))
nets <- predict(fit, new_subjects)
names(nets)
#> [1] "Subject_1" "Subject_2"
compare_networks(nets$Subject_1, nets$Subject_2, method = "frobenius")
#> [1] 0.3826353
plot_network_difference(nets$Subject_2, nets$Subject_1)

Simulating data

simulate_prcggm_data() generates data from the model, with a scale-free baseline network, random covariate effects and a perfect, noisy or absent prior, which is useful to explore the method.

set.seed(2)
sim <- simulate_prcggm_data(n = 500, p = 8, n_binary = 1, n_continuous = 1,
                            prior = "noisy")
fit_sim <- prcggm(sim$x, covariates = sim$covariates, prior = sim$prior,
                  tune = FALSE)
names(fit_sim$networks)
#> [1] "Baseline" "x1_1"     "x2"

Larger problems

Pre-screening

When \(p \times q\) is large compared with \(n\), screening = TRUE removes, for each node, the predictors whose absolute correlation with the node does not exceed gamma (by default the 20th percentile of all absolute pairwise correlations). A custom 0/1 matrix can be supplied with screening_matrix. Pairs with prior support are never removed.

Parallel computing

The node-wise regressions are independent. ncores runs them in parallel on the local machine:

fit <- prcggm(x, covariates = covariates, prior = prior, ncores = 4)

SLURM clusters

For very large networks each node can be a separate task of a ‘SLURM’ array job. The workflow has three non-interactive steps:

# 1. Prepare the inputs and job scripts in a shared directory
job <- prcggm_slurm_prepare(x, covariates = covariates, prior = prior,
                            dir = "/scratch/my_project/prcggm")
job$command   # the sbatch command to submit from a shell

# 2. Each array task runs prcggm_node() through the copied job script.
#    Edit prcggm_node.sbatch (partition, memory, R module) before submitting.

# 3. When all tasks have completed
fit <- prcggm_slurm_collect("/scratch/my_project/prcggm")

References

Mapelli, A., Massi, M. C., Cuccuru, G., Di Angelantonio, E. and Ieva, F. (2026). Prior-informed conditional Gaussian graphical models: an application to protein interaction network reconstruction. arXiv:2606.31805. https://doi.org/10.48550/arXiv.2606.31805

Zhang, J. and Li, Y. (2023). High-dimensional Gaussian graphical regression models with covariates. Journal of the American Statistical Association, 118(543), 2088–2100.