# aertslab/scenicplus architecture

> Architecture diagram of the GitHub repository aertslab/scenicplus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aertslab/scenicplus
- Repository: https://github.com/aertslab/scenicplus

## Overview

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: [`src/scenicplus/scenicplus_class.py`](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_class.py) (SCENIC+ object), [`src/scenicplus/snakemake/Snakefile`](https://github.com/aertslab/scenicplus/tree/main/src/scenicplus/snakemake/Snakefile) (Snakemake), [`src/scenicplus/triplet_score.py`](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/triplet_score.py) (Triplet scoring), [`src/scenicplus/scenicplus_mudata.py`](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_mudata.py) (MuData bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core data model"]
  node_scenicplus_class[("SCENIC+ object<br/>analysis container")]
  node_scenicplus_mudata[("MuData bridge<br/>container adapter")]
end

subgraph group_group_pipeline["Inference pipeline"]
  node_adata_wrangling["AnnData wrangling<br/>input adapter"]
  node_cistarget_wrangling["cistarget import<br/>motif adapter"]
  node_gene_search_space["Search space<br/>region model"]
  node_tf_to_gene["TF to gene<br/>regulatory inference<br/>[TF_to_gene.py]"]
  node_enhancer_to_gene["Enhancer to gene<br/>regulatory inference"]
  node_triplet_score["Triplet scoring<br/>evidence integrator<br/>[triplet_score.py]"]
  node_eregulon_enrichment["eRegulon enrich<br/>scoring"]
  node_grn_modules["GRN modules<br/>network assembly<br/>[modules.py]"]
  node_gsea_approach["GSEA approach<br/>module scoring<br/>[gsea_approach.py]"]
  node_gsea["GSEA helpers<br/>enrichment utils<br/>[gsea.py]"]
end

subgraph group_group_analysis["Analysis and output"]
  node_filtering["Filtering<br/>preprocessing<br/>[filtering.py]"]
  node_quality_metrics["Quality metrics<br/>qc<br/>[quality_metrics.py]"]
  node_rss["RSS<br/>specificity scoring<br/>[RSS.py]"]
  node_networks["Networks<br/>network view<br/>[networks.py]"]
  node_plotting["Plotting<br/>visualization<br/>[grn_plot.py]"]
  node_loom["Loom export<br/>export/import<br/>[loom.py]"]
  node_simulation["Simulation<br/>downstream analysis<br/>[simulation.py]"]
  node_basca["BASCA<br/>downstream analysis<br/>[BASCA.py]"]
  node_differentiation_potential["Diff potential<br/>downstream analysis"]
end

subgraph group_group_runtime["Runtime and orchestration"]
  node_cli["CLI<br/>command interface<br/>[scenicplus.py]"]
  node_snakemake["Snakemake<br/>workflow"]
  node_pycistarget_wrapper["pycisTarget<br/>external integration<br/>[run_pycistarget.py]"]
  node_tangram["Tangram<br/>external integration<br/>[projections.py]"]
end

node_adata_wrangling -->|"normalize inputs"| node_scenicplus_mudata
node_cistarget_wrangling -->|"add motif data"| node_scenicplus_mudata
node_gene_search_space -->|"candidate regions"| node_enhancer_to_gene
node_scenicplus_mudata -->|"preprocess"| node_filtering
node_filtering -->|"clean inputs"| node_tf_to_gene
node_filtering -->|"clean inputs"| node_enhancer_to_gene
node_pycistarget_wrapper -->|"import results"| node_cistarget_wrangling
node_tf_to_gene -->|"TF evidence"| node_triplet_score
node_enhancer_to_gene -->|"enhancer evidence"| node_triplet_score
node_triplet_score -->|"score regulons"| node_eregulon_enrichment
node_triplet_score -->|"build modules"| node_grn_modules
node_gsea -->|"support scoring"| node_gsea_approach
node_gsea_approach -->|"assemble modules"| node_grn_modules
node_grn_modules -->|"store network"| node_scenicplus_class
node_eregulon_enrichment -->|"store scores"| node_scenicplus_class
node_scenicplus_class -->|"qc"| node_quality_metrics
node_scenicplus_class -->|"specificity"| node_rss
node_scenicplus_class -->|"derive graph"| node_networks
node_networks -->|"visualize"| node_plotting
node_scenicplus_class -->|"export"| node_loom
node_scenicplus_class -->|"simulate"| node_simulation
node_scenicplus_class -->|"analyze"| node_basca
node_scenicplus_class -->|"estimate"| node_differentiation_potential
node_cli -->|"orchestrate"| node_snakemake
node_snakemake -->|"stage data"| node_adata_wrangling
node_snakemake -->|"run inference"| node_tf_to_gene
node_snakemake -->|"publish outputs"| node_plotting
node_tangram -->|"map cells"| node_scenicplus_mudata

click node_scenicplus_class "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_class.py"
click node_scenicplus_mudata "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_mudata.py"
click node_adata_wrangling "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/adata_cistopic_wrangling.py"
click node_cistarget_wrangling "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/cistarget_wrangling.py"
click node_gene_search_space "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/gene_search_space.py"
click node_tf_to_gene "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/TF_to_gene.py"
click node_enhancer_to_gene "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/enhancer_to_gene.py"
click node_triplet_score "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/triplet_score.py"
click node_eregulon_enrichment "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/eregulon_enrichment.py"
click node_grn_modules "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/modules.py"
click node_gsea_approach "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/gsea_approach.py"
click node_gsea "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/gsea.py"
click node_filtering "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/preprocessing/filtering.py"
click node_quality_metrics "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/regulon_qc/quality_metrics.py"
click node_rss "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/RSS.py"
click node_networks "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/networks.py"
click node_plotting "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/plotting/grn_plot.py"
click node_loom "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/loom.py"
click node_simulation "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/simulation.py"
click node_basca "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/BASCA.py"
click node_differentiation_potential "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/differentiation_potential.py"
click node_cli "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/cli/scenicplus.py"
click node_snakemake "https://github.com/aertslab/scenicplus/tree/main/src/scenicplus/snakemake/Snakefile"
click node_pycistarget_wrapper "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/wrappers/run_pycistarget.py"
click node_tangram "https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/tangram/projections.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scenicplus_class,node_scenicplus_mudata toneBlue
class node_adata_wrangling,node_cistarget_wrangling,node_gene_search_space,node_tf_to_gene,node_enhancer_to_gene,node_triplet_score,node_eregulon_enrichment,node_grn_modules,node_gsea_approach,node_gsea toneAmber
class node_filtering,node_quality_metrics,node_rss,node_networks,node_plotting,node_loom,node_simulation,node_basca,node_differentiation_potential toneMint
class node_cli,node_snakemake,node_pycistarget_wrapper,node_tangram toneRose
```

## Components

### Core data model

SCENIC+ analysis containers and shared state boundary.

- [SCENIC+ object](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_class.py): analysis container · Primary analysis object for SCENIC+ state and results. · `src/scenicplus/scenicplus_class.py`
- [MuData bridge](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/scenicplus_mudata.py): container adapter · MuData-style interface for multimodal SCENIC+ data. · `src/scenicplus/scenicplus_mudata.py`

### Inference pipeline

Wrangling, regulatory inference, triplet scoring, and GRN assembly.

- [AnnData wrangling](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/adata_cistopic_wrangling.py): input adapter · Converts scRNA/scATAC artifacts into SCENIC+ inputs. · `src/scenicplus/data_wrangling/adata_cistopic_wrangling.py`
- [cistarget import](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/cistarget_wrangling.py): motif adapter · Loads and normalizes motif/enrichment results. · `src/scenicplus/data_wrangling/cistarget_wrangling.py`
- [Search space](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/data_wrangling/gene_search_space.py): region model · Defines candidate enhancer-to-gene search regions. · `src/scenicplus/data_wrangling/gene_search_space.py`
- [TF to gene](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/TF_to_gene.py): regulatory inference · Links transcription factors to target genes. · `src/scenicplus/TF_to_gene.py`
- [Enhancer to gene](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/enhancer_to_gene.py): regulatory inference · Links accessible enhancers to candidate genes. · `src/scenicplus/enhancer_to_gene.py`
- [Triplet scoring](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/triplet_score.py): evidence integrator · Combines TF, enhancer, and gene evidence into triplets. · `src/scenicplus/triplet_score.py`
- [eRegulon enrich](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/eregulon_enrichment.py): scoring · Scores enriched regulons and eGRN activity. · `src/scenicplus/eregulon_enrichment.py`
- [GRN modules](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/modules.py): network assembly · Builds higher-level regulatory modules from evidence. · `src/scenicplus/grn_builder/modules.py`
- [GSEA approach](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/gsea_approach.py): module scoring · Enrichment-driven module construction and scoring. · `src/scenicplus/grn_builder/gsea_approach.py`
- [GSEA helpers](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/grn_builder/gsea.py): enrichment utils · Supporting gene set enrichment logic for GRN building. · `src/scenicplus/grn_builder/gsea.py`

### Analysis and output

QC, downstream analyses, visualization, and export.

- [Filtering](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/preprocessing/filtering.py): preprocessing · Data cleanup and thresholding before inference. · `src/scenicplus/preprocessing/filtering.py`
- [Quality metrics](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/regulon_qc/quality_metrics.py): qc · Computes regulon and network quality measures. · `src/scenicplus/regulon_qc/quality_metrics.py`
- [RSS](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/RSS.py): specificity scoring · Regulon specificity scoring across cell states. · `src/scenicplus/RSS.py`
- [Networks](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/networks.py): network view · Network-level representation of inferred GRNs. · `src/scenicplus/networks.py`
- [Plotting](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/plotting/grn_plot.py): visualization · Plots coverage, correlation, dot, and GRN figures. · `src/scenicplus/plotting/grn_plot.py`
- [Loom export](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/loom.py): export/import · Loom-compatible serialization and interoperability. · `src/scenicplus/loom.py`
- [Simulation](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/simulation.py): downstream analysis · Perturbation or differentiation-style downstream analyses. · `src/scenicplus/simulation.py`
- [BASCA](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/BASCA.py): downstream analysis · Additional downstream interpretive analysis routines. · `src/scenicplus/BASCA.py`
- [Diff potential](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/differentiation_potential.py): downstream analysis · Estimates differentiation potential from derived scores. · `src/scenicplus/differentiation_potential.py`

### Runtime and orchestration

CLI and Snakemake entry points for execution.

- [CLI](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/cli/scenicplus.py): command interface · Shell entry points and subcommands for running SCENIC+. · `src/scenicplus/cli/scenicplus.py`
- [Snakemake](https://github.com/aertslab/scenicplus/tree/main/src/scenicplus/snakemake/Snakefile): workflow · File-driven workflow orchestration for end-to-end runs. · `src/scenicplus/snakemake/Snakefile`
- [pycisTarget](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/wrappers/run_pycistarget.py): external integration · Wrapper around external motif-enrichment tooling. · `src/scenicplus/wrappers/run_pycistarget.py`
- [Tangram](https://github.com/aertslab/scenicplus/blob/main/src/scenicplus/tangram/projections.py): external integration · Projection/mapping integration with Tangram utilities. · `src/scenicplus/tangram/projections.py`

## Connections

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