API Reference¶
- illico.asymptotic_wilcoxon.asymptotic_wilcoxon(adata, is_log1p, group_keys, reference=None, n_threads=1, batch_size='~256', alternative='two-sided', use_continuity=True, tie_correct=True, exp_post_agg=False, layer=None, groups=None, exclude_from_ovr=None, precompile=True, use_rust=True, return_as_scanpy=False, n_genes=None, corr_method='benjamini-hochberg')[source]¶
Perform asymptotic Mann-Whitney tests for differential gene expression.
Mann-Whitney test is the same as Wilcoxon rank-sum test. This function takes as input an AnnData object of shape (n_cells, n_genes) with a group (e.g., perturbation) variable stored in .obs. It performs either one-versus-rest (OVR) or one-versus-one (OVO) Wilcoxon-Mann-Whitney tests for each gene, depending on whether a reference group is provided.
It supports all the combinations of data formats (dense, sparse CSR, sparse CSC, in RAM or lazy) and tests (OVO, OVR), except one: the OVR test on lazy CSR datasets. The reason why this combo is not supported is because OVR test requires each column to be entirely in RAM as it has to be sorted, but CSR matrices requires the entirety of the .indices to be in RAM to chunk vertically, which defeats the purpose of using a lazy format in the first place.
- Parameters:
adata (ad.AnnData) – Annotated data matrix of shape (n_cells, n_genes).
is_log1p (bool) – Whether the data is log1p transformed.
group_keys (str) – Key in adata.obs specifying the group variable.
reference (str or None, default=None) – Name of the reference group for OVO tests. If None, OVR tests are performed.
n_threads (int, default=1) – Number of threads to use for parallel computation.
batch_size (int or str, default="~256") – Number of genes to process in each batch. Can be an integer for fixed-size batches, or a string with an integer preceded by “~” (e.g., “~256”, “~512”, “~1024”) to target approximately that number of genes per chunk with balanced worker allocation.
alternative (str, default="two-sided") – Type of alternative hypothesis. One of ‘two-sided’, ‘less’, or ‘greater’.
use_continuity (bool, default=True) – Whether to apply continuity correction.
tie_correct (bool, default=True) – Whether to apply tie correction in the test statistic.
exp_post_agg (bool, default=False) – Whether to exponentiate the fold change after aggregation. This is relevant if the input data is log1p. See documentation for details. Note that scanpy.rank_genes_groups assumes the data to be log1p, and exponentiates post aggregation by default.
layer (str or None, default=None) – Layer in adata.layers to use for the data. If None, uses adata.X.
groups (list of values or None, default=None) – Subset of groups to test. If None, tests all groups. This arguments serves the same purpose as scanpy’s groups argument in rank_genes_groups. It is used to filter which groups to compare against the reference in the OVO scenario, or which groups to compare against the rest in the OVR scenario. Note that in the OVR scenario, each comparison still happens against the entirety of the other groups, not just the ones listed in this argument. Note that in the OVO scenario, the reference group is automatically added. Order of the values in this list has no impact on the end results, duplicates will be trimmed away.
exclude_from_ovr (list of values or None, default=None) – Subset of groups to exclude from the rest group in the OVR scenario (when reference=None). This argument is ignored in the OVO scenario. This can be useful if, for instance, one of the groups is corrupted and contains meaningless data, and we don’t want it to be part of the comparisons in the OVR scenario. Order of the values in this list has no impact on the end results, duplicates will be trimmed away.
precompile (bool, default=True) – Whether to precompile necessary functions for performance. It is recommended to set this to True.
use_rust (bool, default=True) – Whether to use the Rust implementation of the test. If False, uses the Numba implementation.
return_as_scanpy (bool, default=False) – Whether to return results in a format compatible with Scanpy’s rank_genes_groups function. If yes, the output is a dictionary that can be attached to the adata object like this: adata.uns[‘rank_genes_groups’] = asymptotic_wilcoxon(…, return_as_scanpy=True)
n_genes (int or None, default=None) – Number of top genes to return per group, sorted by z-score. If None, returns all genes. This is relevant only if return_as_scanpy=True, as Scanpy’s rank_genes_groups function expects the results to be sorted by significance. If return_as_scanpy=False, the results are not sorted and n_genes is ignored.
corr_method (str, default="benjamini-hochberg") – Method to use for multiple testing correction. One of ‘benjamini-hochberg’ or ‘bonferroni’.
- Returns:
A DataFrame with MultiIndex (pert, feature) containing columns: - ‘p_value’: P-value from the Mann-Whitney test - ‘statistic’: Test statistic (U-statistic) - ‘z-scores’: Test z-score - ‘fold_change’: Fold change between groups Or a dictionary formatted for Scanpy’s rank_genes_groups results, containing: - ‘params’: Dictionary of parameters used for the test - ‘names’: Record array of gene names sorted by significance for each group - ‘scores’: Record array of test statistics sorted by significance for each group - ‘pvals’: Record array of p-values sorted by significance for each group - ‘pvals_adj’: Record array of adjusted p-values sorted by significance for each group - ‘logfoldchanges’: Record array of log2 fold changes sorted by significance for each group
- Return type:
Either one of pd.DataFrame or Dict, depending on the value of return_as_scanpy
- Raises:
ValueError – If input data matrix indices are not sorted (for sparse CSR matrices). If batch_size is not ‘~<int>’ or a positive integer.
Examples
>>> import anndata as ad >>> import numpy as np >>> import pandas as pd >>> >>> # Create example AnnData object >>> n_cells, n_genes = 1000, 500 >>> X = np.random.negative_binomial(5, 0.3, size=(n_cells, n_genes)) >>> obs = pd.DataFrame({'cell_type': np.random.choice(['A', 'B', 'C'], n_cells)}) >>> var = pd.DataFrame(index=[f'gene_{i}' for i in range(n_genes)]) >>> adata = ad.AnnData(X=X, obs=obs, var=var) >>> >>> # Perform one-versus-rest tests >>> results = asymptotic_wilcoxon( ... adata, ... is_log1p=False, ... group_keys='cell_type', ... n_threads=4 ... ) >>> print(results.head()) >>> >>> # Perform one-versus-one tests against reference >>> results_ovo = asymptotic_wilcoxon( ... adata, ... is_log1p=False, ... group_keys='cell_type', ... reference='A', ... n_threads=4, ... alternative='greater' ... ) >>> >>> # Filter significant results >>> significant = results[results['p_value'] < 0.05] >>> print(f"Found {len(significant)} significant tests")
Notes
The function automatically handles both dense and sparse matrices. For sparse CSR matrices, indices must be sorted per row to ensure correct results.
Author: Rémy Dubois