The cells a Cellucid subsample keeps — cellucid_subsample

cellucid_subsample_cells() gives the cells a subsample keeps: the cells the Cellucid web app opens for the same request (Open data, Cells to open), and the cells cellucid.subsample_cells() gives in Python. Use it to take the cells the viewer showed, or to choose cells the same way before opening.

Usage

cellucid_subsample_cells(x, n_cells = NULL, fraction = NULL, method = "uniform", seed = 0,
  groupby = NULL, allocation = "proportional", min_per_group = 0,
  block_size = NULL, basis = NULL, columns = c(1, 2), grid_size = 32)

Arguments

x: A Seurat object, a SingleCellExperiment or SummarizedExperiment, a data.frame of cells, or the cell count itself (enough for "uniform" and "blocks"). Its cells are taken by their original positions: an object read from a Cellucid-ready file in priority order (its cellucid record holds priority) is refused until cellucid_restore_original_order puts it back, as cellucid_pull(), cellucid_subset() and a session refuse it.
n_cells: How many cells to keep; or give fraction. A count of every cell or more keeps every cell.
fraction: The share of cells to keep, in (0, 1]; the count is n * fraction rounded half up, at least 1, computed exactly from the fraction's shortest round-trip decimal text (found in exact integer arithmetic, the same text on every platform), never as a floating-point product, as the web app and Python compute it. Any count from 1 is a selection here; the web app opens a subsample of at least 2 cells, since one cell has no coordinate variation to draw.
method: "uniform" (every cell alike), "blocks" (runs of block_size neighbouring cells in file order, kept together), "stratified" (split over the categories of groupby) or "spatial" (split over the occupied boxes of a grid_size grid on basis, balanced, so sparse regions keep their cells).
seed: A whole number in [0, 2^32 - 1]. The same seed keeps the same cells; with "uniform" and "blocks" a smaller subsample is inside a larger one.
groupby: "stratified": a cell metadata column name (meta.data, colData), or one value per cell (a factor keeps its level order). Cells without a value are one more stratum.
allocation: "stratified": "proportional" (largest remainder) or "balanced" (equal shares, water-filled).
min_per_group: "stratified": each category first gets this many cells (or all it has).
block_size: "blocks": cells per block. The web app derives it from the file's chunk layout and shows it; give that value to reproduce its cells.
basis: "spatial": a reduction name (a Seurat reduction, a reducedDim), or a matrix of coordinates, one row per cell.
columns: "spatial": the embedding columns used, one to three.
grid_size: "spatial": boxes per axis.

Value

The kept cells' original positions (1-based, ascending): an integer vector, or a double one for an object of more cells than an R integer counts. They are the object's own columns (rows of a data frame), so x[, kept] holds the cells the viewer opens.

Details

All three follow one subsampling specification: a cell's rank is a 32-bit hash of the seed and its position, and the lowest ranks are kept (within each stratum, for "stratified" and "spatial"). The computation is native code (exact 32- and 64-bit integer arithmetic, and the spatial grid in binary64 operations that are never fused), held with the web app and the Python package to one shared conformance fixture (tests/testthat/fixtures/subsample_conformance.json).

Examples

kept <- cellucid_subsample_cells(10000, fraction = 0.1, seed = 0)
length(kept)
#> [1] 1000
cells <- data.frame(type = rep(c("B", "T", "NK"), length.out = 300))
kept <- cellucid_subsample_cells(cells, 30, method = "stratified", groupby = "type")
table(cells$type[kept])
#> 
#>  B NK  T 
#> 10 10 10 
# An object read from a Cellucid-ready file holds its cells in priority
# order: put them back first, x <- cellucid_restore_original_order(x).