API Reference

Import scATrans as:

import scatrans as scat

Submodules scat.pl (plotting) and scat.qc (quality control) are intentionally exposed (scanpy-style convention). Other internal modules are not part of the stable public surface. Functions are grouped by task below; each group lists its key tunable parameters before the full autosummary table. See User Guide for narrative usage and Statistical Guidance & Reporting Checklist for what each result column means.

Core: scoring, filtering, DE

active_score is the main velocity-aware entry point; differential_expression is the no-velocity equivalent. Both return the same kind of results table and feed into the same filter_active_genes / enrichment / plotting tools.

Parameter	Applies to	Default	Options
groupby	both	"condition"	any obs column holding group labels
target_group / reference_group	both	None (required)	must be set explicitly to two values in adata.obs[groupby]; tutorials often use e.g. "GA" / "Ctrl"
use_pseudobulk + sample_col	both	False / None	aggregate to per-replicate pseudobulk before DE (needs sample_col)
pseudobulk_de_backend	both	"pydeseq2"	"pydeseq2" (count-based DESeq2) or "scanpy" (rank_genes_groups on aggregated profiles)
de_method	both	"t-test_overestim_var"	any scanpy.tl.rank_genes_groups method, e.g. "wilcoxon"
use_mixed_model + sample_col	both	False	cell-level LMM with sample random intercept; needs ≥4 samples/group
use_memento_de	differential_expression	False	method-of-moments cell-level DE (raw integer counts required)
use_permutation + n_perm + perm_de_backend	active_score	False / 100 / "same"	permutation FDR on unspliced excess; perm_de_backend="fast" trades accuracy for speed
gamma_method	active_score	"heuristic_shrink"	"heuristic_shrink", "robust_median", "empirical_bayes" (hierarchical, recommended for small reference groups), "raw"
bias_correction	active_score	"huber_length_intron"	"huber_length_intron" or "none"
mode	active_score	"heuristic"	"heuristic" or "advanced" (scVelo moments smoothing)

Always call recommend_workflow(...) (or let active_score_simple / run_default_pipeline call it for you) before picking these by hand — it inspects cell/sample counts and suggests a preset.

active_score	Identify genes showing higher unspliced (nascent) RNA in the target group relative to reference (positive unspliced excess after reference-gamma correction), combined with upregulation (positive logFC).
active_score_simple	Recommended entry point for new users (minimal parameters).
differential_expression	Standalone differential expression (DE) using the same flexible backends as scATrans (scanpy methods, PyDESeq2 pseudobulk, mixed linear models, and Memento -- the Cell 2024 method-of-moments framework).
differential_expression_simple	Minimal-parameter differential expression (no velocity layers required).
diagnose_design	Analyze the experimental design and provide guidance on suitable analysis choices and expected power/limitations.
recommend_workflow	High-level recommendation for analysis path based on experimental design.
run_default_pipeline	End-to-end recommended workflow for first-time users.
filter_active_genes	Apply custom post-filtering to a results DataFrame (from active_score or differential_expression).
store_raw_counts	Store raw counts and the original spliced/unspliced (or mature/nascent) layers early in the analysis, right after loading and basic QC, but BEFORE HVG selection, normalization, or log1p.
ensure_raw_counts	Ensure raw integer counts are available in adata.layers[layer].
restore_raw_counts	Restore raw counts from the stored layer (preferred) or adata.raw back into .X.

filter_active_genes(results_df, preset=..., logfc_direction=..., return_mask=...) takes preset="heuristic" (default cutoffs), "pseudobulk" (looser, post-aggregation), "significant" (replays the built-in strict mask; requires use_permutation=True upstream), or "permissive"; or pass explicit *_cutoff kwargs instead of a preset.

Gene features

Used for optional bias correction inside active_score (length + intron count regressed out of the raw unspliced-excess delta).

WORKFLOW_PRESETS is a public constant dict (keys such as "explore", "pseudobulk", "memento") returned by recommend_workflow() and accepted by active_score_simple / run_default_pipeline. It is not autosummary’d here because it is data, not a callable.

The generate-gene-features console script maps to scat.generate_gene_features_main (importable from the top-level package); programmatic use is via generate_gene_features_from_gtf() below.

Parameter	Function	Notes
organism	add_gene_features	"mouse" (default) or "human", uses the bundled table
gene_features_path	add_gene_features	supply your own parquet instead of the bundled table
gtf_path / organism	generate_gene_features_from_gtf	build a custom table from a 10x/GENCODE GTF (pip install "scatrans[gene_features]")

add_gene_features	Add gene features (length, intron number) to adata.var for bias correction.
generate_gene_features_from_gtf	Generate a gene features parquet (gene_length + intron_number) from a GTF.
list_available_gene_features	List all available gene feature parquet files shipped with the package.

Functional enrichment

All ORA-style functions (run_enrichment, run_kegg, run_go) share the same universe-handling and gene-set-resolution machinery; run_gsea takes a ranked list instead of a candidate gene list.

Parameter	Applies to	Default	Options
gene_sets	run_enrichment, run_gsea	—	base name (e.g. "GO_Biological_Process", auto-resolved per organism) or a full versioned Enrichr name (e.g. "...2021") for a historical library
organism	all ORA/GSEA functions	—	"mouse" or "human"
adata	all ORA/GSEA functions	None	pass the object you called store_raw_counts on to auto-supply the measured-gene background/universe
gene_set_source	all ORA/GSEA functions	auto-detected	"scatrans" (bundled) or "enrichr" (gseapy) to force a source
ontology	run_go	"BP"	"BP", "CC", "MF", or "ALL" (with adjust_across_all=True for unified correction)
method	simplify_enrichment	"jaccard"	"jaccard" (fast, overlap-based) or "pathway_denester" (nested-pathway test)

run_enrichment	Hypergeometric over-representation analysis (clusterProfiler-style ORA).
run_kegg	KEGG pathway enrichment (wrapper around run_enrichment).
run_go	GO enrichment (BP / CC / MF) wrapper around run_enrichment.
run_gsea	Pre-ranked Gene Set Enrichment Analysis (GSEA) using gseapy.prerank.
simplify_enrichment	Redundancy reduction for enrichment results.
save_enrichment_report	Save enrichment results in formats friendly for manuscripts and supplementary materials.
expand_enrichment_genes	Expand semicolon-joined Genes column into a long term-gene table.
list_bundled_gene_sets	List gene set files (.gmt and similar) that are bundled inside the package under scatrans/data/.
compare_enrichment	Run enrichment analysis across multiple named groups/clusters/contrasts (clusterProfiler::compareCluster style).
extract_gene_lists	Extract named gene lists from one or more DE result DataFrames for downstream enrichment.
concat_compare_results	Combine already-computed per-group enrichment results into a compare-style DataFrame.

Quality control (scat.qc)

qc.unspliced_global

Calculate the global fraction of unspliced reads across all cells.

Plotting (scat.pl)

Every scat.pl.* function accepts ax=/axes= (multi-panel embedding), save_path= (vector/300 dpi export), show=, and use_style=; most return (fig, ax).

Parameter	Applies to	Notes
style	volcano_plot	"auto" (legacy active_score colormap), "ggvolcano" (3-color classic), "gradual" (FDR gradient)
x / size_by / color_by	enrich_dotplot, enrich_barplot	x="GeneRatio" (ORA) or "NES" (GSEA, auto-detected); color_by defaults to adjusted p-value
show_terms	enrich_dotplot	int (top N), "auto" (significance + count heuristic), or an explicit term list
top_n / label_genes	comet_plot, volcano_plot	control auto-labeling; label_genes=[...] adds manual labels
use_style / set_style()	all	opt-in publication style (off by default so notebooks are not surprised by global rcParams changes)

pl.comet_plot	Comet plot of log fold change vs. bias-corrected unspliced residual.
pl.volcano_plot	2D volcano plot with ggVolcano-inspired flexibility and style options.
pl.volcano_3d	3D volcano-style view (logFC, -log10(p_adj), velocity residual).
pl.bias_diagnostic_plot	Diagnostic plot showing the effect of gene length / intron number bias correction on velocity delta (before vs after).
pl.enrich_dotplot	Dotplot for enrichment results (clusterProfiler style).
pl.enrich_barplot	Barplot wrapper around the dotplot implementation (for API compatibility).
pl.enrich_upsetplot	UpSet-style plot for term overlap across clusters/groups (compareCluster style).
pl.enrich_vennplot	Simple multi-group Venn diagram for significant enriched terms across clusters.
pl.gseaplot	Classic GSEA plot: running enrichment score (RES) curve + hits + ranked list.
pl.active_score_rankplot	Horizontal ranked barplot of top active scores (publication-friendly).
pl.active_genes_heatmap	Convenience wrapper around scanpy heatmap for the active driver genes.
pl.velocity_phase_portraits	Quick diagnostic grid of unspliced vs spliced (phase-portrait style) for selected genes.
pl.gamma_shrinkage_plot	Visualize per-gene shrinkage strength vs expression depth (empirical Bayes gamma).
pl.set_style	Apply a clean, minimal style suitable for scientific publication figures.
pl.set_nature_style	Legacy alias for set_style() kept for backward compatibility.
pl.style_context	Context manager for temporary style application.
pl.figure_export_context	Context manager for batch-saving figures in multi-panel workflows.
pl.save_all_figures	Batch-save a mapping of name -> matplotlib Figure.