rapids_singlecell.tl.ingest

rapids_singlecell.tl.ingest(adata, adata_ref, *, obs=None, embedding_method=('umap', 'pca'), labeling_method='knn', neighbors_key=None, algorithm='brute', algorithm_kwds=mappingproxy({}), inplace=True)

Map labels and embeddings from reference data to new data.

This is a GPU implementation of scanpy.tl.ingest(). It projects the query into the representation used to construct the reference neighbor graph, transfers labels by k-nearest-neighbor majority vote, and can map reference PCA and UMAP embeddings.

For centered PCA, the query is centered with the reference feature means. This is the fixed-reference PCA transform and makes the projection independent of which other query observations are ingested in the same call.

Parameters:

adata AnnData

Query data whose annotations and embeddings will be inferred.

adata_ref AnnData

Reference data with a precomputed neighbor graph and the annotations and embeddings to map. Variables must match adata in the same order.

obs str | Iterable[str] | None (default: None)

One or more columns from adata_ref.obs to map to adata.obs.

embedding_method Union[Literal['umap', 'pca'], Iterable[Literal['umap', 'pca']]] (default: ('umap', 'pca'))

Reference embeddings to map. Supported values are "pca" and "umap".

labeling_method Union[Literal['knn'], Iterable[Literal['knn']]] (default: 'knn')

Label transfer method for each requested obs column. Only "knn" is supported. A single value is reused for all columns.

neighbors_key str | None (default: None)

Key containing the reference neighbor metadata in adata_ref.uns. Defaults to "neighbors".

algorithm Literal['brute', 'cagra', 'ivfflat', 'ivfpq', 'mg_ivfflat', 'mg_ivfpq'] (default: 'brute')

GPU nearest-neighbor algorithm used for label transfer. "brute" is exact and is the only option that supports sparse representations.

algorithm_kwds Mapping[str, Any] (default: mappingproxy({}))

Options passed to the nearest-neighbor algorithm.

inplace bool (default: True)

Update adata in place. If False, return an updated copy.

Return type:

AnnData | None

Returns:

If inplace=False, returns an updated AnnData. Otherwise updates adata and returns None. Requested labels are stored in adata.obs and embeddings in adata.obsm['X_pca'] and/or adata.obsm['X_umap'].

Notes

A custom representation recorded in the reference neighbor parameters must also exist in adata.obsm and already share the reference coordinate system. Query X_pca is never reused: it is always projected with the reference PCA model.