--- title: "Getting started with prCGGM" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting started with prCGGM} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 5, fig.height = 4.5) ``` **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](#hyperparameters)). The node-wise estimates are finally combined into symmetric networks. The full estimation procedure is described in Mapelli et al. (2026). ```{r setup} 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. ```{r data} data(prcggm_example) x <- prcggm_example$x covariates <- prcggm_example$covariates prior <- prcggm_example$prior dim(x) table(covariates$x1) prior[1:5, 1:5] ``` ## 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 | ```{r variants} set.seed(1) fit_ggm <- prcggm(x) fit_ggm fit_full <- prcggm(x, covariates = covariates, prior = prior, tune = FALSE) fit_full ``` 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. ```{r tuning} 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 ``` 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 ```{r summary} summary(fit) ``` `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. ```{r plot-baseline} plot(fit) ``` ```{r plot-covariate} 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. ```{r predict} new_subjects <- data.frame(x1 = factor(c("0", "1"))) nets <- predict(fit, new_subjects) names(nets) compare_networks(nets$Subject_1, nets$Subject_2, method = "frobenius") ``` ```{r plot-difference} 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. ```{r simulate} 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) ``` ## 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: ```{r parallel, eval = FALSE} 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: ```{r slurm, eval = FALSE} # 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. Zhang, J. and Li, Y. (2023). High-dimensional Gaussian graphical regression models with covariates. *Journal of the American Statistical Association*, 118(543), 2088--2100.