AUCell

Per-cell regulon activity scores.

rustscenic.aucell

AUCell regulon activity scoring.

Public API: rustscenic.aucell.score(expression, regulons, top_frac=0.05) -> pd.DataFrame

Matches pyscenic.aucell.aucell at the algorithmic level: For each cell c, rank all genes by expression (descending). For each regulon r with gene set G_r, AUC = sum over g in G_r with rank(g) < K of (K - rank), normalized by K * |G_r| (clamped to [0, 1]). K = floor(top_frac * n_genes).

score 

score(
    expression, regulons: Iterable, *, top_frac: float = 0.05, chunk_size: int = 10000
) -> pd.DataFrame

Compute per-cell regulon activity matrix.

Parameters:

Name Type Description Default
expression

AnnData, pandas DataFrame (cells × genes), or (matrix, gene_names) tuple. For AnnData inputs, gene names are resolved via rustscenic._gene_resolution.resolve_gene_names so cellxgene / ENSEMBL-ID-keyed datasets are matched against regulon gene symbols automatically.

 required
regulons Iterable

Either: - A dict mapping regulon_name -> set/list of target-gene symbols - A list of pyscenic Regulon / GeneSignature objects (objects with .name and either .genes or .gene2weight attrs)

 required
top_frac float

Fraction of top-ranked genes per cell used as AUC cutoff (default 0.05, matches pyscenic).

 0.05
chunk_size int

Kept for API compatibility. Sparse SciPy/AnnData inputs are scored by the Rust CSR kernel without dense materialisation; dense inputs ignore this setting.

 10000

Returns:

Name Type Description
pandas.DataFrame of shape (n_cells, n_regulons). Index: cell barcodes.
Columns regulon names. Per-regulon gene-coverage counts are stored on
the DataFrame's ``.attrs["regulon_coverage"]`` dict, keyed by regulon name.

Raises:

Type Description
ValueError

A tuple input's matrix is not two-dimensional (cells by genes), or its gene-name count differs from the number of matrix columns.
Notes

Tuple-axis validation was added in version 0.5.1. It is absent from the 0.5.0 wheel.

Reexported helpers

These names are also available from this module. They share the underlying implementation and source documentation of their original definitions.

rustscenic.aucell.dedupe_backend_symbol_for_matrix 

dedupe_backend_symbol_for_matrix(X) -> str | None

Return the Rust dedupe kernel symbol that dedupe_by_symbol will use.

Parameters:

Name Type Description Default
X

Dense NumPy or SciPy sparse matrix whose dtype and sparse status select the kernel. Unsupported dtypes return None.

 required

rustscenic.aucell.dedupe_by_symbol 

dedupe_by_symbol(X, gene_names: Sequence[str])

Collapse duplicate gene-symbol columns by summing their expression.

When an ENSEMBL → symbol swap produces duplicate symbols (e.g. several transcripts collapsing onto the same HGNC symbol, or pseudogenes sharing a parent name), downstream regulon lookup is ambiguous. The scanpy / limma convention is to sum the columns: total per-gene expression aggregated across transcripts. This preserves signal; the alternative (drop all but one) silently loses half the gene's reads.

Parameters:

Name Type Description Default
X

Dense NumPy or SciPy sparse cells-by-genes matrix with numeric float32/float64, int32/int64 or uint32/uint64 values.

 required
gene_names Sequence[str]

Gene symbols corresponding to the columns of X.

 required

Returns:

Type Description
(X_deduped, unique_gene_names) - X may be sparse (scipy.sparse) or
dense numpy; the return type matches the input.

rustscenic.aucell.duplicate_gene_summary 

duplicate_gene_summary(
    gene_names: Sequence[str], *, max_examples: int = 3
) -> tuple[int, list[str]]

Return duplicate gene count and example names from the Rust stage helper.

Parameters:

Name Type Description Default
gene_names Sequence[str]

Gene symbols to inspect for duplicates.

 required
max_examples int

Maximum number of duplicate-name examples to return.

 3

rustscenic.aucell.warn_if_max_likely_unnormalized 

warn_if_max_likely_unnormalized(
    max_val: float | None, *, max_threshold: float = 50.0, stacklevel: int = 2
) -> None

Warn from a Rust-collected expression maximum without rescanning in Python.

Parameters:

Name Type Description Default
max_val float | None

Observed expression maximum; None skips the check.

 required
max_threshold float

Finite maximum above which the normalization warning is emitted.

 50.0
stacklevel int

Stack depth passed to warnings.warn to locate the caller.

 2

rustscenic.aucell.warn_if_poor_coverage 

warn_if_poor_coverage(
    coverage: Mapping[str, tuple[int, int]],
    *,
    threshold: float = 0.5,
    stacklevel: int = 2,
) -> None

Emit a UserWarning listing regulons with < threshold overlap.

This catches the silent-near-zero case that the existing all regulons dropped warning misses: a regulon with 3 out of 50 genes still runs, and still produces a floor-bound AUC score.

Parameters:

Name Type Description Default
coverage Mapping[str, tuple[int, int]]

Regulon names mapped to (matched_gene_count, total_gene_count).

 required
threshold float

Warn when a nonempty regulon's matched fraction is below this value.

 0.5
stacklevel int

Stack depth passed to warnings.warn to locate the caller.

 2

rustscenic.aucell.as_float32_array 

as_float32_array(values) -> np.ndarray

Return a float32 ndarray without changing memory layout.

Parameters:

Name Type Description Default
values

Array-like values accepted by numpy.asarray.

 required

rustscenic.aucell.as_float32_contiguous 

as_float32_contiguous(values) -> np.ndarray

Return a C-contiguous float32 ndarray, copying only when needed.

Parameters:

Name Type Description Default
values

Array-like values accepted by numpy.asarray.

 required

rustscenic.aucell.prepare_regulon_indices_with_coverage 

prepare_regulon_indices_with_coverage(
    gene_names: Iterable[str], regulons: Iterable
) -> tuple[
    list[str],
    list[list[int]],
    list[tuple[str, list[str]]],
    dict[str, tuple[int, int]],
    int,
]

Map regulon genes and coverage in one Rust call.

Parameters:

Name Type Description Default
gene_names Iterable[str]

Feature names in expression-matrix column order.

 required
regulons Iterable

Regulons accepted by iter_regulon_pairs.

 required

Returns:

Type Description
tuple

Retained names, feature-index lists, original regulon pairs, per-regulon (matched, total) coverage and dropped-empty count.

rustscenic.aucell.string_list 

string_list(values: Iterable) -> list[str]

Return Python strings with minimal pandas boundary overhead.

Parameters:

Name Type Description Default
values Iterable

Iterable, pandas Series or Index, or NumPy array of values to convert to strings in input order.

 required