rapids_singlecell.tl.rank_genes_groups

rapids_singlecell.tl.rank_genes_groups(adata, groupby, *, mask_var=None, use_raw=None, groups='all', reference='rest', n_genes=None, rankby_abs=False, pts=False, key_added=None, method=None, corr_method='benjamini-hochberg', tie_correct=False, use_continuity=False, return_u_values=False, layer=None, chunk_size=None, multi_gpu=None, n_bins=None, bin_range=None, skip_empty_groups=False, **kwds)

Rank genes for characterizing groups using GPU acceleration.

Log1p/log-normalized data is expected for biologically meaningful log fold changes. Exact sparse wilcoxon versus rest ranks signed stored values and implicit zeros directly. Sparse wilcoxon with an explicit reference uses sign-safe dense ranking in bounded CUDA streamer tiles. Dense inputs are ranked directly and support any sign. (wilcoxon_binned rejects negative Dask sparse input, which it cannot bin correctly.)

Note

Dask support: 't-test', 't-test_overestim_var', 'wilcoxon_binned', and 'logreg' support Dask arrays. The 'wilcoxon' method does not support Dask arrays.

Note

Wilcoxon ranking precision: 'wilcoxon' and 'wilcoxon_binned' rank values in float32 on every code path, while means and log fold changes are computed in float64. This only diverges from Scanpy when the preprocessing itself ran in float64 — i.e. normalization/log1p produced values carrying sub-float32 precision. If preprocessing was done in float32 (the common case), the values are float32-exact and ranking is bit-identical to Scanpy (~1e-13), even if they are afterward stored as float64. For a fully float64 pipeline the rank-derived scores and p-values still match Scanpy-on-float64 to ~1e-4 on log-normalized data — below any significance threshold and changing no DE calls — because the rank-sum normal approximation is insensitive to sub-float32 tie jitter. If exact float64 ranking matters for your workflow, please open an issue at scverse/rapids_singlecell#issues.

Parameters:

adata AnnData

Annotated data matrix.

groupby str

The key of the observations grouping to consider.

mask_var ndarray[tuple[Any, ...], dtype[bool]] | str | None (default: None)

Select subset of genes to use in statistical tests. Can be a boolean array of shape (n_vars,) or a key in adata.var.

use_raw bool | None (default: None)

Use raw attribute of adata if present.

groups Union[Literal['all'], Iterable[str]] (default: 'all')

Subset of groups, e.g. ['g1', 'g2', 'g3'], to which comparison shall be restricted, or 'all' (default), for all groups.

reference str (default: 'rest')

If 'rest', compare each group to the union of the rest of the group. If a group identifier, compare with respect to this group.

n_genes int | None (default: None)

The number of genes that appear in the returned tables. Defaults to all genes.

rankby_abs bool (default: False)

Rank genes by the absolute value of the score, not by the score. The returned scores are never the absolute values.

pts bool (default: False)

Compute the fraction of cells expressing the genes.

key_added str | None (default: None)

The key in adata.uns information is saved to.

method Literal['logreg', 't-test', 't-test_overestim_var', 'wilcoxon', 'wilcoxon_binned'] | None (default: None)

't-test' uses Welch’s t-test (default), 't-test_overestim_var' overestimates variance of each group, 'wilcoxon' uses Wilcoxon rank-sum, 'wilcoxon_binned' uses histogram-based approximate Wilcoxon rank-sum (faster for large datasets, supports Dask arrays), 'logreg' uses logistic regression.

corr_method Literal['benjamini-hochberg', 'bonferroni'] (default: 'benjamini-hochberg')

p-value correction method. Used only for 't-test', 't-test_overestim_var', 'wilcoxon', and 'wilcoxon_binned'.

tie_correct bool (default: False)

Use tie correction for 'wilcoxon' and 'wilcoxon_binned' scores. Adjusts the variance of the rank-sum statistic for tied values. For 'wilcoxon_binned', each histogram bin acts as a tie group and the correction is derived from the bin counts.

use_continuity bool (default: False)

Apply continuity correction to 'wilcoxon' and 'wilcoxon_binned' z-scores. Subtracts 0.5 from |R - E[R]| before dividing by the standard deviation, matching scipy.stats.mannwhitneyu() default behavior.

return_u_values bool (default: False)

For 'wilcoxon', store Mann-Whitney U statistics in scores instead of z-scores. P-values are still computed from the z-score normal approximation using the selected tie and continuity settings.

layer str | None (default: None)

Key from adata.layers whose value will be used to perform tests on.

chunk_size int | None (default: None)

Number of genes to process at once for 'wilcoxon' and 'wilcoxon_binned'. Default is 512 for 'wilcoxon'. For 'wilcoxon_binned' the default is sized dynamically based on n_groups and n_bins to keep histogram memory stable.

multi_gpu bool | list[int] | str | None (default: None)

GPU selection for 'wilcoxon', 't-test', 't-test_overestim_var', and 'wilcoxon_binned'. For exact 'wilcoxon', None uses all visible GPUs for host input and device OVO, while device OVR stays on its input-owning GPU. For the streaming t-test/binned paths, None and False use the current GPU. True uses all visible GPUs, and a list or comma-separated string selects device IDs. Streaming multi-GPU is host-only: CSR/dense input is sharded by cell rows, CSC by gene columns, and results are gathered on the current device. Device-resident t-test/binned input runs on its owning GPU. On small host inputs the sharding overhead can make multi-GPU slower than a single GPU.

n_bins int | None (default: None)

Number of histogram bins for 'wilcoxon_binned'. Higher values give a better approximation at slightly increased cost. Default is 1000 for in-memory arrays and 200 for Dask arrays.

bin_range Optional[Literal['log1p', 'auto']] (default: None)

How to determine the histogram bin range for 'wilcoxon_binned'. None (default) uses 'auto' for in-memory arrays and 'log1p' for Dask arrays (to avoid a costly data scan). 'log1p' uses a fixed [0, 15] range suitable for most log1p-normalized data. 'auto' computes the actual data range. Use this for nonnegative expression data outside the fixed log1p range.

skip_empty_groups bool (default: False)

Skip selected groups with fewer than two observations after filtering. This is useful for perturbation workflows where a per-cell-type slice keeps categories that are empty or singleton in that slice.

**kwds

Additional arguments passed to the method. For 'logreg', these are passed to cuml.linear_model.LogisticRegression.

Return type:

None

Returns:

Updates adata with the following fields. Rank result fields are Scanpy-compatible structured arrays.

adata.uns['rank_genes_groups' | key_added]['names']

Structured array to be indexed by group id storing the gene names. Ordered according to scores.

adata.uns['rank_genes_groups' | key_added]['scores']

Structured array to be indexed by group id storing the z-score underlying the computation of a p-value for each gene for each group, or the Mann-Whitney U statistic when return_u_values=True. Ordered according to scores.

adata.uns['rank_genes_groups' | key_added]['logfoldchanges']

Structured array to be indexed by group id storing the log2 fold change for each gene for each group.

adata.uns['rank_genes_groups' | key_added]['pvals']

p-values. Only for 't-test', 't-test_overestim_var', 'wilcoxon', and 'wilcoxon_binned'.

adata.uns['rank_genes_groups' | key_added]['pvals_adj']

Corrected p-values. Only for 't-test', 't-test_overestim_var', 'wilcoxon', and 'wilcoxon_binned'.

adata.uns['rank_genes_groups' | key_added]['pts']

Fraction of cells expressing genes per group. Only if pts=True.

adata.uns['rank_genes_groups' | key_added]['pts_rest']

Fraction of cells expressing genes in rest. Only if pts=True and reference='rest'.