| Type: | Package |
| Title: | Prior-Informed Conditional Gaussian Graphical Models |
| Version: | 0.1.0 |
| Description: | Estimates Gaussian graphical models whose mean and precision matrix depend linearly on sample-level covariates, while integrating prior knowledge on the network structure. A typical application is the reconstruction of personalised protein-protein interaction networks from proteomics data, with clinical or demographic variables as covariates and interaction confidence scores from the 'STRING' database as prior knowledge. Prior knowledge enters through a weighted sparse-group lasso penalty that is applied only to the population-level network, so that covariate-specific changes remain entirely data-driven. Node-wise regressions are fitted with 'glmnet' and 'sparsegl', structural hyperparameters are tuned per node by the Bayesian information criterion, and personalised networks can be predicted for new individuals from their covariates. Estimation runs sequentially, in parallel on a single machine, or as 'SLURM' array jobs on computing clusters. The method is described in Mapelli et al. (2026) <doi:10.48550/arXiv.2606.31805>. |
| License: | GPL-3 |
| URL: | https://github.com/AlessiaMapelli/prCGGM |
| BugReports: | https://github.com/AlessiaMapelli/prCGGM/issues |
| Encoding: | UTF-8 |
| Language: | en-GB |
| LazyData: | true |
| Depends: | R (≥ 4.1.0) |
| Imports: | glmnet, graphics, grDevices, parallel, sparsegl, stats, utils |
| Suggests: | corrplot, knitr, rmarkdown, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Config/roxygen2/version: | 8.1.1 |
| NeedsCompilation: | no |
| Packaged: | 2026-10-30 10:18:33 UTC; alessia.mapelli |
| Author: | Alessia Mapelli [aut, cre], Francesca Ieva [ths], Politecnico di Milano [cph] |
| Maintainer: | Alessia Mapelli <alessia.mapelli@polimi.it> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-17 13:10:08 UTC |
prCGGM: Prior-Informed Conditional Gaussian Graphical Models
Description
Estimation of conditional Gaussian graphical models in which both the mean and the precision matrix depend linearly on subject-level covariates, with prior knowledge on edges entering the population-level network through a weighted penalty.
Details
The main entry points are:
-
prcggm()to fit the model; -
predict.prcggm()to obtain personalised networks for new individuals; -
summary.prcggm()andplot.prcggm()to inspect a fitted model; -
prcggm_slurm_prepare(),prcggm_node()andprcggm_slurm_collect()to run the node-wise estimation as 'SLURM' array jobs.
Author(s)
Maintainer: Alessia Mapelli alessia.mapelli@polimi.it
Authors:
Alessia Mapelli alessia.mapelli@polimi.it
Other contributors:
Francesca Ieva [thesis advisor]
Politecnico di Milano [copyright holder]
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. doi:10.48550/arXiv.2606.31805
See Also
Useful links:
Report bugs at https://github.com/AlessiaMapelli/prCGGM/issues
Compare two networks
Description
Computes a summary measure of the difference between two adjacency matrices.
Usage
compare_networks(
network1,
network2,
method = c("difference", "correlation", "frobenius")
)
Arguments
network1, network2 |
Square numeric matrices of the same size. |
method |
|
Value
A single number.
Examples
a <- matrix(c(0, 0.4, 0, 0.4, 0, -0.3, 0, -0.3, 0), 3, 3)
b <- matrix(c(0, 0.1, 0, 0.1, 0, -0.1, 0, -0.1, 0), 3, 3)
compare_networks(a, b, method = "frobenius")
Plot a network component of a fitted model
Description
Draws one network component of a fitted model, or the personalised
network of one individual, as a heatmap with plot_network().
Usage
## S3 method for class 'prcggm'
plot(x, component = "Baseline", newdata = NULL, ...)
Arguments
x |
A |
component |
Name of the component to draw: |
newdata |
Optional one-row data frame of covariates; if supplied, the personalised network of that individual is drawn. |
... |
Further arguments passed to |
Value
Called for its side effect; returns x invisibly.
Examples
data(prcggm_example)
set.seed(1)
fit <- prcggm(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
tune = FALSE)
plot(fit)
plot(fit, component = "x1_1")
Plot a network as a heatmap
Description
Draws an adjacency matrix (for example a component of a fitted model or a
personalised network from predict.prcggm()) as a heatmap. The
corrplot package is used if installed, otherwise
stats::heatmap().
Usage
plot_network(network, labels = NULL, threshold = 0, main = "Network")
Arguments
network |
Square numeric matrix. |
labels |
Optional node labels. By default the row or column names of
|
threshold |
Entries with absolute value below |
main |
Plot title. |
Value
Called for its side effect; returns the plotted matrix invisibly.
Examples
net <- matrix(c(0, 0.4, 0, 0.4, 0, -0.3, 0, -0.3, 0), 3, 3)
plot_network(net, labels = c("A", "B", "C"))
Plot the difference between two networks
Description
Draws network1 - network2 with plot_network(), for example to compare
the personalised networks of two individuals.
Usage
plot_network_difference(
network1,
network2,
labels = NULL,
main = "Network difference"
)
Arguments
network1, network2 |
Square numeric matrices of the same size. |
labels |
Optional node labels, as in |
main |
Plot title. |
Value
Called for its side effect; returns the difference matrix invisibly.
Examples
a <- matrix(c(0, 0.4, 0.4, 0), 2, 2)
b <- matrix(c(0, 0.1, 0.1, 0), 2, 2)
plot_network_difference(a, b)
Fit a prior-informed conditional Gaussian graphical model
Description
Estimates a Gaussian graphical model in which both the mean and the precision matrix depend linearly on subject-level covariates, while prior knowledge on the network (for example 'STRING' interaction confidence scores) reduces the penalty on supported edges of the population-level network.
Usage
prcggm(
x,
covariates = NULL,
prior = NULL,
screening = FALSE,
gamma = NULL,
screening_matrix = NULL,
mean_estimation = TRUE,
lambda_mean = NULL,
lambda_mean_type = c("min", "1se"),
lambda_prec = NULL,
lambda_prec_type = c("min", "1se"),
tune = TRUE,
alpha_grid = c(0.75, 0.5, 0.9, 0.95),
theta_grid = c(1, 0.8, 1.1, 1.3, 1.5),
random_search = FALSE,
p_random = 0.5,
nfolds = 5,
symm_method = c("OR", "AND"),
ncores = 1L,
verbose = FALSE
)
Arguments
x |
Numeric |
covariates |
Optional data frame of subject-level covariates with
|
prior |
Optional symmetric |
screening |
Logical; if |
gamma |
Correlation threshold in [0, 1] for screening. If |
screening_matrix |
Optional |
mean_estimation |
Logical; if |
lambda_mean |
Optional fixed lasso penalty for the mean regressions.
If |
lambda_mean_type |
Cross-validation rule used to select
|
lambda_prec |
Optional fixed penalty for the node-wise network
regressions. If |
lambda_prec_type |
Cross-validation rule used to select
|
tune |
Logical; if |
alpha_grid |
Candidate values in [0, 1] for |
theta_grid |
Positive candidate values for |
random_search |
Logical; if |
p_random |
Proportion of the grid evaluated when |
nfolds |
Number of cross-validation folds. Default 5. |
symm_method |
Symmetrisation rule: |
ncores |
Number of cores used to fit the node-wise regressions in
parallel with the parallel package. Default 1 (sequential). For
very large networks see |
verbose |
Logical; print progress messages. Default |
Details
Throughout, n is the number of subjects, p the number of
features (network nodes) and q the number of covariate columns after
encoding (see Covariate encoding).
Estimation follows two steps. First, each feature is regressed on the
covariates with a lasso penalty and the residuals are kept. Second, for each node
j the residuals 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 are the population-level (baseline) coefficients,
d_j^h the coefficients modulated by covariate h and W the
prior weight matrix. The prior therefore only affects the baseline network.
The penalty \lambda is chosen by cross-validation, and the structural
parameters \alpha and \vartheta are chosen separately for each
node by minimising the node-wise BIC
n \log(RSS_j / n) + \log(n) df_j.
Node-wise estimates are finally combined into symmetric matrices with the
"OR" or "AND" rule.
Depending on the inputs, the same function fits a standard neighbourhood-selection GGM (no covariates, no prior), a prior-weighted GGM (prior only), a conditional GGM (covariates only) or the full prior-informed conditional GGM.
Covariate encoding. Numeric covariates are standardised and give one
column each. Factors (and character or logical columns) with C levels
are dummy coded into C - 1 columns with the first level as the
reference, so the baseline network refers to the reference group; use
factor() or relevel() to choose the reference level. The total number
of resulting columns is q.
Reproducibility. Cross-validation folds (shared by all nodes and
hyperparameter values) and the random-search subsets are drawn from the
current random number generator state before any model is fitted, so
calling set.seed() beforehand makes the fit reproducible, also when
ncores > 1.
Value
An object of class "prcggm", a list with elements:
networksNamed list of symmetric
p \times padjacency matrices of partial-correlation-type edge weights:"Baseline"(the population network) followed by one matrix per covariate effect, named after the encoded covariate (for example"sex_Male").precisionNamed list with the corresponding precision matrix components
\hat\Delta_h. The diagonal of"Baseline"holds the inverse residual variances.mean_effectsp \times (q + 1)matrix of covariate effects on the mean (intercept first), orNULLifmean_estimation = FALSE.residualsMatrix of residuals from the mean step, used as input to the network step.
coefficientsMatrix of node-wise regression coefficients (one row per node) before symmetrisation.
sigma2Residual variance of each node-wise regression.
tuningData frame with, for each node, the selected
lambda,alpha,theta, thebicand the computing time in minutes.covariatesEncoding information used by
predict.prcggm().settingsList of the main estimation settings.
n,p,qNumber of subjects, features and encoded covariates.
callThe matched call.
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. doi: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.
See Also
predict.prcggm(), summary.prcggm(), plot.prcggm(),
prcggm_slurm_prepare().
Examples
data(prcggm_example)
set.seed(1)
fit <- prcggm(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
tune = FALSE)
fit
summary(fit)
# Tune alpha and theta by BIC on a small grid
fit_tuned <- prcggm(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
alpha_grid = c(0.5, 0.9), theta_grid = c(1, 1.3))
fit_tuned$tuning
Example data for prCGGM
Description
A small simulated data set with 1000 subjects, 10 proteins and one binary covariate, generated from a conditional Gaussian graphical model with a scale-free baseline network and an Erdos-Renyi covariate-specific network, as in the simulation study of Mapelli et al. (2026). The prior weight matrix is "perfect": it equals 1 on the true baseline edges and 0 elsewhere.
Usage
prcggm_example
Format
A list with three elements:
xNumeric matrix with 1000 rows (subjects) and 10 columns (
Prot1toProt10) of expression values.covariatesData frame with one factor column,
x1, with levels"0"(reference) and"1".prior10 x 10 prior weight matrix with entries in {0, 1}.
Source
Simulated; see data-raw/prcggm_example.R in the package sources.
Examples
data(prcggm_example)
str(prcggm_example)
Run the estimation as SLURM array jobs
Description
For large networks the node-wise regressions can be distributed over a computing cluster, one 'SLURM' array task per node, in three steps:
-
prcggm_slurm_prepare()validates the inputs, runs the mean step and saves everything the node-wise regressions need indir. It also copies template job scripts todirand returns thesbatchcommand to submit. Each array task calls
prcggm_node()(through the copiedprcggm_node_job.Rscript) and saves the result of one node indir.Once all tasks have finished,
prcggm_slurm_collect()reads the node results and returns the same"prcggm"object asprcggm().
Usage
prcggm_slurm_prepare(
x,
covariates = NULL,
prior = NULL,
dir,
screening = FALSE,
gamma = NULL,
screening_matrix = NULL,
mean_estimation = TRUE,
lambda_mean = NULL,
lambda_mean_type = c("min", "1se"),
lambda_prec = NULL,
lambda_prec_type = c("min", "1se"),
tune = TRUE,
alpha_grid = c(0.75, 0.5, 0.9, 0.95),
theta_grid = c(1, 0.8, 1.1, 1.3, 1.5),
random_search = FALSE,
p_random = 0.5,
nfolds = 5,
symm_method = c("OR", "AND"),
copy_templates = TRUE,
verbose = FALSE
)
prcggm_node(input, node, output_dir = dirname(input))
prcggm_slurm_collect(dir, output_dir = dir)
Arguments
x |
Numeric |
covariates |
Optional data frame of subject-level covariates with
|
prior |
Optional symmetric |
dir |
Directory where inputs, job scripts and node results are written. It is created if needed. There is no default: choose a location on a file system shared by the cluster nodes. |
screening |
Logical; if |
gamma |
Correlation threshold in [0, 1] for screening. If |
screening_matrix |
Optional |
mean_estimation |
Logical; if |
lambda_mean |
Optional fixed lasso penalty for the mean regressions.
If |
lambda_mean_type |
Cross-validation rule used to select
|
lambda_prec |
Optional fixed penalty for the node-wise network
regressions. If |
lambda_prec_type |
Cross-validation rule used to select
|
tune |
Logical; if |
alpha_grid |
Candidate values in [0, 1] for |
theta_grid |
Positive candidate values for |
random_search |
Logical; if |
p_random |
Proportion of the grid evaluated when |
nfolds |
Number of cross-validation folds. Default 5. |
symm_method |
Symmetrisation rule: |
copy_templates |
Logical; copy the template job scripts to |
verbose |
Logical; print progress messages. Default |
input |
Path of the input file written by |
node |
Index of the node (feature) to estimate, from 1 to |
output_dir |
Directory where the node result is saved. Defaults to
the directory of |
Details
Edit the copied prcggm_node.sbatch file to match your cluster (partition,
memory, time, and how R is loaded) before submitting. The template files
are also available in system.file("slurm", package = "prCGGM").
Value
prcggm_slurm_prepare() returns, invisibly, a list with the path
of the saved input file (input), the number of nodes (p) and the
sbatch command to run (command), which is also printed as a message.
prcggm_node() returns, invisibly, the path of the saved node
result.
prcggm_slurm_collect() returns a "prcggm" object, as
prcggm().
Examples
## Not run:
# On the cluster login node
job <- prcggm_slurm_prepare(expr, covariates = covs, prior = W,
dir = "/scratch/my_project/prcggm")
# Submit job$command from a shell, e.g.
# sbatch --array=1-366 /scratch/my_project/prcggm/prcggm_node.sbatch ...
# When all array tasks have completed:
fit <- prcggm_slurm_collect("/scratch/my_project/prcggm")
## End(Not run)
# The same three steps run locally, without SLURM:
data(prcggm_example)
dir <- file.path(tempdir(), "prcggm_slurm")
set.seed(1)
job <- prcggm_slurm_prepare(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
tune = FALSE, dir = dir,
copy_templates = FALSE)
for (i in seq_len(job$p)) prcggm_node(job$input, i)
fit <- prcggm_slurm_collect(dir)
unlink(dir, recursive = TRUE)
Predict personalised networks
Description
Computes the personalised network of new individuals as the linear
combination of the estimated baseline and covariate-specific components,
\hat A(x) = \hat A_0 + \sum_h x_h \hat A_h.
Usage
## S3 method for class 'prcggm'
predict(object, newdata = NULL, type = c("network", "precision"), ...)
Arguments
object |
A |
newdata |
Data frame with the covariates of the new individuals,
containing every covariate used in the fit. If |
type |
|
... |
Not used. |
Details
Covariates in newdata are encoded exactly as in the estimation data:
numeric covariates are standardised with the training mean and standard
deviation, and factors are dummy coded against the training reference
level.
Value
A list with one matrix per row of newdata, named
Subject_1, Subject_2, and so on. Without newdata, a list holding
the baseline matrix only.
See Also
Examples
data(prcggm_example)
set.seed(1)
fit <- prcggm(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
tune = FALSE)
new_subjects <- data.frame(x1 = factor(c("0", "1")))
nets <- predict(fit, new_subjects)
compare_networks(nets$Subject_1, nets$Subject_2, method = "frobenius")
Simulate data from a conditional Gaussian graphical model
Description
Generates expression data whose precision matrix depends linearly on the
covariates, \Omega(x) = \Delta_0 + \sum_h x_h \Delta_h, together with a
prior weight matrix of the chosen quality. The baseline network
\Delta_0 is scale-free (preferential attachment) and each covariate
effect \Delta_h is an Erdos-Renyi random graph, following the
simulation design of Mapelli et al. (2026).
Usage
simulate_prcggm_data(
n = 500,
p = 10,
n_binary = 1,
n_continuous = 0,
edge_prob = 0.1,
coef_range = c(0.35, 0.5),
power = 2.5,
prior = c("perfect", "noisy", "none"),
sensitivity = 0.8,
specificity = 0.9,
confidence_range = c(0.7, 1)
)
Arguments
n |
Number of subjects. |
p |
Number of features (nodes). |
n_binary, n_continuous |
Number of binary (Bernoulli(0.5), returned as
factors with levels |
edge_prob |
Edge probability of the covariate-effect networks. |
coef_range |
Range of the absolute values of the non-zero off-diagonal entries; signs are random. |
power |
Preferential attachment power of the baseline network. |
prior |
Quality of the simulated prior: |
sensitivity, specificity |
Parameters of the noisy prior. |
confidence_range |
Range of the confidence scores of true edges in
the noisy prior; false edges get scores between 0.1 and
|
Value
A list with elements:
xThe
n \times pmatrix of simulated expression data.covariatesData frame of the simulated covariates, named
x1,x2, ...: first the binary ones (factors), then the continuous ones.priorThe
p \times pprior weight matrix.truth_precisionNamed list of the true precision components
\Delta_0, \Delta_1, \ldots. Compare with theprecisionelement of a fittedprcggm()model.truth_networksNamed list of the true networks on the scale of the
networkselement of a fittedprcggm()model, that is the partial correlations-(\Delta_h)_{jk} / \sqrt{(\Delta_0)_{jj} (\Delta_0)_{kk}}with zero diagonal. Their sign is opposite to that of the precision components.
Both lists use the same names as the components of a fitted prcggm()
model ("Baseline", "x1_1", "x2", ...), so that, for example,
fit$networks$x1_1 estimates sim$truth_networks$x1_1.
Examples
set.seed(1)
sim <- simulate_prcggm_data(n = 200, p = 8)
str(sim, max.level = 1)
# Compare the estimated baseline network with the truth
fit <- prcggm(sim$x, covariates = sim$covariates, prior = sim$prior,
mean_estimation = FALSE, tune = FALSE)
compare_networks(fit$networks$Baseline, sim$truth_networks$Baseline,
method = "correlation")
Summarise a fitted prCGGM model
Description
Gives an overview of a fitted "prcggm" object: the size of the problem,
the model that was fitted, the structure of each estimated network
component and the hyperparameters selected across nodes.
Usage
## S3 method for class 'prcggm'
summary(object, ...)
Arguments
object |
A |
... |
Not used. |
Details
The summary reports:
the number of subjects
n, featurespand encoded covariate columnsq, whether prior knowledge was used and the symmetrisation rule;for each network component (the baseline network and one component per covariate effect), the number of edges, the density (edges divided by the
p(p - 1)/2possible pairs) and the mean absolute weight of the non-zero edges;how often each combination of
\alphaand\varthetawas selected by BIC across thepnode-wise regressions.
Printing the returned object shows these results; the full estimates
remain available in the fitted object (see prcggm()).
Value
An object of class "summary.prcggm", a list with elements:
componentsData frame with one row per network component and columns
component,edges,densityandmean_abs_weight.tuningContingency table of the selected
alpha(rows) andtheta(columns) across nodes.fitList with
n,p,q,prior(logical) andsymm_method.
See Also
prcggm(), plot.prcggm(), predict.prcggm().
Examples
data(prcggm_example)
set.seed(1)
fit_tuned <- prcggm(prcggm_example$x,
covariates = prcggm_example$covariates,
prior = prcggm_example$prior,
alpha_grid = c(0.5, 0.9), theta_grid = c(1, 1.3))
summary(fit_tuned)