Skip to main content
v2026.11,986 entries · CC-BY 4.0

hdWGCNA: Single-Cell Network Analysis in R

Build an hdWGCNA network from a prepared Seurat object, follow the official research example, and distinguish module summaries from hub-gene rankings.

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.

  1. Load the prepared input. The tutorial starts after normalization, variable-feature selection, scaling, dimensionality reduction and cell grouping. Its object contains Sample, cell_type and 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)
  1. Create the named experiment. SetupForWGCNA establishes the experiment and selects network features. Its manual permits feature selection arguments to pass to SelectNetworkGenes. 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.

  1. Aggregate within sample and cell type. MetacellsByGroups uses 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.

  1. Choose the network population and inspect candidate powers. SetDatExpr selects expression for the specified group and uses metacells by default. Here the network is restricted to INH. 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.

  1. Construct and inspect the network. The construction manual requires setup, aggregation and normalization, expression selection, and a power test first. ConstructNetwork delegates 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.

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

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.

hdWGCNA output units and retrieval checkpoints
Output artifactUnit or organizationRetrieval commandInterpretation checkpointSource URLs
Module assignment tableGene-level assignmentsGetModules(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 eigengenesCells in rows; modules in columnsGetMEs(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 tableTop-ranked genes within each moduleGetHubGenes(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 matrixSquare gene-by-gene matrixGetTOM(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

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about hdWGCNA: Single-Cell Network Analysis in R

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →