Draw a size-balanced subsample of gated cells across samples

WHAT: returns row indices, per sample, capped so no sample dominates. WHY: event counts differ by orders of magnitude between files. Embedding all cells lets the largest file dictate the manifold and makes "sample" structure indistinguishable from acquisition depth. Drawing about the same number from each sample makes the shared embedding comparable between samples.

Usage

plan_subsample(n_per_sample, cap = 20000L, equalise = TRUE, total_cap = NULL)

Arguments

n_per_sample

named integer vector: sample_id -> number of gated cells.

cap

maximum cells to take from any one sample.

equalise

if TRUE, take min(cap, lower quartile of N) from every sample, or all of a sample's cells where it has fewer; if FALSE, take min(cap, N) per sample.

total_cap

optional overall ceiling on embedded cells; the per-sample allowance is reduced proportionally if the total would exceed it.

Value

named integer vector: sample_id -> number of cells to draw.

Details

WHY THE LOWER QUARTILE AND NOT THE SMALLEST SAMPLE. The level used to be the smallest sample's count, so one sample with few cells shrank every other sample to its size. On one cohort a sample with 393 CD45+ cells cut a map that could have held 59,000 cells down to 5,895, and the populations on it broke into sparse specks. The level is now the lower quartile of the counts: no sample contributes more than it, so none dominates, and the quarter of samples below it contribute every cell they have.