Quick Start

Table of contents

1. TOC

---

Run the complete pipeline

The simplest way to run GeneCircuitry is through the entry-point wrapper:

# With example data (PBMC 3k auto-downloaded)
python run_complete_analysis.py

# With your own data
python run_complete_analysis.py \
    --input data/my_cells.h5ad \
    --output results/my_run \
    --name "My Experiment"

# Skip optional analyses
python run_complete_analysis.py --skip-celloracle  # no GRN inference
python run_complete_analysis.py --skip-hotspot      # no module identification

# Custom parameters
python run_complete_analysis.py --seed 123 --n-jobs 16 --min-genes 300

# See all options
python run_complete_analysis.py --help

---

The genecircuitry command

After installation the genecircuitry console script is registered and is the primary entrypoint — it is equivalent to python -m genecircuitry.pipeline but works from any directory without needing the source tree.

genecircuitry --help

Flag reference

Input / output

Flag	Short	Default	Description
--input	-i	(example dataset)	Input .h5ad or .h5 file. Omit to auto-download PBMC 3k.
--output	-o	output	Output directory. Created automatically.
--name	-n	test_run	Label for this run (used in logs and reports).

Analysis

Flag	Short	Default	Description
--species	-s	human	Species for GRN base network (human or mouse).
--cluster-key		leiden	adata.obs column that holds cluster labels.
--clusters		all	Comma-separated list of clusters to analyse (subset).
--cluster-key-stratification		(disabled)	Run a per-cluster stratified analysis on this column.
--embedding-grn		X_draw_graph_fa	Embedding used for CellOracle visualisations.
--embedding-hotspot		X_umap	Embedding used for Hotspot.
--normalization-key		n_counts	adata.obs column with per-cell total counts.
--raw-count-layer		raw_counts	Layer name where raw integer counts are stored.
--tf-dictionary		(auto)	Path to a custom TF→target pickle file.
--atac-peaks		(none)	BED file of pre-called ATAC peaks for motif-based base GRN.
--no-base-grn		False	Disable the default base GRN (use with --tf-dictionary).

Quality control

Flag	Default	Description
--min-genes	config.QC_MIN_GENES	Minimum genes per cell to retain.
--min-counts	config.QC_MIN_COUNTS	Minimum UMI counts per cell to retain.

Computational

Flag	Default	Description
--seed	42	Global random seed.
--n-jobs	config.N_JOBS	Parallel workers for Hotspot / stratification.

Pipeline control

Flag	Default	Description
--skip-qc	False	Skip QC filtering (input already filtered).
--skip-celloracle	False	Skip GRN inference.
--skip-hotspot	False	Skip gene-module identification.
--debug	False	Verbose debug logging.
--steps	(all)	Space-separated list of steps to run (see below).

Common recipes

# Minimal run — example data, all defaults
genecircuitry

# Your own data, custom output dir
genecircuitry -i data/my_cells.h5ad -o results/my_run -n "My Experiment"

# Human GRN only, 8 cores, reproducible seed
genecircuitry -i data/my_cells.h5ad --skip-hotspot --n-jobs 8 --seed 1

# Mouse data with ATAC peaks for base GRN
genecircuitry -i data/mouse.h5ad --species mouse --atac-peaks data/peaks.bed

# Per-cluster stratified analysis
genecircuitry -i data/my_cells.h5ad \
    --cluster-key-stratification cell_type \
    --parallel --n-jobs 4

# Run only selected steps (checkpoint-aware)
genecircuitry -i data/my_cells.h5ad --steps load preprocessing clustering

Tip: genecircuitry and python -m genecircuitry.pipeline share the same parser — all flags above work identically with both invocation styles.

---

Run specific pipeline steps

# Run only QC + normalization + clustering (skip GRN and Hotspot)
python -m genecircuitry.pipeline \
    --input data/my_cells.h5ad \
    --output results/ \
    --steps load preprocessing clustering

# Resume from checkpoints — already-completed steps are skipped automatically
python -m genecircuitry.pipeline \
    --input data/my_cells.h5ad \
    --output results/ \
    --steps celloracle hotspot

Available step names: load, preprocessing, stratification, clustering, atac_peaks, celloracle, hotspot, grn_analysis, report, summary

---

Stratified (per-cluster) analysis

Analyse each cell type independently in parallel:

python -m genecircuitry.pipeline \
    --input data/my_cells.h5ad \
    --output results/ \
    --cluster-key-stratification cell_type \
    --parallel \
    --n-jobs 4

Each stratification gets its own subdirectory under results/stratified_analysis/<ClusterName>/.

---

Python API

import scanpy as sc
from genecircuitry import config, set_random_seed, set_scanpy_settings
from genecircuitry.preprocessing import perform_qc, perform_normalization

# 1. Setup
set_random_seed(42)
set_scanpy_settings()

# 2. Load data
adata = sc.read_h5ad("data/my_cells.h5ad")

# 3. QC (all thresholds come from config)
adata = perform_qc(adata)

# Override thresholds per-call (doesn't alter global config)
adata = perform_qc(adata, min_genes=300, pct_counts_mt_max=15.0)

# 4. Normalization
adata = perform_normalization(adata)

# 5. GRN preprocessing + CellOracle (requires celloracle installed)
from genecircuitry.celloracle_processing import (
    perform_grn_pre_processing,
    create_oracle_object,
    run_PCA, run_KNN, run_links,
)
adata_grn = perform_grn_pre_processing(adata, cluster_key="leiden")
oracle = create_oracle_object(adata_grn, cluster_column_name="leiden",
                              embedding_name="X_umap")
oracle, n_comps = run_PCA(oracle)
oracle = run_KNN(oracle, n_comps=n_comps)
links = run_links(oracle, cluster_column_name="leiden")

---

Expected output structure

results/
├── preprocessed_adata.h5ad        # QC + normalized AnnData
├── clustered_adata.h5ad           # After dim-reduction & clustering
├── report.html                    # Interactive analysis report
├── report.pdf                     # PDF report (requires weasyprint)
├── analysis_summary.txt
├── logs/
│   ├── pipeline.log               # All steps with timestamps
│   ├── error.log                  # Errors with full tracebacks
│   └── *.checkpoint               # Auto-resume markers
├── figures/
│   ├── qc/                        # QC violin/scatter plots
│   ├── grn/                       # GRN network plots, rank plots
│   └── hotspot/                   # Module heatmaps
├── celloracle/
│   ├── grn_merged_scores.csv
│   └── grn_filtered_links.pkl
├── hotspot/
│   ├── autocorrelation_results.csv
│   └── gene_modules.csv
└── stratified_analysis/
    └── <ClusterName>/             # One folder per stratification
        ├── report.html
        ├── figures/
        ├── celloracle/
        └── hotspot/

---

Checkpointing

GeneCircuitry writes .checkpoint files to logs/ after each step. If the pipeline is interrupted, re-running the same command resumes from where it left off. The checkpoint is invalidated if the input file or key parameters change.