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.
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.
The model is estimated by node-wise penalised regressions, in two steps:
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).
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 0prcggm() 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_1Both 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.
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.001788016
#> 2 Prot2 0.0010958768 0.9 1.0 -177.288412 0.002478683
#> 3 Prot3 0.0252354865 0.5 1.0 -4.915761 0.001351353
#> 4 Prot4 0.0007696949 0.9 1.0 -320.697407 0.002781316
#> 5 Prot5 0.0023545886 0.9 1.0 -521.428701 0.001628419
#> 6 Prot6 0.0017554372 0.9 1.3 -647.490500 0.001722300
#> 7 Prot7 0.0006100839 0.9 1.0 -790.913647 0.001809168
#> 8 Prot8 0.0009996079 0.9 1.3 -508.038645 0.001878250
#> 9 Prot9 0.0029798359 0.5 1.0 -464.349515 0.001808051
#> 10 Prot10 0.0005850918 0.9 1.0 -673.225814 0.001893131For 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.
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 2fit$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.
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.3826353simulate_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.
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.
The node-wise regressions are independent. ncores runs
them in parallel on the local machine:
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")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.