| Title: | Prior-Informed Conditional Gaussian Graphical Models |
|---|---|
| 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>. |
| Authors: | Alessia Mapelli [aut, cre], Francesca Ieva [ths], Politecnico di Milano [cph] |
| Maintainer: | Alessia Mapelli <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.0 |
| Built: | 2026-11-18 00:12:50 UTC |
| Source: | https://github.com/cran/prCGGM |
Computes a summary measure of the difference between two adjacency matrices.
compare_networks( network1, network2, method = c("difference", "correlation", "frobenius") )compare_networks( network1, network2, method = c("difference", "correlation", "frobenius") )
network1, network2
|
Square numeric matrices of the same size. |
method |
|
A single number.
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")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")
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().
plot_network(network, labels = NULL, threshold = 0, main = "Network")plot_network(network, labels = NULL, threshold = 0, main = "Network")
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. |
Called for its side effect; returns the plotted matrix invisibly.
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"))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"))
Draws network1 - network2 with plot_network(), for example to compare
the personalised networks of two individuals.
plot_network_difference( network1, network2, labels = NULL, main = "Network difference" )plot_network_difference( network1, network2, labels = NULL, main = "Network difference" )
network1, network2
|
Square numeric matrices of the same size. |
labels |
Optional node labels, as in |
main |
Plot title. |
Called for its side effect; returns the difference matrix invisibly.
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)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)
Draws one network component of a fitted model, or the personalised
network of one individual, as a heatmap with plot_network().
## S3 method for class 'prcggm' plot(x, component = "Baseline", newdata = NULL, ...)## S3 method for class 'prcggm' plot(x, component = "Baseline", newdata = NULL, ...)
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 |
Called for its side effect; returns x invisibly.
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")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")
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.
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 )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 )
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 |
Throughout, is the number of subjects, the number of
features (network nodes) and 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
the residuals are regressed on the residuals of the other nodes and
on their interactions with the covariates, using the sparse-group lasso
penalty
where are the population-level (baseline) coefficients,
the coefficients modulated by covariate and the
prior weight matrix. The prior therefore only affects the baseline network.
The penalty is chosen by cross-validation, and the structural
parameters and are chosen separately for each
node by minimising the node-wise BIC
.
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 levels
are dummy coded into 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 .
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.
An object of class "prcggm", a list with elements:
networksNamed list of symmetric adjacency
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 . The diagonal of "Baseline" holds the
inverse residual variances.
mean_effects matrix of covariate effects
on the mean (intercept first), or NULL if mean_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, the bic and the computing time in minutes.
covariatesEncoding information used by predict.prcggm().
settingsList of the main estimation settings.
n, p, q
Number of subjects, features and encoded covariates.
callThe matched call.
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.
predict.prcggm(), summary.prcggm(), plot.prcggm(),
prcggm_slurm_prepare().
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$tuningdata(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
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.
prcggm_exampleprcggm_example
A list with three elements:
xNumeric matrix with 1000 rows (subjects) and 10 columns
(Prot1 to Prot10) 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}.
Simulated; see data-raw/prcggm_example.R in the package sources.
data(prcggm_example) str(prcggm_example)data(prcggm_example) str(prcggm_example)
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 in dir. It also copies
template job scripts to dir and returns the sbatch command to
submit.
Each array task calls prcggm_node() (through the copied
prcggm_node_job.R script) and saves the result of one node in dir.
Once all tasks have finished, prcggm_slurm_collect() reads the
node results and returns the same "prcggm" object as prcggm().
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)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)
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 |
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").
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().
## 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)## 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)
Computes the personalised network of new individuals as the linear
combination of the estimated baseline and covariate-specific components,
.
## S3 method for class 'prcggm' predict(object, newdata = NULL, type = c("network", "precision"), ...)## S3 method for class 'prcggm' predict(object, newdata = NULL, type = c("network", "precision"), ...)
object |
A |
newdata |
Data frame with the covariates of the new individuals,
containing every covariate used in the fit. If |
type |
|
... |
Not used. |
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.
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.
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")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")
Generates expression data whose precision matrix depends linearly on the
covariates, , together with a
prior weight matrix of the chosen quality. The baseline network
is scale-free (preferential attachment) and each covariate
effect is an Erdos-Renyi random graph, following the
simulation design of Mapelli et al. (2026).
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) )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) )
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
|
A list with elements:
xThe matrix of simulated expression
data.
covariatesData frame of the simulated covariates, named x1,
x2, ...: first the binary ones (factors), then the continuous ones.
priorThe prior weight matrix.
truth_precisionNamed list of the true precision components
. Compare with
the precision element of a fitted prcggm() model.
truth_networksNamed list of the true networks on the scale of
the networks element of a fitted prcggm() model, that is the
partial correlations
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.
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")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")
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.
## S3 method for class 'prcggm' summary(object, ...)## S3 method for class 'prcggm' summary(object, ...)
object |
A |
... |
Not used. |
The summary reports:
the number of subjects , features and encoded covariate
columns , 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 possible pairs) and the mean absolute
weight of the non-zero edges;
how often each combination of and
was selected by BIC across the node-wise
regressions.
Printing the returned object shows these results; the full estimates
remain available in the fitted object (see prcggm()).
An object of class "summary.prcggm", a list with elements:
componentsData frame with one row per network component and
columns component, edges, density and mean_abs_weight.
tuningContingency table of the selected alpha (rows) and
theta (columns) across nodes.
fitList with n, p, q, prior (logical) and
symm_method.
prcggm(), plot.prcggm(), predict.prcggm().
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)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)