hcocena is an R package for horizontal integration and downstream analysis of
transcriptomics datasets. It provides a modern S4 workflow built around
HCoCenaExperiment for reproducible network-centric transcriptomics analyses.
The package supports both multi-layer integration, such as RNA-seq plus array data, and single-layer analyses using the same API. The focus is a module-centric workflow: from data import and correlation-based network construction to clustering, heatmaps, functional enrichment, upstream inference, cell-type annotation, longitudinal analysis, and optional LLM-assisted module interpretation.
- S4-first workflow with
HCoCenaExperiment,MultiAssayExperiment, andSummarizedExperiment - Correlation cutoff tuning and automatic cutoff selection helpers
- Clustering, integrated network construction, module splitting, and hCoCena heatmaps
- Functional enrichment across multiple databases with export helpers
- Upstream inference with DoRothEA and PROGENy via
decoupleR - Cell-type annotation helpers and reference-data preview utilities
- Longitudinal module and endotype analyses
- A Docker workflow with bundled
reference_filesfor a ready-to-run setup
- Package source is at the repository root and follows a Bioconductor-style layout
- Docker support lives in
docker/, including bundledreference_files - GitHub-only workflow notebooks are kept in
inst/scripts/workflows/ - CI for package checks is defined in
.github/workflows/bioc-check.yaml
After Bioconductor acceptance:
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("hcocena")For local development or pre-submission testing from a checkout:
install.packages("remotes")
remotes::install_local(".", dependencies = TRUE, upgrade = "never")To build a ready-to-use RStudio image from this repository:
docker build -f docker/Dockerfile -t hcocena .
docker run --rm -p 8787:8787 -e PASSWORD=hcocena hcocenaThe container prepares a workspace at /home/rstudio/hcocena and includes:
- the local
hcocenainstallation - bundled
reference_files/with pathway, GO, hallmark, TF, and immune helper references - visible workflow notebooks under
/home/rstudio/hcocena/inst/scripts/workflows/includinghcocena_main.Rmdandhcocena_satellite.Rmd - preinstalled optional packages for common workflows, including
DESeq2,limma,sva,edgeR,tximport,apeglm,ashr,EnhancedVolcano,pheatmap,org.Hs.eg.db,org.Mm.eg.db,CALIBERrfimpute,RCy3,SpatialExperiment, andGSVA - empty
count_data,annotation_data, andoutputdirectories
See docker/README.md for the Docker-specific notes.
library(hcocena)
hc <- hc_init()
hc <- hc_set_paths(
hc,
dir_count_data = "/path/to/counts/",
dir_annotation = "/path/to/annotation/",
dir_reference_files = "/path/to/reference/",
dir_output = tempdir()
)
hc <- hc_define_layers(
hc,
data_sets = list(
Layer1 = c("counts.tsv", "anno.tsv")
)
)
hc <- hc_read_data(
hc,
gene_symbol_col = "SYMBOL",
sample_col = "SampleID",
count_has_rn = FALSE,
anno_has_rn = FALSE
)
hc <- hc_run_expression_analysis_1(hc, export = FALSE)
hc <- hc_plot_cutoffs(hc, interactive = FALSE)For a reproducible package-based example, install hcocena and run:
browseVignettes("hcocena")The package ships toy data and prepared example objects in inst/extdata to
support documentation, testing, and manual smoke tests.
Local real-data checks live behind an explicit opt-in runner. By default, the
runner looks for the STAR protocol data in ../data relative to this repository
and writes ignored outputs to realdata-output/.
quick uses the real Array/RNA-seq data with the top 2000 variable genes per
layer. It runs integration, clustering, module heatmaps, module splitting,
Hallmark/KEGG enrichment, and a module-label font-size probe. full keeps the
same checks but uses the full imported gene set and broader enrichment defaults.
Rscript scripts/run_realdata_regression.R --mode quick
Rscript scripts/run_realdata_regression.R --mode quick --update-reference
Rscript scripts/run_realdata_regression.R --mode fullSet HCOCENA_REALDATA_DIR to point at another data directory. Normal package
tests skip the real-data run; enable it explicitly with:
HCOCENA_RUN_REALDATA=true HCOCENA_REALDATA_MODE=quick Rscript -e "testthat::test_file('tests/testthat/test-realdata-regression.R')"PowerShell:
$env:HCOCENA_RUN_REALDATA = "true"; $env:HCOCENA_REALDATA_MODE = "quick"; Rscript -e "testthat::test_file('tests/testthat/test-realdata-regression.R')"The exported CSV/JSON artifacts are designed as golden-master inputs for later
R/Python comparisons: QC metrics, edge lists, GFC matrices, module tables,
split diagnostics, enrichment tables, heatmap matrices, and a module-label
font-size probe. Each run also writes a visual_check_report_<mode>.pdf with
the generated plot variants, non-default plot parameters, and image pages for
manual inspection, including the pre-split heatmap, post-split heatmap, and
combined enrichment plot.
The longer walkthroughs the package is normally driven from are installed with it, so they are available from an installed copy and not only from a clone:
inst/scripts/workflows/hcocena_main.Rmd-- full analysis, import to enrichmentinst/scripts/workflows/hcocena_satellite.Rmd-- optional downstream analyses
dir(system.file("scripts", "workflows", package = "hcocena"))
file.copy(
system.file("scripts", "workflows", "hcocena_main.Rmd", package = "hcocena"),
"hcocena_main.Rmd"
)They are templates, not reproducible documents: they point at your own count
and annotation files, and several steps contact external services (ChEA3,
Enrichr, DoRothEA, Cytoscape, LLM providers). The built vignette
(vignette("hcocena-s4-workflow")) is the runnable short version.
One practical note: when using longitudinal imputation with
impute_method = "rfcont", attach CALIBERrfimpute in the session first:
library(CALIBERrfimpute)- Method paper: Oestreich et al. (2022), Bioinformatics, https://doi.org/10.1093/bioinformatics/btac589
- Step-by-step protocol: Holsten et al. (2024), STAR Protocols, https://doi.org/10.1016/j.xpro.2024.102922
Both papers use the earlier hCoCena interface, in which the functions worked
on a global hcobject and had no hc_ prefix (repository
MarieOestreich/hCoCena, Docker image mo126/hcocena). In this package every
step takes and returns an HCoCenaExperiment (hc <- hc_step(hc, ...)), and
the current Docker image is therealtomek/hcocena. The functions map as
follows:
| In the papers | In this package |
|---|---|
init_wd(), check_dirs(), init_save_folder() |
hc_init(), hc_set_paths(), hc_check_dirs(), hc_init_save_folder() |
define_layers(), read_data() |
hc_define_layers(), hc_read_data() |
set_supp_files(), read_supplementary() |
hc_set_supp_files(), hc_read_supplementary() |
set_global_settings(), set_layer_settings() |
hc_set_global_settings(), hc_set_layer_settings() |
suggest_topvar() |
hc_suggest_topvar() |
run_expression_analysis_1(), plot_cutoffs(), set_cutoff(), plot_deg_dist() |
hc_run_expression_analysis_1(), hc_plot_cutoffs(), hc_set_cutoff(), hc_plot_deg_dist() |
run_expression_analysis_2() |
hc_run_expression_analysis_2() |
build_integrated_network(), plot_integrated_network() |
hc_build_integrated_network(), hc_plot_integrated_network() |
cluster_calculation(), plot_cluster_heatmap() |
hc_cluster_calculation(), hc_plot_cluster_heatmap() |
functional_enrichment() |
hc_functional_enrichment() |
TF_overrep_module(), TF_overrep_network(), check_tf() |
hc_tf_overrep_module(), hc_tf_overrep_network(), hc_check_tf() |
find_hubs() |
hc_find_hubs() |
change_grouping_parameter(), cut_hclust() |
hc_change_grouping_parameter(), hc_cut_hclust() |
write_session_info() |
hc_write_session_info() |
Results that the papers read from hcobject are available through
accessors such as hc_clusters(), hc_gene_to_cluster(), hc_graph() and
hc_satellite().
Please cite the method paper, and the protocol where you followed it:
Oestreich M, Holsten L, Agrawal S, Dahm K, Koch P, Jin H, Becker M, Ulas T (2022). "hCoCena: horizontal integration and analysis of transcriptomics datasets." Bioinformatics 38(20):4727-4734. doi:10.1093/bioinformatics/btac589
Holsten L, Dahm K, Oestreich M, Becker M, Ulas T (2024). "hCoCena: A toolbox for network-based co-expression analysis and horizontal integration of transcriptomic datasets." STAR Protocols 5(1):102922. doi:10.1016/j.xpro.2024.102922
In R: citation("hcocena").
