GeneCircuitry

Transcriptional Regulatory Network analysis for single-cell RNA-seq data

GeneCircuitry is a Python package that integrates Scanpy, CellOracle, and Hotspot into a single modular, checkpoint-enabled pipeline for gene regulatory network (GRN) inference from single-cell data. Run the full workflow with one command, or execute individual steps selectively and resume from where you left off.

---

What GeneCircuitry does

Step	Tool	Output
Quality control & normalization	Scanpy	Filtered, normalized AnnData
Dimensionality reduction & clustering	Scanpy (PCA, UMAP, Leiden)	Cell embeddings + cluster labels
GRN inference	CellOracle	Per-cluster transcription factor networks
Gene module identification	Hotspot	Spatially autocorrelated gene modules
Network visualization	NetworkX	Centrality plots, network graphs, rank plots
Comparative & aggregation analysis	GeneCircuitry Engine	Cross-cluster concordance, Jaccard alignment
Reporting	Built-in HTML/PDF engine	Interactive analysis report
Stratified analysis	PipelineController	Per-cell-type parallel runs

---

Quick install

Pixi (recommended) — installs all conda and pip dependencies in one step:

curl -fsSL https://pixi.sh/install.sh | bash   # install pixi once
git clone https://github.com/samuelecancellieri/genecircuitry.git
cd genecircuitry
pixi install
pixi run run        # launch the pipeline

pip / venv:

git clone https://github.com/samuelecancellieri/genecircuitry.git
cd genecircuitry
pip install -e ".[grn,hotspot]"

Docker:

docker run --rm \
    -v /path/to/your/data:/data \
    -v /path/to/output:/output \
    zanathos/genecircuitry:latest \
    --input /data/your_data.h5ad --output /output

Singularity / Apptainer (HPC clusters):

singularity pull genecircuitry.sif docker://zanathos/genecircuitry:latest
singularity exec \
    --bind /path/to/your/data:/data \
    --bind /path/to/output:/output \
    genecircuitry.sif genecircuitry --input /data/your_data.h5ad --output /output

See Getting Started → Installation for all five options, including Conda, version pins, and HPC-specific tips.

---

Run your first analysis

# Run the full pipeline on the bundled PBMC 3k demo dataset
python run_complete_analysis.py

# Run on your own data
python run_complete_analysis.py --input my_data.h5ad --output results/

# Run only specific steps
python -m genecircuitry.pipeline --input my_data.h5ad --output results/ \
    --steps load preprocessing clustering

See Getting Started → Quick Start for the full walkthrough.

---

Documentation

Getting Started

• Installation — pip, conda, pixi, Docker
• Quick Start — CLI and Python API walkthrough

User Guide

• Pipeline Overview — step names, CLI flags, parallel execution, architecture
• Preprocessing & QC — filtering, normalization, clustering
• GRN Inference — CellOracle Oracle objects and link inference
• Gene Modules — Hotspot autocorrelation and module detection
• Plotting System — genecircuitry/plotting/ subpackage
• Reporting — HTML/PDF report generation
• Stratified Analysis — per-cluster parallel runs
• Checkpoints & Resume — auto-resume and checkpoint management

Reference

• Configuration — all config.py parameters
• API Reference — function signatures across all modules
• ATAC Peaks Processing — BED → TF motif matrix for CellOracle

Other

• Architecture & Implementation — full subsystem architecture and developer guide

---

Data flow

AnnData (.h5ad)
    │
    ▼
[Preprocessing & QC]            genecircuitry/preprocessing.py
  ├─ perform_qc()
  ├─ perform_normalization()
  └─ perform_dimensionality_reduction_clustering()
    │
    ▼  (checkpoint: preprocessed_adata.h5ad)
    │
    ├──────────────────────────────────────────────────┐
    ▼                                                  │
[Optional: Stratification]       split by cell type    │
  └─ per-cluster AnnData objects                       │
    │                                                  │
    ├────────────────────────┐                         │
    ▼                        ▼                         │
[CellOracle GRN]        [Hotspot Modules]              │
  create_oracle_object()  create_hotspot_object()      │
  run_PCA()               run_hotspot_analysis()       │
  run_KNN()                                            │
  run_links()                                          │
    │                        │                         │
    └────────────┬───────────┘                         │
                 ▼                                     │
         [GRN Deep Analysis]   genecircuitry/grn_deep_analysis.py
         [Reporting]           genecircuitry/reporting/ → HTML + PDF
                 ▲
                 └─────────────────────────────────────┘