rapids-singlecell
rsc.pp, rsc.tl and rsc.get mirror scanpy on the GPU.
rsc.gr, rsc.ptg and rsc.dcg port parts of squidpy, pertpy and decoupler.
Compute with rapids-singlecell (rsc), plot with sc.pl/sq.pl/dc.pl, and leave rsc only for the gaps listed below.
Before you start
Run once in a shell:
rapids-singlecell-check-kernel # GPU, RMM and CUDA kernels; stop if NOT READY
python -m rapids_singlecell_skills.api map --options # every public rsc symbol with its enum choices
The map reflects the installed version.
Narrow tasks can map one namespace with --namespace pp.
Do not fetch the docs website or read rsc source to discover the API.
For one detail, run python -m rapids_singlecell_skills.api describe rsc.pp.neighbors --parameter algorithm.
If either command fails, read references/setup.md.
Setup code
import rmm
rmm.reinitialize(pool_allocator=True) # before any GPU array, once per process
import cupy as cp
from rmm.allocators.cupy import rmm_cupy_allocator
cp.cuda.set_allocator(rmm_cupy_allocator)
import rapids_singlecell as rsc
import scanpy as sc
from anndata.acc import A
- The pool is fastest when data fit in VRAM.
Importing rsc alone installs RMM without a pool.
- If data do not fit, use
rmm.reinitialize(managed_memory=True) instead.
For Dask, multi-GPU or data far beyond VRAM, read references/dask.md.
Where data live
- Only
X, and layers you move yourself, live on the GPU.
rsc writes obs, var, obsm, obsp and uns results to the host.
rsc.pp QC, filter, normalization and HVG functions raise _check_gpu_X on host input.
rsc.get.anndata_to_GPU(adata) moves only X; layer= or convert_all=True adds layers.
- Keep raw counts as a host layer, not
.raw or a GPU copy.
rsc.get.aggregate and rsc.tl.rank_genes_groups read host data directly.
sc.pl works with a GPU X when coloring by obs or obsm.
Call rsc.get.anndata_to_CPU(adata) once before plotting gene expression.
- Check
type(adata.X) instead of converting defensively or hand-rolling converters.
- Like scanpy 1.13, read with
use=A.layers["counts"] and write with out= (an accessor, or True to return).
layer, obsm, use_rep, key_added, inplace and copy are deprecated.
calculate_qc_metrics returns its metrics unless out=False.
Standard workflow
Inspect first: shape, whether X holds integer counts, and which obs columns hold the biological sample, batch and condition.
sample and condition stand for the dataset’s own columns.
Convert dense counts to CSR (scipy.sparse.csr_matrix) before moving them to the GPU.
Cross-tabulate sample against condition, because a batch nested in condition cannot be corrected without erasing the condition.
For spatial data, read references/spatial.md first; its QC and normalization replace those below.
import pandas as pd
from scipy.stats import median_abs_deviation
def qc_outliers(obs: pd.DataFrame, by: str) -> pd.Series:
def mads(col: str) -> pd.Series:
g = obs.groupby(by, observed=True)[col]
return (obs[col] - g.transform("median")) / g.transform(median_abs_deviation)
return (
(mads("log1p_total_counts").abs() > 5)
| (mads("log1p_n_genes_by_counts").abs() > 5)
| ((mads("pct_counts_mt") > 3) & (obs["pct_counts_mt"] > 8))
)
adata.layers["counts"] = adata.X.copy() # host copy of raw counts
rsc.get.anndata_to_GPU(adata)
adata.var["mt"] = adata.var_names.str.startswith(("MT-", "mt-"))
rsc.pp.calculate_qc_metrics(adata, qc_vars=["mt"], out=False)
adata = adata[~qc_outliers(adata.obs, by="sample").to_numpy()].copy()
rsc.pp.scrublet(adata, batch=A.obs["sample"], verbose=False) # raw counts
adata = adata[~adata.obs["predicted_doublet"].to_numpy()].copy()
rsc.pp.filter_genes(adata, min_cells=20)
rsc.pp.highly_variable_genes(adata, n_top_genes=2000, flavor="seurat_v3")
rsc.pp.normalize_total(adata) # median depth
rsc.pp.log1p(adata)
rsc.pp.pca(adata, n_comps=50)
rsc.pp.harmony_integrate(adata, A.obs["sample"]) # only if batches share biology
rsc.pp.neighbors(adata, use=A.obsm["X_pca_harmony"]) # A.obsm["X_pca"] without integration
rsc.tl.leiden(adata, resolution=[0.25, 0.5, 1.0, 2.0]) # one graph, keys leiden_<res>
rsc.tl.umap(adata)
rsc.tl.rank_genes_groups(adata, "leiden_1.0", method="wilcoxon", pts=True)
Defaults that override old tutorials
- QC thresholds are per-sample MADs, shown on the distributions before filtering.
Flag rather than drop high-mito cells in tumors or metabolically active tissue.
- Correct ambient RNA (CellBender, SoupX) only when contamination is evident, and keep the uncorrected counts.
- Score doublets per sample and remove them before clustering.
- Normalize to median depth, not
target_sum=1e4 or 1e6.
Do not scale (it densifies X) or regress_out before PCA.
- Select about 2000
seurat_v3 HVGs on raw counts, where batch=A.obs["sample"] is optional.
- Integrate only when the uncorrected embedding separates technical batches that share biology.
Start with Harmony and move to scVI/scANVI for complex or cross-system batches.
- Verify integration kept biology with known markers or scib-metrics, not UMAP inspection.
- Leiden partitions change with the seed.
Sweep resolutions with 3 to 5
rng values; keep those whose labels agree across seeds (ARI) and whose clusters have distinct markers.
- GPU PCA on sparse input is not bitwise reproducible across reruns and can shift cluster boundaries.
Save final labels in the AnnData instead of rerunning.
- Marker p-values after clustering are only for ranking because the same data defined the clusters.
Filter markers by
pts detection fractions and effect size.
- Annotate clusters from positive and negative markers (score marker sets with
rsc.dcg.ulm and compare cluster means) or reference transfer (CellTypist, scANVI).
Use unknown for weak or tied evidence and treat LLM-proposed labels as hypotheses.
- UMAP is display only, so never infer distances, relatedness or trajectories from it.
- Comparing conditions needs biological replicates and pseudobulk, so read references/conditions.md first.
- Use foundation-model embeddings only on request and next to a PCA, Harmony or scVI baseline, which they usually do not beat.
Fast paths
rsc.pp.neighbors defaults to exact brute, which is fine up to about 500k cells.
Above that use algorithm="nn_descent" (5x faster at 2M cells, recall 0.99), not ivfflat (recall 0.72 by default).
- Use
rank_genes_groups(method="wilcoxon_binned") for Dask input or tens of millions of cells.
- Do not rerun steps on CPU to validate or benchmark them unless asked.
Outside rsc
| Need |
Use |
| Ambient RNA |
CellBender, SoupX |
| scVI, scANVI, sysVI |
scvi-tools |
| Annotation |
CellTypist, scANVI |
| Integration metrics |
scib-metrics |
| Pseudobulk DE |
PyDESeq2 on rsc.get.aggregate output |
| Pathway resources and plots |
decoupler dc.op, dc.pl, scoring with rsc.dcg |
| Cell-cell communication across samples |
LIANA+ |
| Neighborhood enrichment |
squidpy |
| Condition & perturbation analysis |
pertpy |
Never replace a missing rsc capability with a silent CPU reimplementation.
For CRISPR screens and perturbation distances, read references/perturbation.md.
Deliverables
Use a notebook for multi-step workflows or when asked.
Otherwise a script is fine.
- Check outputs against data scale.
Hundreds of clusters, clusters near cell count, or figures of hundreds of megapixels mean stop and fix.
- Follow requested choices unless the data or design make them invalid.
Then show the evidence and propose an alternative.
In a notebook:
- One stage per cell, under about 25 lines.
Plot right after the computation it shows, then interpret in a short markdown cell.
- Never paste standalone scripts into notebook cells.
- Record package versions at the end of the notebook with
session_info2.
- While developing, test new stages on an AnnData checkpoint saved after preprocessing, not by re-executing the notebook.
- Execute top to bottom in a fresh kernel with
jupyter nbconvert --to notebook --execute --inplace and read every output.
- Deliver the executed notebook, the final AnnData, and a short markdown report of findings, evidence and limitations.
1---2name: rapids-singlecell3description: "Read before writing any rapids-singlecell code (`import rapids_singlecell as rsc`) or running scanpy-, squidpy-, decoupler- or pertpy-style analysis on a GPU. Covers QC, doublets, normalization, HVGs, PCA, integration, clustering, UMAP, markers, annotation, pseudobulk DE, pathway scoring, CRISPR screens, spatial statistics and niches, out-of-core or multi-GPU runs, and GPU setup. rsc differs from scanpy in where data live and in defaults."4metadata:5 source: https://skillmd.com/skills/scverse/rapids-singlecell6---78# rapids-singlecell910`rsc.pp`, `rsc.tl` and `rsc.get` mirror scanpy on the GPU.11`rsc.gr`, `rsc.ptg` and `rsc.dcg` port parts of squidpy, pertpy and decoupler.12Compute with rapids-singlecell (rsc), plot with `sc.pl`/`sq.pl`/`dc.pl`, and leave rsc only for the gaps listed below.1314## Before you start1516Run once in a shell:1718```bash19rapids-singlecell-check-kernel # GPU, RMM and CUDA kernels; stop if NOT READY20python -m rapids_singlecell_skills.api map --options # every public rsc symbol with its enum choices21```2223The map reflects the installed version.24Narrow tasks can map one namespace with `--namespace pp`.25Do not fetch the docs website or read rsc source to discover the API.26For one detail, run `python -m rapids_singlecell_skills.api describe rsc.pp.neighbors --parameter algorithm`.27If either command fails, read [references/setup.md](references/setup.md).2829## Setup code3031```python32import rmm3334rmm.reinitialize(pool_allocator=True) # before any GPU array, once per process35import cupy as cp36from rmm.allocators.cupy import rmm_cupy_allocator3738cp.cuda.set_allocator(rmm_cupy_allocator)39import rapids_singlecell as rsc40import scanpy as sc41from anndata.acc import A42```4344- The pool is fastest when data fit in VRAM.45 Importing rsc alone installs RMM without a pool.46- If data do not fit, use `rmm.reinitialize(managed_memory=True)` instead.47 For Dask, multi-GPU or data far beyond VRAM, read [references/dask.md](references/dask.md).4849## Where data live5051- Only `X`, and layers you move yourself, live on the GPU.52 rsc writes `obs`, `var`, `obsm`, `obsp` and `uns` results to the host.53- `rsc.pp` QC, filter, normalization and HVG functions raise `_check_gpu_X` on host input.54 `rsc.get.anndata_to_GPU(adata)` moves only `X`; `layer=` or `convert_all=True` adds layers.55- Keep raw counts as a host layer, not `.raw` or a GPU copy.56 `rsc.get.aggregate` and `rsc.tl.rank_genes_groups` read host data directly.57- `sc.pl` works with a GPU `X` when coloring by `obs` or `obsm`.58 Call `rsc.get.anndata_to_CPU(adata)` once before plotting gene expression.59- Check `type(adata.X)` instead of converting defensively or hand-rolling converters.60- Like scanpy 1.13, read with `use=A.layers["counts"]` and write with `out=` (an accessor, or `True` to return).61 `layer`, `obsm`, `use_rep`, `key_added`, `inplace` and `copy` are deprecated.62 `calculate_qc_metrics` returns its metrics unless `out=False`.6364## Standard workflow6566Inspect first: shape, whether `X` holds integer counts, and which `obs` columns hold the biological sample, batch and condition.67`sample` and `condition` stand for the dataset’s own columns.68Convert dense counts to CSR (`scipy.sparse.csr_matrix`) before moving them to the GPU.69Cross-tabulate sample against condition, because a batch nested in condition cannot be corrected without erasing the condition.70For spatial data, read [references/spatial.md](references/spatial.md) first; its QC and normalization replace those below.7172```python73import pandas as pd74from scipy.stats import median_abs_deviation757677def qc_outliers(obs: pd.DataFrame, by: str) -> pd.Series:78 def mads(col: str) -> pd.Series:79 g = obs.groupby(by, observed=True)[col]80 return (obs[col] - g.transform("median")) / g.transform(median_abs_deviation)8182 return (83 (mads("log1p_total_counts").abs() > 5)84 | (mads("log1p_n_genes_by_counts").abs() > 5)85 | ((mads("pct_counts_mt") > 3) & (obs["pct_counts_mt"] > 8))86 )87```8889```python90adata.layers["counts"] = adata.X.copy() # host copy of raw counts91rsc.get.anndata_to_GPU(adata)92adata.var["mt"] = adata.var_names.str.startswith(("MT-", "mt-"))93rsc.pp.calculate_qc_metrics(adata, qc_vars=["mt"], out=False)94adata = adata[~qc_outliers(adata.obs, by="sample").to_numpy()].copy()95rsc.pp.scrublet(adata, batch=A.obs["sample"], verbose=False) # raw counts96adata = adata[~adata.obs["predicted_doublet"].to_numpy()].copy()97rsc.pp.filter_genes(adata, min_cells=20)98rsc.pp.highly_variable_genes(adata, n_top_genes=2000, flavor="seurat_v3")99rsc.pp.normalize_total(adata) # median depth100rsc.pp.log1p(adata)101rsc.pp.pca(adata, n_comps=50)102rsc.pp.harmony_integrate(adata, A.obs["sample"]) # only if batches share biology103rsc.pp.neighbors(adata, use=A.obsm["X_pca_harmony"]) # A.obsm["X_pca"] without integration104rsc.tl.leiden(adata, resolution=[0.25, 0.5, 1.0, 2.0]) # one graph, keys leiden_<res>105rsc.tl.umap(adata)106rsc.tl.rank_genes_groups(adata, "leiden_1.0", method="wilcoxon", pts=True)107```108109## Defaults that override old tutorials110111- QC thresholds are per-sample MADs, shown on the distributions before filtering.112 Flag rather than drop high-mito cells in tumors or metabolically active tissue.113- Correct ambient RNA (CellBender, SoupX) only when contamination is evident, and keep the uncorrected counts.114- Score doublets per sample and remove them before clustering.115- Normalize to median depth, not `target_sum=1e4` or `1e6`.116 Do not `scale` (it densifies `X`) or `regress_out` before PCA.117- Select about 2000 `seurat_v3` HVGs on raw counts, where `batch=A.obs["sample"]` is optional.118- Integrate only when the uncorrected embedding separates technical batches that share biology.119 Start with Harmony and move to scVI/scANVI for complex or cross-system batches.120- Verify integration kept biology with known markers or scib-metrics, not UMAP inspection.121- Leiden partitions change with the seed.122 Sweep resolutions with 3 to 5 `rng` values; keep those whose labels agree across seeds (ARI) and whose clusters have distinct markers.123- GPU PCA on sparse input is not bitwise reproducible across reruns and can shift cluster boundaries.124 Save final labels in the AnnData instead of rerunning.125- Marker p-values after clustering are only for ranking because the same data defined the clusters.126 Filter markers by `pts` detection fractions and effect size.127- Annotate clusters from positive and negative markers (score marker sets with `rsc.dcg.ulm` and compare cluster means) or reference transfer (CellTypist, scANVI).128 Use `unknown` for weak or tied evidence and treat LLM-proposed labels as hypotheses.129- UMAP is display only, so never infer distances, relatedness or trajectories from it.130- Comparing conditions needs biological replicates and pseudobulk, so read [references/conditions.md](references/conditions.md) first.131- Use foundation-model embeddings only on request and next to a PCA, Harmony or scVI baseline, which they usually do not beat.132133## Fast paths134135- `rsc.pp.neighbors` defaults to exact `brute`, which is fine up to about 500k cells.136 Above that use `algorithm="nn_descent"` (5x faster at 2M cells, recall 0.99), not `ivfflat` (recall 0.72 by default).137- Use `rank_genes_groups(method="wilcoxon_binned")` for Dask input or tens of millions of cells.138- Do not rerun steps on CPU to validate or benchmark them unless asked.139140## Outside rsc141142 | Need | Use |143 | -------------------------------------- | -------------------------------------------------- |144 | Ambient RNA | CellBender, SoupX |145 | scVI, scANVI, sysVI | scvi-tools |146 | Annotation | CellTypist, scANVI |147 | Integration metrics | scib-metrics |148 | Pseudobulk DE | PyDESeq2 on `rsc.get.aggregate` output |149 | Pathway resources and plots | decoupler `dc.op`, `dc.pl`, scoring with `rsc.dcg` |150 | Cell-cell communication across samples | LIANA+ |151 | Neighborhood enrichment | squidpy |152 | Condition & perturbation analysis | pertpy |153154Never replace a missing rsc capability with a silent CPU reimplementation.155For CRISPR screens and perturbation distances, read [references/perturbation.md](references/perturbation.md).156157## Deliverables158159Use a notebook for multi-step workflows or when asked.160Otherwise a script is fine.161162- Check outputs against data scale.163 Hundreds of clusters, clusters near cell count, or figures of hundreds of megapixels mean stop and fix.164- Follow requested choices unless the data or design make them invalid.165 Then show the evidence and propose an alternative.166167In a notebook:168169- One stage per cell, under about 25 lines.170 Plot right after the computation it shows, then interpret in a short markdown cell.171- Never paste standalone scripts into notebook cells.172- Record package versions at the end of the notebook with `session_info2`.173- While developing, test new stages on an AnnData checkpoint saved after preprocessing, not by re-executing the notebook.174- Execute top to bottom in a fresh kernel with `jupyter nbconvert --to notebook --execute --inplace` and read every output.175- Deliver the executed notebook, the final AnnData, and a short markdown report of findings, evidence and limitations.