pySCENIC: Single-Cell Regulatory Network Guide

Q: Does pySCENIC require normalized expression data or raw counts?

The co-expression inference step ( pyscenic grn ) performs robustly on either raw unique molecular identifier (UMI) counts or library-size normalized counts (e.g., CPM or counts per 10,000). However, the AUCell ranking step calculates rankings per cell across expressed genes, which is inherently invariant to linear library size normalizations.

pySCENIC is a high-performance Python implementation of the SCENIC (Single-Cell rEgulatory Network Inference and Clustering) pipeline developed by the Aerts Laboratory at the VIB-KU Leuven Center for Microbiology. Built to infer transcription factors, gene regulatory networks (GRNs), and cellular states from single-cell RNA sequencing (scRNA-seq) data, pySCENIC scales computational regulatory biology to datasets encompassing hundreds of thousands of cells.

What it is used for in research

In single-cell transcriptomics, standard clustering methods group cells based on global transcriptomic similarities, which can be influenced by technical noise, cell cycle phase, or sequencing batch effects. pySCENIC resolves these limitations by mapping gene expression profiles directly to the underlying transcription factor-driven regulatory architecture.

SCENIC Analysis in Single-Cell Biology

A standard SCENIC analysis reconstructs transcriptional networks into functional units known as regulons. A regulon consists of a transcription factor (TF) and its direct, co-expressed target genes validated through genomic cis-regulatory motif discovery. By requiring that candidate target genes possess direct binding motifs for the transcription factor, pySCENIC filters out indirect correlations and false-positive associations typical of naive co-expression methods.

Cellular State Identification via Single-Cell Regulatory Networks

When analyzing scenic single cell and scenic single-cell datasets, researchers use regulon activity scores rather than individual gene expression values to classify cell types, trace differentiation trajectories, and identify master regulators of disease phenotypes. For example, in oncology and developmental biology, pySCENIC identifies lineage-defining transcription factors driving tumor subpopulation heterogeneity or cellular reprogramming. Furthermore, combining pySCENIC transcriptomic regulons with chromatin accessibility datasets—such as those analyzed with ArchR for single-cell ATAC-seq—provides an integrated epigenetic and transcriptional view of cellular identity.

Install or access (official source only)

pySCENIC is distributed through the Python Package Index (PyPI) and as containerized images maintained on Docker Hub. The software requires Python 3.8 to 3.10 and relies on numerical and bioinformatics dependencies including arboreto, ctxcore, pyarrow, loompy, and scipy.

Package Installation via pip

Install pySCENIC directly into an isolated virtual environment or conda environment using pip:

pip install pyscenic

For accelerated cis-regulatory motif ranking, ensure that ctxcore >= 0.2.0 and pyarrow >= 8.0.0 are installed to support Feather v2 format database queries.

Containerized Execution (Docker and Singularity)

For high-performance computing (HPC) clusters, the official pre-built container from the Aerts Lab provides a fully configured environment containing all C-extensions and library dependencies:

# Pull official container via Singularity
singularity pull docker://aertslab/pyscenic:latest

# Or run interactively with Docker
docker run --rm -it -v $(pwd):/data aertslab/pyscenic:latest pyscenic --help

Downloading cisTarget Databases

To run motif enrichment and regulon pruning, download the organism-specific cisTarget ranking databases and motif annotation tables from the official Aerts Lab resource repository (https://resources.aertslab.org/cistarget/). For human genome build hg38, download the following ranking databases and annotation tables:

Motif rankings (10 kb around TSS): hg38__refseq-r80__10kb_up_and_down_tss.mc9nr.genes_vs_motifs.rankings.feather
Motif rankings (500 bp around TSS): hg38__refseq-r80__500bp_up_and_100bp_down_tss.mc9nr.genes_vs_motifs.rankings.feather
Motif annotations table: motifs-v9-nr.hgnc-m0.001-o0.0.tbl
Transcription factor list: hs_hgnc_tfs.txt (curated list of human transcription factor gene symbols)

For researchers evaluating transcription factor binding preferences, databases such as the JASPAR transcription factor binding database document the position weight matrices (PWMs) underlying these pre-computed motif libraries.

Step-by-step task

The pySCENIC workflow consists of three primary command-line steps executed in sequence: co-expression module inference (grn), cis-regulatory motif pruning (ctx), and cellular regulon activity scoring (aucell).

1. Prepare Input Expression Matrix

pySCENIC accepts single-cell count matrices in .loom, .csv, or .h5ad formats. A Loom file contains filtered single-cell expression data with genes along rows and cell barcodes along columns. Underlying biological data matrices rely heavily on h5py HDF5 file handling within Python pipelines.

2. Infer Co-expression Modules (GRNBoost2)

The pyscenic grn command derives co-expression modules between transcription factors and candidate target genes using the Arboreto gradient boosting algorithm (GRNBoost2):

pyscenic grn 
    expression_filtered.loom 
    hs_hgnc_tfs.txt 
    --output adjacencies.tsv 
    --method grnboost2 
    --num_workers 16 
    --sparse 
    --seed 42

The --sparse flag conserves system memory during matrix covariance calculations, and --num_workers specifies CPU parallelism.

3. Prune Indirect Targets with cisTarget Motif Analysis

The pyscenic ctx command evaluates whether candidate targets in each co-expression module are significantly enriched for cis-regulatory motifs of the corresponding transcription factor, retaining only high-confidence direct targets:

pyscenic ctx 
    adjacencies.tsv 
    databases/hg38__refseq-r80__10kb_up_and_down_tss.mc9nr.genes_vs_motifs.rankings.feather 
    databases/hg38__refseq-r80__500bp_up_and_100bp_down_tss.mc9nr.genes_vs_motifs.rankings.feather 
    --annotations_fname databases/motifs-v9-nr.hgnc-m0.001-o0.0.tbl 
    --expression_mtx_fname expression_filtered.loom 
    --output regulons.csv 
    --mask_dropouts 
    --mode multiprocessing 
    --num_workers 16

The --mask_dropouts parameter excludes zero-count dropout events when calculating correlation signs between transcription factors and target genes.

4. Quantify Regulon Activity per Cell (AUCell)

The pyscenic aucell command scores the activity of each discovered regulon across individual cells by computing the Area Under the Recovery Curve (AUCell) against ranked gene expression:

pyscenic aucell 
    expression_filtered.loom 
    regulons.csv 
    --output scenic_integrated.loom 
    --num_workers 16 
    --seed 42

5. Downstream Analysis in Python (Scanpy Integration)

Load the generated Loom file into Scanpy to extract regulon activity scores and project them onto single-cell embeddings:

import scanpy as sc
import loompy as lp

# Load regulon activity matrix from output loom file
with lp.connect("scenic_integrated.loom", mode="r") as ds:
    auc_matrix = ds.ca["RegulonsAUC"]
    cell_ids = ds.ca["CellID"]
    regulon_names = ds.ra["Gene"]

# Integrate with AnnData object for visualization
adata = sc.read_h5ad("expression_filtered.h5ad")
adata.obsm["X_regulon_auc"] = auc_matrix

# Plot regulon activity on UMAP
sc.pl.umap(adata, color=["X_regulon_auc"], title="Regulon Activity")

Output and how to read it

The pySCENIC pipeline generates structured outputs corresponding to each analytical phase:

Adjacencies table (adjacencies.tsv): A tab-separated file listing transcription factor (TF), target gene (target), and calculated importance weight (importance). High importance scores indicate strong predictive power in the GRNBoost2 regression model.
Regulon definitions (regulons.csv): Lists verified regulons with associated transcription factors, enriched motif identifiers, Normalized Enrichment Scores (NES ≥ 3.0), and target gene symbols. Regulons appended with (+) denote target genes positively correlated with TF expression (activation), whereas (-) denotes negatively correlated repression targets.
Loom dataset (scenic_integrated.loom): An updated Loom container storing the complete cell-by-regulon AUC matrix under the column attribute RegulonsAUC. Each value represents a continuous score between 0.0 and 1.0 reflecting the proportion of regulon genes actively expressed in that cell.

Troubleshooting

Running pySCENIC on large genomic datasets involves high computational demands. Common issues and their resolutions include:

1. High Memory Consumption and Out-of-Memory (OOM) Errors (Exit Code 137)

During the pyscenic ctx step, querying multi-gigabyte Feather ranking databases across numerous workers can exhaust node memory. To prevent HPC batch crashes:

Allocate at least 8 GB to 16 GB of RAM per worker core in your job submission script.
Pass --mode multiprocessing rather than running Dask cluster distributed mode to reduce serialization overhead.
Use the --sparse flag during the grn step to prevent expanding sparse single-cell matrices into dense memory arrays.

2. Feather Database Format Incompatibility

Older pySCENIC scripts using Feather v1 databases fail when paired with modern pyarrow libraries, producing ArrowInvalid errors. Download updated Feather v2 format files (labeled .genes_vs_motifs.rankings.feather) from the official Aerts Lab repository and verify pyarrow >= 8.0.0.

3. Zero Regulons Identified or Missing Transcription Factors

If pySCENIC completes the ctx step without producing regulons, verify gene symbol nomenclature. Gene names must match the case convention of the species database: human gene symbols must be fully capitalized (e.g., SOX2, GATA3), whereas mouse gene symbols must use title case (e.g., Sox2, Gata3). Case mismatches cause the TF list to fail matching the ranking database.

4. Loom Matrix Orientation Mismatch

If pyscenic grn throws attribute errors regarding cell or gene dimensions, verify the row and column attributes in your Loom file. By default, pySCENIC expects genes as rows (attribute Gene) and cells as columns (attribute CellID). If your matrix is inverted, apply the --transpose yes command argument.

Free alternatives

Several open-source computational tools provide gene regulatory network inference and transcription factor activity scoring in single-cell transcriptomics. The table below compares pySCENIC against complementary alternatives:

Tool	Network Source	Primary Input Data	Main Analytical Purpose	Computational Footprint
pySCENIC	De novo co-expression (GRNBoost2) plus cisTarget motif pruning	scRNA-seq count matrix + TF list + Feather database	Unsupervised discovery of novel, context-specific regulons and cellular states	Moderate to High; requires multi-core CPU and 16+ GB RAM for motif scanning
decoupleR	Curated prior-knowledge networks (CollecTRI, DoRothEA)	scRNA-seq or spatial transcriptomics count matrix	Rapid scoring of known TF and pathway activities via fast linear models	Low; executes in seconds via efficient matrix multiplication
CellOracle	Multi-omic base network (scATAC-seq peaks) + ridge regression	Paired scRNA-seq and scATAC-seq datasets	In silico transcription factor perturbation and cell fate transition simulation	High; requires chromatin peak modeling and iterative network simulations

For researchers seeking rapid transcription factor activity scoring without the heavy computational burden of de novo network inference, consult the decoupler omics activity inference guide to explore prior-knowledge scoring frameworks.

FAQ

What is the difference between pySCENIC and SCENIC in R?

pySCENIC is the Python implementation of SCENIC. It replaces the R implementation’s GENIE3 random forest algorithm with GRNBoost2 (gradient boosted trees via Arboreto) and optimizes cis-regulatory motif ranking using C++ bindings in ctxcore. This enables pySCENIC to run significantly faster and scale to much larger cell counts while integrating directly with Python-based scRNA-seq packages like Scanpy and AnnData.

Can pySCENIC be used on single-cell ATAC-seq data?

Standard pySCENIC is designed specifically for single-cell RNA-seq expression data. To integrate single-cell ATAC-seq chromatin accessibility data directly with transcription factor networks, researchers use SCENIC+, an advanced multi-omic pipeline developed by the same laboratory that links candidate enhancers directly to target genes.

Does pySCENIC require normalized expression data or raw counts?

The co-expression inference step (pyscenic grn) performs robustly on either raw unique molecular identifier (UMI) counts or library-size normalized counts (e.g., CPM or counts per 10,000). However, the AUCell ranking step calculates rankings per cell across expressed genes, which is inherently invariant to linear library size normalizations.

How many cells can pySCENIC analyze?

With multi-threading and modern multi-core workstations, pySCENIC routinely processes datasets containing 50,000 to 200,000 single cells. Datasets exceeding 500,000 cells can be analyzed efficiently on HPC clusters using containerized workflows or automated Nextflow pipelines (such as VSN-Pipelines).

Sources (official docs)

Van de Sande, B., Flerin, C., Davie, K., De Waegeneer, M., Hulselmans, G., Aibar, S., Seurinck, R., Saelens, W., Cannoodt, R., Rouchon, Q., Verfaillie, A., De Maeyer, D., Sanchez-Guzman, D., Choi, C., Montagne, N., Byers, D., Saeys, Y., & Aerts, S. (2020). A scalable SCENIC workflow for single-cell gene regulatory network analysis. Nature Protocols, 15(7), 2247–2276. https://doi.org/10.1038/s41596-020-0336-2 (Read: 2026-11-10)
Aibar, S., González-Blas, C. B., Moerman, T., Huynh-Thu, V. A., Imrichova, H., Hulselmans, G., Rambow, F., Marine, J. C., Geurts, P., Aerts, J., van den Oord, J., Atak, Z. K., Wessels, L. F. A., & Aerts, S. (2017). SCENIC: single-cell regulatory network inference and clustering. Nature Methods, 14(11), 1083–1086. https://doi.org/10.1038/nmeth.4463 (Read: 2026-11-10)
pySCENIC Official Documentation (Read the Docs). Aerts Laboratory, VIB-KU Leuven Center for Microbiology. https://pyscenic.readthedocs.io/en/latest/ (Read: 2026-11-10)
pySCENIC Source Code Repository. GitHub: Aerts Lab. https://github.com/aertslab/pySCENIC (Read: 2026-11-10)
Aerts Lab cisTarget Databases Resource Repository. VIB.AI and VIB-KU Leuven. https://resources.aertslab.org/cistarget/ (Read: 2026-11-10)