Command line

Installing rctd-py adds an rctd command with three subcommands:

rctd info                                   # versions, GPU availability (--json for machines)
rctd validate spatial.h5ad reference.h5ad   # fast input checks, no GPU needed
rctd run spatial.h5ad reference.h5ad        # deconvolve (default: doublet mode)

rctd run spatial.h5ad reference.h5ad \
    --mode doublet --output results.h5ad --device cuda \
    --batch-size 5000 --umi-min 20 --cell-type-col cell_type

rctd run spatial.h5ad reference.h5ad --json --quiet   # JSON summary for pipelines

Both positional arguments accept a .h5ad file, an AnnData Zarr store or a SpatialData Zarr store. In a spatial SpatialData store with several tables, name one with --table (or point at store.zarr/tables/<name>); --table applies to the spatial input only, so a multi-table reference store takes the store.zarr/tables/<name> path. Results are always written as .h5ad; the input is never modified.

Output

Results are written into a copy of the spatial input, by default <spatial_stem>_rctd.h5ad.

Slot	Content	Modes
.obsm["rctd_weights"]	cell type weights (N x K)	all
.obs["rctd_dominant_type"]	highest weight in rctd_weights (the full-mode fit; in doublet mode it can differ from rctd_first_type)	all
.obs["rctd_spot_class"]	singlet / doublet_certain / doublet_uncertain / reject	doublet
.obs["rctd_first_type"], .obs["rctd_second_type"]	primary and secondary type	doublet
.obs["rctd_first_class"], .obs["rctd_second_class"]	type only certain at class level (class_df)	doublet
.obs["rctd_first_class_name"], .obs["rctd_second_class_name"]	class of each type	doublet with --class-df
.obsm["rctd_weights_doublet"]	doublet weights (N x 2)	doublet
.obs["rctd_converged"]	convergence flag	full
.obs["rctd_n_types"]	number of types per pixel	multi
.obsm["rctd_sub_weights"], .obsm["rctd_cell_type_indices"]	selected types and their weights	multi
.uns["rctd_mode"], .uns["rctd_config"], .uns["rctd_version"], .uns["rctd_cell_type_names"]	run metadata	all

Pixels that were not fitted get NaN weights and "filtered" labels: total UMI outside --umi-min / --umi-max, or fewer than counts_MIN (10) counts on the bulk gene list.

Reference

rctd

rctd-py: GPU-accelerated cell type deconvolution for spatial transcriptomics.

.. program:: rctd .. rubric:: Usage

.. code-block:: shell

rctd [OPTIONS] COMMAND [ARGS]...

.. rubric:: Options

.. option:: –version

Show the version and exit.

info

Show version, device, and environment information.

.. program:: rctd info .. rubric:: Usage

.. code-block:: shell

rctd info [OPTIONS]

.. rubric:: Options

.. option:: –json

Output as JSON.

run

Run RCTD deconvolution on spatial transcriptomics data.

.. program:: rctd run .. rubric:: Usage

.. code-block:: shell

rctd run [OPTIONS] SPATIAL REFERENCE

.. rubric:: Options

.. option:: –table

SpatialData stores only: name of the table to read from the SPATIAL store when it holds several.

.. option:: –cell-type-col <cell_type_col>

Column in reference .obs for cell type labels.

:default: ``'cell_type'``

.. option:: –mode

Deconvolution mode.

:default: ``'doublet'``
:options: full | doublet | multi

.. option:: -o, –output

Output h5ad path. [default: <spatial_stem>_rctd.h5ad]

.. option:: –json

Print structured JSON summary to stdout.

.. option:: -q, –quiet

Suppress progress messages.

.. option:: –gene-cutoff <gene_cutoff>

:default: ``0.000125``

.. option:: –fc-cutoff <fc_cutoff>

:default: ``0.5``

.. option:: –gene-cutoff-reg <gene_cutoff_reg>

:default: ``0.0002``

.. option:: –fc-cutoff-reg <fc_cutoff_reg>

:default: ``0.75``

.. option:: –umi-min <umi_min>

Minimum UMI count per pixel.

:default: ``100``

.. option:: –umi-max <umi_max>

:default: ``20000000``

.. option:: –umi-min-sigma <umi_min_sigma>

:default: ``300``

.. option:: –max-multi-types <max_multi_types>

:default: ``4``

.. option:: –confidence-threshold <confidence_threshold>

:default: ``5.0``

.. option:: –doublet-threshold <doublet_threshold>

:default: ``20.0``

.. option:: –dtype

:default: ``'float64'``
:options: float32 | float64

.. option:: –device

:default: ``'auto'``
:options: auto | cpu | cuda

.. option:: –no-compile

Disable torch.compile: skips the first-run compile (up to hours on torch<2.14) at about 15% slower runs; also for environments without CUDA headers.

.. option:: –eigh-threshold <eigh_threshold>

Override the K cutoff for GPU eigh in _psd_batch. K<=threshold stays on GPU; K>threshold offloads to CPU LAPACK. Default is arch-based (16 on sm_<9, 128 on sm_>=9). Raising it helps only with CUDA 13+; with CUDA 11.8/12.1 GPU eigh was 3-7x slower on an L40S.

.. option:: –batch-size <batch_size>

GPU batch size for pixel processing.

:default: ``10000``

.. option:: –sigma-override <sigma_override>

Skip sigma estimation, use this value directly.

.. option:: –cell-min <cell_min>

Minimum cells per type in reference.

:default: ``25``

.. option:: –n-max-cells <n_max_cells>

Max cells per type for downsampling.

:default: ``10000``

.. option:: –min-umi-ref <min_umi_ref>

Minimum UMI for reference cells.

:default: ``100``

.. option:: –class-df <class_df_path>

Doublet mode: TSV with 'cell_type' and 'class' columns mapping subtypes to higher-level classes for hierarchical fallback. See README for usage.

.. rubric:: Arguments

.. option:: SPATIAL

Required argument

.. option:: REFERENCE

Required argument

validate

Validate inputs before running RCTD (fast, no GPU needed).

.. program:: rctd validate .. rubric:: Usage

.. code-block:: shell

rctd validate [OPTIONS] SPATIAL REFERENCE

.. rubric:: Options

.. option:: –table

SpatialData stores only: name of the table to read from the SPATIAL store when it holds several.

.. option:: –cell-type-col <cell_type_col>

Column in reference .obs for cell type labels.

:default: ``'cell_type'``

.. option:: –umi-min <umi_min>

Minimum UMI count per pixel.

:default: ``100``

.. option:: –cell-min <cell_min>

Minimum cells per cell type in reference.

:default: ``25``

.. option:: –json

Output as JSON.

.. rubric:: Arguments

.. option:: SPATIAL

Required argument

.. option:: REFERENCE

Required argument