# API Reference

Import scATrans as:

```python
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 {doc}`../user_guide/index` for narrative usage and
{doc}`../statistical_guidance` 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.

```{eval-rst}
.. currentmodule:: scatrans

.. autosummary::
   :toctree: generated/
   :nosignatures:

   active_score
   active_score_simple
   differential_expression
   differential_expression_simple
   diagnose_design
   recommend_workflow
   run_default_pipeline
   filter_active_genes
   store_raw_counts
   ensure_raw_counts
   restore_raw_counts
```

`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]"`) |

```{eval-rst}
.. autosummary::
   :toctree: generated/
   :nosignatures:

   add_gene_features
   generate_gene_features_from_gtf
   list_available_gene_features
```

## 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) |

```{eval-rst}
.. autosummary::
   :toctree: generated/
   :nosignatures:

   run_enrichment
   run_kegg
   run_go
   run_gsea
   simplify_enrichment
   save_enrichment_report
   expand_enrichment_genes
   list_bundled_gene_sets
   compare_enrichment
   extract_gene_lists
   concat_compare_results
```

## Quality control (`scat.qc`)

```{eval-rst}
.. autosummary::
   :toctree: generated/
   :nosignatures:

   qc.unspliced_global
```

## 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) |

```{eval-rst}
.. autosummary::
   :toctree: generated/
   :nosignatures:

   pl.comet_plot
   pl.volcano_plot
   pl.volcano_3d
   pl.bias_diagnostic_plot
   pl.enrich_dotplot
   pl.enrich_barplot
   pl.enrich_upsetplot
   pl.enrich_vennplot
   pl.gseaplot
   pl.active_score_rankplot
   pl.active_genes_heatmap
   pl.velocity_phase_portraits
   pl.gamma_shrinkage_plot
   pl.set_style
   pl.set_nature_style
   pl.style_context
   pl.figure_export_context
   pl.save_all_figures
```