pyucell.compute_ucell_scores

pyucell.compute_ucell_scores#

pyucell.compute_ucell_scores(adata, signatures, layer=None, max_rank=1500, ties_method='average', missing_genes='impute', chunk_size=None, w_neg=1.0, suffix='_UCell', n_jobs=-1, device='cpu')#

Compute UCell scores for an AnnData object.

Parameters:

  • adata (AnnData) – An AnnData object (cells x genes)

  • signatures (Dict[str, List[str]]) – A dictionary of signatures, where the names of the entries are the signature names

  • layer (str, optional) – Which layer to use (None = adata.X).

  • max_rank (int, optional) – Cap ranks at this value (ranks > max_rank are dropped for sparsity).

  • ties_method (str, optional) – Passed to scipy.stats.rankdata on the CPU path. The torch backend (device != None) only supports "min" and "ordinal".

  • missing_genes (str) – “impute”: missing genes get a placeholder -1 (to be treated as max_rank) “skip”: missing genes are simply removed

  • chunk_size (int, optional) – Size of the cell blocks processed at once. Defaults to 500 on CPU and 5000 when device is set (GPUs benefit from larger batches).

  • w_neg (float) – Weight on negative gene sets, when using signatures with positive and negative genes

  • suffix (str, optional) – Suffix to append to column names in adata.obs.

  • n_jobs (int, optional) – Number of parallel jobs (ignored when device is set; GPU chunks run serially to avoid multi-process CUDA init).

  • device (str | None, optional) – "cpu" or None (default): CPU path with joblib parallelism (avoids PyTorch). "cuda" / "mps" / "auto": PyTorch backend for hardware acceleration. Requires the pyucell[gpu] extra.

Returns:

Adds signature scores in adata.obs