vcocena provides a packaged, runnable version of the Vertical CoCena² multi‑omics
pipeline, plus plotting helpers.
Where horizontal integration (hCoCena) combines several datasets measured on one platform, vertical integration combines different omics layers — RNA‑seq and microarray, or transcriptome and chromatin accessibility. The pipeline builds a co‑expression network per layer, clusters each, correlates clusters across layers, and merges everything into one integrated network of modules.
Two dependencies are no longer on CRAN — MCDA (archived 2025-11-20) and its
dependency glpkAPI (archived 2026-03-20). Both sit on the main execution path, so
they cannot be skipped. Add a dated repository snapshot from before the archivals and
they resolve as ordinary packages:
options(repos = c(
CRAN = "https://cloud.r-project.org",
snapshot = "https://packagemanager.posit.co/cran/2025-11-01"
))
# install.packages("remotes")
remotes::install_github("BioCompNet/Vcocena")The snapshot is a secondary repository: R takes the highest available version of each package, so everything else still comes from current CRAN and only the two archived packages come from the snapshot.
glpkAPI compiles against the GLPK C library — libglpk-dev on Debian/Ubuntu,
brew install glpk on macOS. The remaining Bioconductor dependencies install normally
via BiocManager::install().
Do not call install_bioconductor_packages() from this package — it still lists
pcaGoPromoter, which was removed from Bioconductor in release 3.12.
The container pins every dependency, including the two archived ones, and needs no manual setup:
git clone https://github.com/BioCompNet/Vcocena.git && cd Vcocena
docker build -f docker/Dockerfile -t vcocena:1.0.0 .
docker run --rm vcocena:1.0.0 Rscript /opt/docker/run_smoke.RSee docker/README.md for running your own data.
library(vcocena)
ex <- vcocena_example()
# vcocena_example() points into the installed package library, which is usually
# read-only. run_vcocena() creates its save_folder inside working_directory and
# writes plots there, so copy the example somewhere writable first.
wd <- file.path(tempdir(), "example_vertical")
dir.create(wd, recursive = TRUE, showWarnings = FALSE)
file.copy(list.files(ex$working_directory, full.names = TRUE), wd, recursive = TRUE)
out <- run_vcocena(
working_directory = wd,
layers = list(
set1 = c(ex$counts_seq, ex$anno_seq),
set2 = c(ex$counts_array, ex$anno_array)
),
supplement = c(ex$tf, ex$hallmark, ex$go, ex$kegg, ex$reactome),
layers_names = c("sequencing", "microarray"),
save_folder = "out_v1",
layer_top_var = c(100, 100),
layer_min_corr = c(0.2, 0.2),
layer_range_cutoff_length = c(10, 10),
data_in_log = TRUE,
# Modules below this many entities are dropped (painted white). Kept small here
# because the toy example only has 100 genes per layer; real runs use 15–50.
min_nodes_number_for_cluster = 5,
# Figures are opt-in. "paper" draws Fig 5B/5C/5D/5E of Carraro et al.;
# see the Figures section below for the full vocabulary.
plots = "paper"
)
out$plots # one row per figure: key, status, seconds, files, reasonThe bundled example is a 100‑gene subset intended only as a smoke test; its variance range is too narrow for meaningful modules. Use it to check the install, not to judge results.
run_vcocena() returns a list, but the network and cluster objects are written to the
global environment rather than into that return value. Read them from there:
lso <- get("layer_specific_outputs", envir = .GlobalEnv) # per-layer networks, clusters
int <- get("integrated_output", envir = .GlobalEnv) # integrated network + modules
int$cluster_calc$cluster_information # module assignments
int$cluster_calc$GFC_per_cluster # Group Fold Change per module per condition
# cluster_information still contains modules below min_nodes_number_for_cluster,
# marked cluster_included = "no" / color = "white". Filter them out yourself:
dplyr::filter(int$cluster_calc$cluster_information, color != "white")There is no tabular export; results live as in‑memory objects and PDFs. docker/run_full.R
shows how to write them out as TSV.
run_vcocena() always writes the per-layer Heatmap_topvar_genes<x>.pdf files —
they come out of the analysis itself. Everything else is opt-in through plots,
which defaults to "none" meaning no additional figures.
run_vcocena(..., plots = "paper") # Fig 5B, 5C/5E, 5D
run_vcocena(..., plots = c("module_heatmap", "cutoffs"))
run_vcocena(..., plots = "all")
vcocena_plot_keys() # the full vocabularyShorthands: none, paper, networks, diagnostics, all.
| key | figure |
|---|---|
module_heatmap |
Fig 5B — modules × conditions, cells = GFC, plus a module-size bar and a layer share (%) bar giving each module's per-layer composition |
module_heatmap_enrichment |
Fig 5B with the enriched pathways of each module drawn to its right — the combined figure hCoCena's functional-enrichment step produces. One PDF per .gmt collection in supplement, plus an _ALL page with the collections as headed blocks |
module_circos |
Fig 5D — one page per module: its entities around a circle, one concentric track per condition, split into per-layer sectors, with an inner dendrogram |
module_networks |
Supplementary — the same modules drawn as subnetworks, nodes coloured by GFC and outlined by layer. Not a panel of Figure 5. Modules above max_edges (20,000 within-module edges) are skipped with a reason: every edge is a line on every condition panel |
enrichment |
Fig 5C/5E — enrichment dot plots for each .gmt in supplement |
network_integrated, network_gfc, network_layers |
the integrated network by module, by GFC per condition, and by layer |
cutoffs, degree, corr_dist |
cutoff-selection and network diagnostics |
pca, pca_modules |
sample PCA, and PCA by module |
Unknown keys are rejected before any analysis runs, so a typo costs a millisecond rather than the whole correlation stage.
Figures are drawn in isolation: one that fails is recorded and the rest still
run, because the analysis results already exist. The return value carries a
manifest, also written to <save_folder>/plot_report.csv:
key status time files
module_heatmap ok 1.8s 2
module_circos ok 95.3s 2
enrichment skipped 0.1s 0 <- no collection yielded enriched terms
Beside each PDF the stage writes <key>.rds holding what the figure was drawn
from — and, where one exists, the plot object itself — so a panel can be
rebuilt or restyled without rerunning the pipeline:
| file | contents |
|---|---|
module_heatmap.rds |
the ComplexHeatmap object, the module × condition GFC matrix, the per-layer composition table, and the drawn (clustered) module order with colour names |
module_circos.rds |
the modules drawn, their gene lists, and the per-gene GFC table for those genes |
module_networks.rds |
a per-module summary (vertices, edges, shared entities) and each module's layout coordinates |
enrichment.rds |
one result table per gene-set collection, the modules profiled, and the background size |
network_integrated.rds, network_gfc.rds, network_layers.rds |
the drawn igraph, the shared layout, and the colouring table used |
cutoffs.rds, degree.rds |
per-layer cutoff statistics and the cutoffs chosen |
corr_dist.rds |
the integrated edge list and cross-layer correlations |
pca.rds, pca_modules.rds |
the prcomp objects |
x <- readRDS("out_v1/module_heatmap.rds")
x$module_names # "orchid" "sandybrown" ...
ComplexHeatmap::draw(x$heatmap)Fig 5B clusters its rows, so the drawn order differs from the table order. The
stage records the order the reader actually saw and draws the Fig 5D pages, the
subnetwork pages and the enrichment columns in that same order. Modules are
named by their nearest named colour everywhere (steelblue, not #4682B4), so
the same module carries the same name across every panel.
A skipped row always says why. On the bundled example, enrichment is
expected to skip: the toy .gmt files contain placeholder identifiers
(PC1, LNC1, …) that share no genes with the toy count matrices.
To draw figures after the fact on a workspace that is already loaded, call
vcocena_plots() directly — it reads the same global objects the pipeline
leaves behind.
module_heatmap_enrichment follows the design of the
hCoCena enrichment figure: a
second panel is joined to the right of the module heatmap, one column per
enriched term, one dot per (module, term). Dot size encodes significance —
(−log10 q − 1)/4 clamped to [0, 1], so q = 0.01 is a small dot and q ≤ 1e-5 the
largest — and a module-coloured guide line runs across each row so the eye can
follow a module into the panel. Each module contributes its top (default 5)
terms; with consistent_terms = TRUE the columns are the union of those, and a
dot appears wherever any of them is significant in a module, so a term can be
read across rows. Rows are not clustered here; they follow the order Fig 5B was
drawn in.
plot_module_heatmap_enrichment(gene_sets = supplementary_data$hallmark,
label = "HALLMARK", top = 5)
# several collections as headed blocks:
plot_module_heatmap_enrichment(gene_sets = list(GO = supplementary_data$go,
KEGG = supplementary_data$kegg))On the bundled example this figure is skipped: the toy .gmt files share no
genes with the toy counts, so nothing can be enriched. It needs real gene sets.
The published network reproduces exactly, and from the authors' saved
environment (Zenodo 10.5281/zenodo.6984701) this package draws Figure 5B with
the paper's 14 modules in the paper's row order, gene loads and RNA/ATAC
shares, and the paper's Fig 5D circular heatmap. out_paper/README.md in the
project records what matched and what legitimately differs (re-clustering
under igraph 2.0 yields 6 modules; enrichment thresholds). Two arguments exist
for that data's conventions and any like it:
plot_module_heatmap(col_order = c("B_C_RNA", "B_T_6_RNA", ...), # published order
condition_annotation = c("cell_line", "time_point", "compound")) # colour tiles
plot_module_heatmap_enrichment(gene_sets = supplementary_data$hallmark,
symbol_fun = function(x) sub("\\s*_A$", "", x)) # ATAC nodes are "GENE _A"symbol_fun maps entity names to gene symbols for gene-set matching only;
module membership and layer shares always use the true entity names, which is
what keeps the RNA and ATAC copies of a gene distinct.
Modules are stored as hex colours, so the heatmap labels rows with the nearest
named colour — this is where names like steelblue come from. Right of the
heatmap: a module colour swatch, an entities bar with the module size printed
beside it, and a layer share (%) bar giving each module's share of entities
per layer. Those shares sum to 100% even when an entity is present in both
layers (it contributes 1/k to each of its k layers). If a run warns that most
entities are shared, the layer split carries little information: that happens
whenever both layers measure the same identifiers, as in the bundled
sequencing/microarray example, where every module reads 50/50.
A note on names: module colours are assigned by position in a fixed palette and interpolated to the number of modules found, so steelblue in one run has no relation to steelblue in another — or in the paper. Compare modules by their gene lists, never by their names.
| Argument | Why it matters |
|---|---|
data_in_log |
Set TRUE for rlog/VST/log2 input. Leaving it FALSE silently produces wrong Group Fold Changes. |
layer_top_var |
Genes/features per layer. suggest_topvar() proposes values from variance inflection points. |
cutoff_vec |
Correlation cutoff per layer. If NULL these are chosen automatically — see the caveat below. |
voi |
Annotation column defining groups for GFC calculation. |
min_nodes_number_for_cluster |
Minimum module size, default 3. Smaller modules are marked cluster_included = "no" and coloured white rather than deleted — see below. |
identicals_min_corr, cross_corr_threshold |
Control which cross‑layer cluster pairs are linked. |
plots |
Which figures to draw. Default "none" means no additional figures. |
Automatic cutoff selection is stringent. On a published dataset, choose_auto_cutoff()
selected 0.984/0.991 where the original authors had chosen 0.707/0.693 by hand from the
diagnostic plots — retaining 878 entities instead of 3,405. Inspect cutoff_plot() and
consider passing cutoff_vec explicitly rather than relying on the automatic choice.
min_nodes_number_for_cluster applies at both stages. The same value is passed to
per‑layer clustering and to the integrated clustering, and there is no way to set them
separately through run_vcocena(). This matters because find_all_cluster_corrs() skips
white clusters outright — a layer cluster dropped by the threshold never enters the
cross‑layer correlation step, so its entities get no cross‑layer edges. Raising the value
shrinks the integrated network, not just the final module table. To threshold only the
final modules, run the stages separately (see vCoCena_stepwise.R) and raise
global_settings$min_nodes_number_for_cluster between cluster_networks() and
cluster_integrated_network().
Note also that entities the algorithm could not assign consistently across iterations are
put in Cluster 0 and painted white too — that is a separate mechanism from the size
threshold.
Module counts will not match analyses run before ~2024. igraph 2.0 rewrote community
detection. On an identical network, cluster_louvain returns 6 communities where igraph
1.2.6 returned 147. Re‑running an older CoCena analysis on current igraph yields coarser
modules; the entities do not scatter, they merge.
run_vcocena() takes count matrices, one per layer. If your layers are themselves
hCoCena integrations across several datasets, this entry point does not accept them —
that was the design in Carraro et al. 2022, and it needs the hCoCena stage first.
docker/run_paper.R and docker/run_paper_integration.R check this package against
Carraro et al., eLife 2022 using the authors'
own saved R environment as ground truth. The vertical‑integration stage reproduces the
published network exactly: 3,405 nodes, 186,723 edges, 35,453 cross‑layer edges.
See CITATION.cff. The method is described in
Carraro et al., eLife 2022.