How aertslab/scenicplus works
1. What this repo is
SCENIC+ is a Python library for inferring single-cell gene regulatory networks from multiomic data, typically combining scRNA-seq and scATAC-seq. The repository is organized as an analysis toolkit plus a command-line pipeline and Snakemake workflow.
2. Primary data model boundary
The central architectural boundary is around a SCENIC+ analysis object built from cell-by-gene expression and cell-by-peak accessibility inputs. The codebase includes scenicplus_class.py and scenicplus_mudata.py, which strongly suggest that AnnData/MuData-style containers are the main interchange format between pipeline stages.
3. Input wrangling layer
data_wrangling/ adapts upstream single-cell outputs into the SCENIC+ workflow. It contains helpers for:
- adata_cistopic_wrangling.py for integrating AnnData with cisTopic-style accessibility results,
- cistarget_wrangling.py for importing motif/enrichment results,
- gene_search_space.py for defining candidate enhancer-to-gene search regions.
This layer is where raw or preprocessed scRNA/scATAC artifacts are normalized into a common analysis-ready structure.
4. Core regulatory inference pipeline
The main inference path is split across several top-level modules:
- TF_to_gene.py for linking transcription factors to target genes,
- enhancer_to_gene.py for linking accessible enhancers to genes,
- triplet_score.py for combining TF, enhancer, and gene evidence into higher-confidence regulatory triplets,
- eregulon_enrichment.py for scoring enriched regulons/eGRNs.
This is the conceptual heart of the system: from separate evidence sources to inferred TF–enhancer–gene relationships.
5. GRN construction subsystem
grn_builder/ contains the machinery for assembling network modules and enrichment-based GRN logic. Files like modules.py, gsea.py, and gsea_approach.py indicate support for gene set enrichment-driven grouping and scoring. This layer likely turns raw triplet evidence into higher-level regulons and network modules.
6. Quality control and filtering
The preprocessing/ and regulon_qc/ packages provide filtration and assessment steps before and after network inference. filtering.py handles data cleanup or thresholding, while quality_metrics.py computes metrics for regulon or network quality. These are the main guardrails around noisy single-cell inputs and unstable inferred regulons.
7. Analysis utilities around the inferred network
Several modules operate on the final GRN or on derived cell-state scores:
- RSS.py for regulon specificity scoring,
- BASCA.py, differentiation_potential.py, and simulation.py for downstream interpretive analyses,
- networks.py for network-level representations,
- loom.py for export/import in loom-compatible form.
These are downstream consumers of the core SCENIC+ results.
8. Visualization layer
plotting/ is a separate presentation boundary for network and multiomic outputs. It includes:
- coverageplot.py for chromatin/accessibility tracks,
- dotplot.py for summary expression/accessibility plots,
- correlation_plot.py for association visualizations,
- grn_plot.py for network figures.
The cytoscape_styles/SCENIC+.xml asset indicates intended export into Cytoscape for interactive network visualization.
9. Command-line interface
cli/ exposes the package as a runnable application rather than only a library. scenicplus.py, commands.py, and gfx.py define CLI entry points and subcommands, making the pipeline usable from the shell and enabling scripted workflows.
10. Workflow orchestration
snakemake/ contains a Snakefile and config.yaml, so the repository also supports a reproducible, file-driven pipeline execution model. This is the orchestration boundary for end-to-end runs, especially when multiple preprocessing, inference, and export steps must be chained.
11. External tool integration
wrappers/run_pycistarget.py and the tangram/ package show explicit integration points with external single-cell ecosystem tools. The README also frames SCENIC+ as building on pycisTarget and pycisTopic. Architecturally, SCENIC+ is not a standalone monolith; it coordinates outputs from specialized motif, topic, and mapping tools.
12. Documentation and example artifacts
docs/ and notebooks/ provide worked examples and tutorial-driven documentation, including human cerebellum workflows and perturbation simulation. These are not core runtime components, but they are important for understanding the intended pipeline sequence and the shape of intermediate data artifacts.
13. Packaging and deployment
The repo is packaged as a standard Python project (pyproject.toml, requirements.txt, requirements.in) and includes Dockerfiles for containerized execution. That means the architecture is designed to be deployable both as a local Python package and as a reproducible containerized analysis environment.
14. Overall data flow
The high-level flow is: scRNA/scATAC inputs and external enrichment results are wrangled into SCENIC+ data structures; candidate gene search spaces are computed; TF-to-gene and enhancer-to-gene relationships are inferred; triplets are scored and assembled into regulons/networks; QC and specificity metrics are computed; and the final outputs are visualized, exported, or used in downstream simulation/analysis.
Main entry points: scenicplus_class.py SCENIC+ object · Snakefile Snakemake · triplet_score.py Triplet scoring · scenicplus_mudata.py MuData bridge
Components 25
Core data model
SCENIC+ analysis containers and shared state boundary.
- SCENIC+ object · Primary analysis object for SCENIC+ state and results.
src/scenicplus/scenicplus_class.py - MuData bridge · MuData-style interface for multimodal SCENIC+ data.
src/scenicplus/scenicplus_mudata.py
Inference pipeline
Wrangling, regulatory inference, triplet scoring, and GRN assembly.
- AnnData wrangling · Converts scRNA/scATAC artifacts into SCENIC+ inputs.
src/scenicplus/data_wrangling/adata_cistopic_wrangling.py - cistarget import · Loads and normalizes motif/enrichment results.
src/scenicplus/data_wrangling/cistarget_wrangling.py - Search space · Defines candidate enhancer-to-gene search regions.
src/scenicplus/data_wrangling/gene_search_space.py - TF to gene · Links transcription factors to target genes.
src/scenicplus/TF_to_gene.py - Enhancer to gene · Links accessible enhancers to candidate genes.
src/scenicplus/enhancer_to_gene.py - Triplet scoring · Combines TF, enhancer, and gene evidence into triplets.
src/scenicplus/triplet_score.py - eRegulon enrich · Scores enriched regulons and eGRN activity.
src/scenicplus/eregulon_enrichment.py - GRN modules · Builds higher-level regulatory modules from evidence.
src/scenicplus/grn_builder/modules.py - GSEA approach · Enrichment-driven module construction and scoring.
src/scenicplus/grn_builder/gsea_approach.py - GSEA helpers · Supporting gene set enrichment logic for GRN building.
src/scenicplus/grn_builder/gsea.py
Analysis and output
QC, downstream analyses, visualization, and export.
- Filtering · Data cleanup and thresholding before inference.
src/scenicplus/preprocessing/filtering.py - Quality metrics · Computes regulon and network quality measures.
src/scenicplus/regulon_qc/quality_metrics.py - RSS · Regulon specificity scoring across cell states.
src/scenicplus/RSS.py - Networks · Network-level representation of inferred GRNs.
src/scenicplus/networks.py - Plotting · Plots coverage, correlation, dot, and GRN figures.
src/scenicplus/plotting/grn_plot.py - Loom export · Loom-compatible serialization and interoperability.
src/scenicplus/loom.py - Simulation · Perturbation or differentiation-style downstream analyses.
src/scenicplus/simulation.py - BASCA · Additional downstream interpretive analysis routines.
src/scenicplus/BASCA.py - Diff potential · Estimates differentiation potential from derived scores.
src/scenicplus/differentiation_potential.py
Runtime and orchestration
CLI and Snakemake entry points for execution.
- CLI · Shell entry points and subcommands for running SCENIC+.
src/scenicplus/cli/scenicplus.py - Snakemake · File-driven workflow orchestration for end-to-end runs.
src/scenicplus/snakemake/Snakefile - pycisTarget · Wrapper around external motif-enrichment tooling.
src/scenicplus/wrappers/run_pycistarget.py - Tangram · Projection/mapping integration with Tangram utilities.
src/scenicplus/tangram/projections.py
Connections 28
- AnnData wrangling → MuData bridge: normalize inputs · Builds analysis-ready multimodal state from single-cell inputs.
- cistarget import → MuData bridge: add motif data · Imports enrichment evidence into the shared analysis container.
- Search space → Enhancer to gene: candidate regions · Provides searchable enhancer-to-gene regions.
- MuData bridge → Filtering: preprocess · Container-level inputs are filtered and cleaned before inference.
- Filtering → TF to gene: clean inputs · Preprocessed data feeds TF-target inference.
- Filtering → Enhancer to gene: clean inputs · Preprocessed data feeds enhancer-target inference.
- pycisTarget → cistarget import: import results · External motif results are wrapped and normalized.
- TF to gene → Triplet scoring: TF evidence · TF-to-gene links contribute to triplet scoring.
- Enhancer to gene → Triplet scoring: enhancer evidence · Enhancer-to-gene links contribute to triplet scoring.
- Triplet scoring → eRegulon enrich: score regulons · Triplet evidence is aggregated into enriched regulons.
- Triplet scoring → GRN modules: build modules · Triplet evidence seeds higher-level GRN modules.
- GSEA helpers → GSEA approach: support scoring · Shared enrichment logic supports module construction.
- GSEA approach → GRN modules: assemble modules · Enrichment-driven approach organizes regulatory modules.
- GRN modules → SCENIC+ object: store network · Constructed modules are persisted in the main analysis object.
- eRegulon enrich → SCENIC+ object: store scores · Enrichment outputs are attached to the SCENIC+ object.
- SCENIC+ object → Quality metrics: qc · Network quality is evaluated on inferred results.
- SCENIC+ object → RSS: specificity · Regulon specificity is computed from analysis state.
- SCENIC+ object → Networks: derive graph · Network views are derived from the analysis object.
- Networks → Plotting: visualize · Network representations feed plotting routines.
- SCENIC+ object → Loom export: export · Analysis state can be serialized for interoperability.
- SCENIC+ object → Simulation: simulate · Downstream perturbation analyses use the inferred network state.
- SCENIC+ object → BASCA: analyze · Additional downstream interpretation operates on the same state.
- SCENIC+ object → Diff potential: estimate · Derived regulon activity supports differentiation potential analysis.
- CLI → Snakemake: orchestrate · Command-line entry points can launch workflow execution.
- Snakemake → AnnData wrangling: stage data · Workflow begins with input wrangling and normalization.
- Snakemake → TF to gene: run inference · Workflow drives the core inference stages.
- Snakemake → Plotting: publish outputs · Workflow can generate figures and deliverables.
- Tangram → MuData bridge: map cells · Projection utilities connect mapping outputs to the shared data model.