Written and maintained by CASRAI Editorial Board
Published
On this page
hdWGCNA is an R package for finding gene co-expression modules in single-cell and spatial transcriptomics data held in Seurat objects. Its workflow connects metacell-based network construction with single-cell module summaries and hub-gene analysis. Keeping those analysis units separate makes the results easier to interpret and reproduce.
What it is used for in research
Use hdWGCNA to investigate groups of genes whose expression varies together within a defined cellular context. Morabito and colleagues describe a framework for network inference, module identification, enrichment, statistical analysis and visualization. It extends the Seurat ecosystem rather than replacing the upstream single-cell RNA sequencing workflow.
The methods paper explains the central difficulty: sparse single-cell measurements can distort gene correlations. Aggregating similar cells into metacells reduces sparsity before estimating the network. The resulting modules describe relationships among genes; they are different from clusters that group cells. A project therefore needs both a cellular context and a gene-network question.
For example, a researcher might explore coordinated expression within inhibitory neurons and then examine where the resulting module summaries vary across cells. That is an illustrative research question, not a finding about any particular gene or disease. A module or hub ranking alone does not establish a causal mechanism. Keep differential gene expression analysis and network analysis distinct in the analysis plan: they answer different questions.
Install or access
The project distributes hdWGCNA through its GitHub repository under GPLv3. Its official installation instructions recommend a conda environment. Run this block in a terminal with conda available; these are the project’s environment and dependency commands.
conda create -n hdWGCNA -c conda-forge -c bioconda r-base=4.4 mamba
conda activate hdWGCNA
mamba install -c conda-forge -c bioconda r-seurat r-hdf5r r-wgcna r-igraph r-tidyverse r-ggraph r-harmony r-enrichr r-devtools
mamba install -c conda-forge -c bioconda bioconductor-ucell bioconductor-genomicranges bioconductor-geneoverlap
Next open R inside that environment and run the installation sequence below. The documented GitHub command selects the development branch. Record the installed revision alongside package versions when preserving an analysis; a branch name alone is not a fixed software snapshot. The guide to sharing a reproducible conda environment covers the environment record.
install.packages("BiocManager")
BiocManager::install()
devtools::install_github('smorabit/hdWGCNA', ref='dev')
The commands install software, not the study’s input data. Keep the processed Seurat object, analysis script and software record together as separate project artifacts. Name the input explicitly in the script rather than relying on an object left over in an interactive R session.
Step-by-step task: an inhibitory-neuron network
This worked example follows the official single-cell tutorial’s control-cortex dataset and its inhibitory-neuron group, labelled INH. Obtain Zhou_2020_control.rds through the data link in that tutorial and place it in the R working directory. The commands retain the tutorial’s parameter choices so each output can be traced to the selected cellular context. The expression assay is RNA in this example.
- Load the prepared input. The tutorial starts after normalization, variable-feature selection, scaling, dimensionality reduction and cell grouping. Its object contains
Sample,cell_typeand a Harmony reduction. Those names are dataset-specific prerequisites; substitute real metadata and reduction names when adapting the example.
library(Seurat)
library(WGCNA)
library(hdWGCNA)
set.seed(12345)
seurat_obj <- readRDS('Zhou_2020_control.rds')
# Run this update when using the tutorial's v4 object in Seurat v5:
seurat_obj <- SeuratObject::UpdateSeuratObject(seurat_obj)
- Create the named experiment.
SetupForWGCNAestablishes the experiment and selects network features. Its manual permits feature selection arguments to pass toSelectNetworkGenes. Here the tutorial’s fraction rule is retained. Complete any intended Seurat subsetting before setup: the tutorial does not support subsetting afterward.
seurat_obj <- SetupForWGCNA(
seurat_obj,
gene_select = "fraction",
fraction = 0.05,
wgcna_name = "tutorial"
)
The experiment name identifies an analysis stored within the Seurat object. The setup manual also permits an existing experiment’s metacell object to be reused through metacell_location. For a project with several analyses, record which experiment owns each network and whether aggregation was shared; otherwise similarly named outputs can become difficult to distinguish.
- Aggregate within sample and cell type.
MetacellsByGroupsuses the selected reduction to find neighboring cells within metadata-defined groups. The sample grouping prevents aggregation across biological samples. Normalize the aggregated expression before using it for the network.
seurat_obj <- MetacellsByGroups(
seurat_obj = seurat_obj,
group.by = c("cell_type", "Sample"),
reduction = 'harmony',
k = 25,
max_shared = 10,
ident.group = 'cell_type'
)
seurat_obj <- NormalizeMetacells(seurat_obj)
The metacell manual distinguishes the neighborhood size, overlap allowance and minimum cell count per group. These controls do different jobs: k sets the number of neighbors aggregated, max_shared limits sharing between metacells, and min_cells excludes undersized groups. The example’s settings are not universal recommendations. Inspect representation within the actual grouping before adapting them.
- Choose the network population and inspect candidate powers.
SetDatExprselects expression for the specified group and uses metacells by default. Here the network is restricted toINH. Run the power sweep and inspect its plots before constructing the network.
seurat_obj <- SetDatExpr(
seurat_obj,
group_name = "INH",
group.by = 'cell_type',
assay = 'RNA',
slot = 'data'
)
seurat_obj <- TestSoftPowers(seurat_obj, networkType = 'signed')
plot_list <- PlotSoftPowers(seurat_obj)
patchwork::wrap_plots(plot_list, ncol = 2)
power_table <- GetPowerTable(seurat_obj)
The expression setter also accepts external matrices and pseudobulk objects. Its external matrix convention is samples in rows and genes in columns; it checks genes for zero variance or excessive missingness. Do not assume an arbitrary imported expression table has the required orientation. State the analysis unit before choosing between single-cell, metacell and pseudobulk inputs.
- Construct and inspect the network. The construction manual requires setup, aggregation and normalization, expression selection, and a power test first.
ConstructNetworkdelegates to WGCNA’s network machinery, including topological overlap and Dynamic Tree Cut. This documented call leaves soft-power selection automatic; retain the power table when recording the run.
seurat_obj <- ConstructNetwork(seurat_obj, tom_name = 'INH')
PlotDendrogram(seurat_obj, main = 'INH hdWGCNA Dendrogram')
The construction function exposes tom_outdir and tom_name for matrix storage. Choose an output location appropriate to the project and keep a record of it. Reusing an output name without documenting which analysis produced it makes later comparisons harder to audit.
- Compute cell-level summaries and hub rankings. Calculate module eigengenes, harmonizing by the tutorial’s sample field. Then calculate connectivity within the same cell type used for network construction. Retrieve the results and save the updated object.
seurat_obj <- ModuleEigengenes(seurat_obj, group.by.vars = "Sample")
seurat_obj <- ModuleConnectivity(
seurat_obj,
group.by = 'cell_type',
group_name = 'INH'
)
hMEs <- GetMEs(seurat_obj)
modules <- GetModules(seurat_obj)
hub_df <- GetHubGenes(seurat_obj, n_hubs = 10)
saveRDS(seurat_obj, file = 'hdWGCNA_object.rds')
Output and how to read it
Read module membership, eigengenes and connectivity as different outputs. The downloadable data table below maps their analysis units and extraction points, together with the storage distinction for the topological overlap matrix. It is a cross-reference compiled from the function manuals, tutorial and changelog.
Module eigengenes summarize expression. The ModuleEigengenes manual describes a singular value decomposition of each module’s scaled expression matrix, using its first dimension by default. Harmony can adjust the resulting summaries using group.by.vars; vars.to.regress instead supplies covariates for scaling. These parameters act at different stages. Record both rather than describing every adjustment simply as batch correction.
Connectivity ranks genes relative to modules. The ModuleConnectivity manual defines kME through correlations between gene expression and module eigengenes. It recommends matching the population selected for SetDatExpr. High kME supports a hub ranking within that analysis; it is not a measure of differential-expression significance or proof of regulatory direction. Interpret the ranking with the population and eigengene choice attached.
Assignments can change during connectivity analysis. By default, the function can reassign a gene with negative kME in its original module to the module with its highest kME. The manual attributes this discrepancy to constructing networks on metacells while calculating kME on cells. Record whether reassignment was enabled when comparing an early dendrogram with the final assignment table.
Grey is unassigned. The tutorial excludes the grey category from downstream module interpretation. Preserve the complete assignment table for traceability, but do not present grey as a discovered biological program. Module labels and colors organize an analysis; biological names require additional supporting evidence.
Troubleshooting
Dependency installation fails. The installation page suggests trying another supported package source for a failing dependency, including conda when another installation route fails. For a specific unresolved problem, use the project’s GitHub issues. An informative report should include the exact command and error, software versions and a minimal description of the input structure.
Groups disappear or aggregation fails. Check the metadata columns, reduction name and group sizes against MetacellsByGroups. Its min_cells parameter filters undersized groups. Changing that threshold changes which groups contribute; document the reason for a change instead of silently treating the new network as the same analysis.
Seurat versions disagree. The metacell reference distinguishes Seurat v4’s slot argument from v5’s layer. The changelog records fixes involving v5 metacells and SCTransform eigengenes. Match the installed version to its documentation before changing preprocessing to work around an error.
The saved object cannot recover a TOM. The 0.4.12 changelog adds optional in-object storage through ConstructNetwork(store_tom_in_seurat=TRUE), with a default of FALSE, and introduces SetTOM. It also changes GetTOM to look inside the object before loading a disk file. For the workflow above, preserve the TOM files with the saved object; saving the object alone should not be your assumption about matrix preservation.
For computational reproducibility, retain the input identity, selected features, experiment name, grouping fields, aggregation settings, power diagnostics, network settings and software record. This checklist is an editorial synthesis of the workflow’s dependencies, not an additional hdWGCNA validation procedure.
Free alternatives
Two open-source software routes cover related network tasks. Their official descriptions support the distinctions below. Treat them as alternative analysis implementations, not drop-in replacements for this Seurat-based script.
| Software | Officially described scope | Relationship to this workflow |
|---|---|---|
| WGCNA for R; GPL version 2 or later | Correlation-network construction, module identification, module summaries and associations with sample traits. | The underlying R network toolkit used by hdWGCNA. A direct WGCNA analysis requires you to manage the input matrix and surrounding workflow. |
| PyWGCNA; MIT license | Python weighted correlation networks, module eigengenes, membership measures, trait relationships and comparisons across datasets. | A Python implementation for related network questions. Its own data preparation and documentation replace the R commands shown here. |
Language alone is not the whole comparison. First decide whether the task is discovery of a network, evaluation of an existing gene set, or comparison with another dataset. Then document the chosen input representation and the outputs being compared. Similar-looking module plots do not establish that two software workflows used identical genes, observations or settings.
Sources
- hdWGCNA project overview and installation. Checked 2026-11-14.
- Morabito et al.: hdWGCNA methods paper, Cell Reports Methods, 2023, DOI 10.1016/j.crmeth.2023.100498. Checked 2026-11-14.
- Official hdWGCNA single-cell tutorial and example-data link. Checked 2026-11-14.
- SetupForWGCNA reference and MetacellsByGroups reference. Checked 2026-11-14.
- SetDatExpr reference and ConstructNetwork reference. Checked 2026-11-14.
- ModuleEigengenes reference and ModuleConnectivity reference. Checked 2026-11-14.
- hdWGCNA changelog. Checked 2026-11-14.
- CRAN: WGCNA and Mortazavi Lab: PyWGCNA. Checked 2026-11-14.
Data: hdWGCNA output units and retrieval checkpoints
An original cross-reference of output units, retrieval commands and interpretation boundaries, compiled from the official hdWGCNA single-cell tutorial, function references and changelog. These are documented software artifacts, not measured biological results.
| Output artifact | Unit or organization | Retrieval command | Interpretation checkpoint | Source URLs |
|---|---|---|---|---|
| Module assignment table | Gene-level assignments | GetModules(seurat_obj) | Contains gene_name, module and color; kME columns are added after connectivity calculation. | https://smorabit.github.io/hdWGCNA/articles/basic_tutorial.html |
| Module eigengenes | Cells in rows; modules in columns | GetMEs(seurat_obj) | Retrieves harmonized eigengenes by default; the eigengene is the first decomposition dimension by default. | https://smorabit.github.io/hdWGCNA/articles/basic_tutorial.html ; https://smorabit.github.io/hdWGCNA/reference/ModuleEigengenes.html |
| Hub-gene table | Top-ranked genes within each module | GetHubGenes(seurat_obj, n_hubs = 10) | Ranks genes by kME, a correlation with module eigengenes; this is not a differential-expression significance statistic. | https://smorabit.github.io/hdWGCNA/articles/basic_tutorial.html ; https://smorabit.github.io/hdWGCNA/reference/ModuleConnectivity.html |
| Topological overlap matrix | Square gene-by-gene matrix | GetTOM(seurat_obj) | Network construction writes a TOM to disk. Version 0.4.12 adds optional in-object storage, default FALSE; GetTOM checks that storage before disk. | https://smorabit.github.io/hdWGCNA/articles/basic_tutorial.html ; https://smorabit.github.io/hdWGCNA/reference/ConstructNetwork.html ; https://smorabit.github.io/hdWGCNA/news/index.html |
Sources
- hdWGCNA single-cell tutorial (accessed 2026-11-14)
- ModuleEigengenes reference (accessed 2026-11-14)
- ModuleConnectivity reference (accessed 2026-11-14)
- ConstructNetwork reference (accessed 2026-11-14)
- hdWGCNA changelog (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







