cuspa.tl.aggregate_to_cells

cuspa.tl.aggregate_to_cells(

batches: Iterable[tuple[Any, Any]],

polygons: Polygons,

num_genes: int,

*,

num_cells: int | None = None,

stream: int = 0,

) → CSRMatrix

Aggregate transcript batches into one GPU-resident (cells × genes) CSR.

Each batch is a (points, gene_ids) pair of CuPy arrays. Batches are consumed one at a time; this function does not read files or choose a batch size. The returned CSR has sorted, duplicate-free int32 data.

Parameters:

batches

Iterable of (points, gene_ids) CuPy CUDA-array pairs. The iterable is consumed one batch at a time; earlier point and gene-id arrays are not retained after their sparse contribution is merged.

polygons

Cell polygons shared by every batch.

num_genes

Number of gene columns in the output matrix.

num_cells

Output row count. Defaults to polygons.num_polygons.

stream

CUDA stream handle for native kernels. 0 means the default stream. The corresponding CuPy stream must also be current because buffer copies and sparse merging use CuPy’s current stream.

Returns:

CSRMatrix

Sparse count matrix across all batches, stored on the GPU.

Notes

Batch merging uses float32 sparse matrices. Counts for a (cell, gene) pair must be below 2**24.