RustScenic

Fast, memory-efficient gene-regulation analysis for single-cell data.

Infer gene networks and score their activity using RNA and chromatin-accessibility data. A Python package accelerated with Rust. Runs on CPUs; no GPU required.

Created and maintained by Ekin Kahraman, developed in collaboration with the Kuan-Lin Huang Lab at the Icahn School of Medicine at Mount Sinai.

Documentation | Benchmarks | Validation | Citation | Zenodo DOI

Highlights

• Gene-network inference on 1.3 million mouse-brain cells in under 47 minutes, with 4.28 GB peak memory during analysis on 16 CPU cores (v0.5.0 benchmark).
• 3.3x faster with about 81% less peak physical memory than arboreto in a controlled 20,000-cell gene-network comparison on the same hardware.
• 21.4% lower topic-model peak memory, with unchanged output files in repeated mouse-brain tests (v0.5.0 memory audit).
• 11x to 52x faster than SCENIC+ for selected analysis stages on sampled real-data inputs, measured on one machine.
• Huang Lab collaborator run recovered 16/17 expected brain transcription factors in human brain data.

The first three results were measured on the v0.5.0 release candidate. The million-cell run used prepared RNA and 2,095 selected genes; separate full-data preparation peaked at 71.49 GB. These measurements do not describe a complete million-cell spatial workflow.

Current release: v0.5.0. Python 3.10 to 3.13; Linux, macOS and Windows. Core analysis runs without Java, dask, CUDA or Snakemake.

Installation

pip install rustscenic

Upgrading from 0.4.x

v0.5.0 reduces memory use and adds separate positively and negatively correlated target sets. Gene-network fitting now follows arboreto's stopping rule; use early_stop_mode="legacy_inbag" only to reproduce the previous behaviour. See the release notes for compatibility options and the change to Apache-2.0. Earlier published releases remain under MIT.

Benchmark Evidence

The SCENIC+ comparison starts from prepared matrices and measures gene-network inference, enhancer links and activity scores. It excludes raw-data processing, topic modelling and motif-database construction.

The tools use different methods for enhancer linking: RustScenic uses correlation over the fixed search space, while SCENIC+ uses boosted trees plus Pearson scoring for region-to-gene links.

Machine: Apple M5 laptop, 16 GB RAM, macOS arm64, 4 CPU threads. RustScenic rows used Python 3.13.9; SCENIC+ reference rows used Python 3.11.8 for its dependency stack. Rows can be sampled subsets; the shape column is the actual benchmark input.

Including data preparation, the human brain GEM-X row is 11.89 s for RustScenic versus 150.36 s for SCENIC+.

Full commands, hardware, validation metrics and output signatures are in site_docs/benchmarks.md.

Stage Coverage

Quick Start

This example uses v0.5.0. It builds candidate gene sets from network edges and scores their activity; these sets have not been filtered for motif support or split by positive and negative correlation.

import anndata as ad
import rustscenic.aucell
import rustscenic.data
import rustscenic.grn

adata = ad.read_h5ad("rna.h5ad")
tfs = rustscenic.data.tfs("hs")

grn = rustscenic.grn.infer(
    adata, tf_names=tfs, n_estimators=5000, top_targets_per_tf=50, seed=777
)
regulons = {
    tf: group["target"].tolist()
    for tf, group in grn.groupby("TF")
    if len(group) >= 10
}
auc = rustscenic.aucell.score(adata, regulons, top_frac=0.05)

Command line:

rustscenic pipeline --rna data.h5ad --tfs tfs.txt --output out/
rustscenic grn --expression rna.h5ad --tfs tfs.txt --output grn.parquet
rustscenic aucell --expression rna.h5ad --regulons grn.parquet --output aucell.parquet
rustscenic topics --expression atac.h5ad --output topics.parquet --n-topics 30
rustscenic cistarget --rankings rankings.feather --regulons regulons.tsv --output motifs.parquet

See examples/pbmc3k_end_to_end.py for a small real-data RNA example.

v0.5.0 also provides add_correlation, build_regulons, and rustscenic add-cor to separate target sets by correlation sign. See the API map for those features. A correlation sign is not experimental proof of activation or repression.

Validation

Validation artefacts live under validation/. Public interpretation lives in site_docs/benchmarks.md and site_docs/validation.md.

Current Boundaries

• The SCENIC+ speedups cover selected analysis stages, not every possible raw-data and motif-database workflow.
• GRN, gene AUCell and eRegulon edge agreement are not claimed to be bit-identical to SCENIC+; see Benchmarks for the parity metrics.
• v0.5.0 changes grn.infer to arboreto-compatible early stopping. Use early_stop_mode="legacy_inbag" only to reproduce historical RustScenic stopping behaviour. The pipeline defaults to separate activator and repressor regulons; grn_regulon_polarities="unsigned" is the explicit compatibility path.
• Complete million-cell spatial workflows and an atlas-wide CELLxGENE resource remain outside the validated scope.

Documentation

• Installation
• Quickstart
• API map
• HPC operation
• Benchmarks
• Validation
• Scope

Citation

If you use RustScenic in a paper, report, benchmark, derivative package or lab workflow, cite the exact release used. GitHub citation metadata is in CITATION.cff. Zenodo concept DOI: 10.5281/zenodo.20246040.

RustScenic is created and maintained by Ekin Kahraman. See AUTHORS.md for attribution.