NetPerturb 🧬

MCBLab/NetPerturb is a scalable Nextflow pipeline designed to infer Gene Regulatory Networks (GRNs) and calculate single-cell expression ranking perturbation scores using the scRank algorithm.

Previous GRN tools are often difficult to scale for large Single-Cell RNA-seq (scRNA-seq) datasets. In this context, NetPerturb was built to enable high-throughput perturbation scoring in a user-friendly, parallelized, and computationally effective way. The pipeline uses Singularity containers, making installation trivial and results highly reproducible across high-performance computing (HPC) environments.

Pipeline Summary

The workflow executes the following core modules:

1. Object Parsing and Downsampling (DOWNSAMPLE)

This is the initial step of the process. It ingests a fully processed Seurat object (.rds) and identifies the user-defined metadata column containing the cell identities (e.g., cell types or clones). To ensure statistical robustness and equitable GRN inference, it randomly downsamples the cells from each identity to a specified maximum number (--n_cells), balancing the computational load.

2. Network Inference (GENIE3, SCTENIFOLDNET, SCRANK)

This is the heavy-lifting computational core. For each downsampled cellular identity, the pipeline infers a gene regulatory network using the method selected with --network: genie3 runs GENIE3, sctnet runs SCTENIFOLDNET, and scrank uses the scRank network strategy. Each method returns regulatory interaction weights between genes for each cell state.

3. Perturbation Scoring (RANK_SCORE)

Using the list of target genes (--target) provided by the user, this module extracts the specific regulatory weight of the targets from the GENIE3 output. It calculates the perturbation score, which reflects how much the network relies on the specific target gene within that specific cell state.

4. Consolidate Results (MERGE)

This final step collects the perturbation scores from all parallel GENIE3 tasks and merges them into a single, clean text file, ready for downstream visualization.

Quick Start

1. Install Nextflow (>=22.10.1).
2. Install Singularity (highly recommended for full pipeline reproducibility).
3. Start running your analysis!

# Quick example
nextflow run netperturb/main.nf \
  profile test,singularity

# Example with all parameters
nextflow run netperturb/main.nf \
  --obj /path/to/your/seurat_object.rds \
  --column clone_annotation \
  --species human \
  --n_cells 3000 \
  --binding antagonist \
  --n_cores 32 \
  --target /path/to/targets.txt \
  --network genie3 \
  --outdir results \
  -profile singularity

Inputs and References

NetPerturb requires the following main parameters:

--obj: Path to a fully processed Seurat object (.rds or compatible serialized object) containing normalized RNA assays and metadata annotations.

--column: Metadata column in the Seurat object that defines the cellular identities to compare, such as cell type, cluster, treatment group, clone, or phenotype.

--species: Species used by scRank when building and scoring regulatory networks. Accepted values depend on the underlying scRank annotation support, commonly human or mouse.

--target: Path to a text file containing the target genes to score. Each line should contain one target entry. If multiple genes should be evaluated together as one perturbation set, separate them with semicolons, for example Stfa1;Mpo. Max number is two targets at same time.

# Example
Brd4
Cstdc5
Stfa1;Mpo

--network: Network inference method to use. Supported values are genie3, sctnet, and scrank.

--n_cells: Maximum number of cells to keep per cellular identity during downsampling. If an identity has fewer cells than this value, the pipeline uses all available cells for that identity.

--binding: Perturbation mode passed to the scoring step, for example antagonist or agonist.

--n_cores: Number of CPU cores requested for parallelizable network inference and scoring steps.

--outdir: Directory where the final results and pipeline reports will be written. Defaults to results.

Outputs

If successfully run, the workflow will generate its primary output in the specified --outdir:

rank_scores/perbscore_all_targets.txt: A consolidated table containing the cell identity (cell_type), the evaluated gene (target), and its final regulatory importance (perb_score).

# Example
cell_type	target	binding	perb_score
sensitive	Stfa1;Mpo	antagonist	1.38837233985176e-06
resistant	Stfa1;Mpo	antagonist	3.86382149842044e-06
sensitive	Brd4	antagonist	1.5395821350262e-06
resistant	Brd4	antagonist	1.61320913209275e-06
sensitive	Cstdc5	antagonist	1.30868421341405e-06
resistant	Cstdc5	antagonist	2.91128461301128e-06

Other intermediate files (such as split matrices and raw GENIE3 weights) are temporarily stored in the work directory and can be retained or discarded based on standard Nextflow cache management.

Credits

NetPerturb is developed and maintained by the Marques-Coelho Bioinformatics Lab(MCBLab).

Citations

If you use this pipeline in your research, please cite:

...