Pipeline¶

An AnnData, a path to an .h5ad, or a pandas DataFrame (cells × genes).

Directory where all artifacts are written. Created if missing.

Pre-built cells × peaks AnnData, or a path to one on disk. Use this when you already have a cleaned/subset ATAC matrix (e.g. cell-called barcodes only, post-QC). Mutually exclusive with fragments + peaks: if adata_atac is provided, the fragments + peaks path is skipped. This avoids carrying the full raw 10x barcode set (~450k empty droplets typical) through topics, which can stall downstream stages on consumer hardware.

Paths to a 10x-style fragments.tsv[.gz] and peak BED. When both are provided AND adata_atac is not, rustscenic.preproc builds the cells × peaks AnnData and topics fits on it.

Paths to a 10x-style fragments.tsv[.gz] and peak BED. When both are provided AND adata_atac is not, rustscenic.preproc builds the cells × peaks AnnData and topics fits on it.

Candidate transcription factor names. Path to a newline-separated file, an iterable of strings, or None to use the bundled human TF list.

Motif ranking DataFrame, or a path to a parquet / feather file with motifs as rows and genes as columns. If provided, cistarget runs to score candidate regulons for motif enrichment.

Optional motif-to-TF annotation table. When provided alongside motif_rankings, the active regulons are pruned to enriched motifs annotated back to the source TF, and target genes are restricted to the motif ranking recovery window.

Optional region-based motif ranking DataFrame, or path, with motifs as rows and peak / region IDs as columns. When supplied alongside ATAC inputs and gene coordinates, eRegulon assembly uses this exact region-cistarget path instead of the gene-cistarget bridge. File-backed parquet / feather rankings are projected to the peaks used by the current run so large region-ranking databases do not need to be loaded in full.

DataFrame with columns ['gene', 'chrom', 'tss'], or a path to a parquet/csv file with the same shape. When supplied alongside fragments + peaks, the orchestrator runs rustscenic.enhancer.link_peaks_to_genes and, when either gene- or region-based motif rankings are supplied, rustscenic.eregulon.build_eregulons.

"vb" (default) - online VB LDA, fast at small K (≤ 10). "gibbs" - collapsed-Gibbs LDA (Mallet-class), slower per sweep but recovers ~10× more distinct topics on sparse scATAC at K ≥ 30. Pair with topics_n_threads > 1 for AD-LDA parallel execution at atlas scale. Keep the thread count fixed across biological comparisons because it changes the AD-LDA partition and may change the fitted posterior mode.

Gibbs sweeps (only used when topics_method='gibbs'). 200 is a reasonable default; bump to 500–1000 for higher-quality posterior estimates.

Threads for the Gibbs sampler (only used when topics_method='gibbs'). 1 = bit-deterministic serial path. > 1 = AD-LDA parallel path, reproducible at a fixed seed and thread count. Treat the thread count as part of the model configuration, not only as a scheduler setting.

Fraction of candidate TFs sampled per split in GRN boosting. 0.1 matches arboreto/SCENIC defaults. Lower values can be much faster on high-TF datasets, but change edge rankings and should be treated as a speed/quality tradeoff.

"arboreto" (default) uses the trailing mean of OOB improvements. "legacy_inbag" reproduces historical RustScenic early stopping.

"both" (default) computes TF-target Pearson correlations and emits separate <TF>_activator and <TF>_repressor regulons. "activating" keeps only positive-correlation regulons. "unsigned" is the explicit legacy path and skips dichotomisation.

Retained for API compatibility. Flat GRN scheduling ignores the value.

Maximum boosting trees fitted per target gene. Early stopping may fit fewer; passed to grn.infer.

Trailing-window size for the selected GRN stopping monitor. Zero disables early stopping.

Maximum highest-importance targets per candidate regulon, applied separately to each TF and polarity in signed mode. Candidate sets require at least min(10, grn_top_targets) genes.

Absolute Pearson-correlation threshold for activating or repressing GRN edges. Neutral edges are excluded from signed regulons. Ignored for grn_regulon_polarities="unsigned".

Exclude cells where either gene is zero when scoring correlations. Ignored for unsigned regulons.

Fraction of the highest-ranked genes per cell used for AUCell recovery, greater than zero and at most one.

Number of latent topics requested when ATAC input is available.

Passes over the ATAC corpus for topics_method="vb". Gibbs fitting uses topics_n_iters instead.

Ranking-universe fraction used for enrichment recovery AUC and for the target-recovery window during motif-annotation pruning.

Minimum motif AUC for enrichment reporting and annotation-based motif filtering on the gene- and region-ranking paths.

Optional minimum normalized enrichment score. None applies no NES filter; a supplied threshold excludes undefined NES values.

Maximum peak-center to gene-TSS distance in base pairs for enhancer-to-gene linking when its inputs are available.

Minimum absolute correlation retained for enhancer-to-gene links.

Minimum surviving target genes required for an assembled eRegulon.

Minimum peak-to-gene links required for an assembled eRegulon.

Write rna_with_regulons.h5ad with AUCell scores attached to obs. Default True preserves the full end-to-end artifact. Set False for HPC profiling runs that need to measure compute stages without the final full-RNA h5ad materialisation and write.

Random seed passed to GRN inference and the selected topic fitter. Hold the Gibbs thread count and other settings fixed as well.

Enable pipeline progress logging. Called stages may still emit their own messages or warnings when this is false.