Skip to content
BioCompNetPublic

About

Vertical omics integration

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

vcocena

R-CMD-check Codecov pkgdown License: MIT

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.

Install

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.

Docker (recommended)

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.R

See docker/README.md for running your own data.

Quickstart

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, reason

The 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.

Reading the 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.

Figures

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 vocabulary

Shorthands: 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

Every figure also saves its data

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)

The module-level figures agree with each other

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.

The heatmap with pathways on the right

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.

Reproducing the published Figure 5

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.

Reading Figure 5B

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.

Important parameters

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.

Reproducibility notes

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.

Citation

See CITATION.cff. The method is described in Carraro et al., eLife 2022.

About

Vertical omics integration

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages