Skip to contents

Starts from all cells of feat_long minus exclude (e.g. multiplet-flagged barcodes). Each iteration fits the depth t null per class x stratum and the allelic rho on the null rows of the current set, scores every candidate cell on the classes regions (chromosomes and arms) with s_comb, thresholds at the selection quantile q and keeps the cells with at most max_calls calls. Every iteration re-evaluates all candidates (a cell dropped earlier can come back), so the set does not ratchet.

Usage

select_null_cells(
  feat_long,
  states = caller_states("normal", params),
  params = caller_defaults(),
  n_iter = 2,
  max_calls = 0,
  exclude = NULL,
  classes = c("chrom", "arm"),
  depth_model = "t",
  threshold = c("parametric", "empirical"),
  q = 0.9999,
  n_sim = NULL,
  chroms = paste0("chr", 1:22)
)

Arguments

feat_long

features long table (cell, region, class, stratum, z, sd_null, nA, n_hap; fold, null_region, eligible optional; chrom optional, else parsed from the region name)

states

state set (caller_states())

params

caller_defaults()

n_iter

iterations

max_calls

cells with more calls than this are not null cells

exclude

cells never in the null set

classes

region classes used for the selection

depth_model

"t" or "gauss"

threshold

"parametric" or "empirical"

q

selection quantile per row

n_sim

simulated rows per class x stratum (parametric; default max(2e4, 20 / (1 - q)))

chroms

chromosomes whose rows are scored (default autosomes chr1-chr22); NULL = all

Value

list(null_cells, log (per iteration), calls (per candidate cell: n_calls, null), tpar, rho, thresholds)

Details

Thresholds (threshold): "parametric" (default) re-draws the null rows under the fitted model (t depth, beta-binomial alleles with robust_rho()) and takes the quantile of the simulated scores; it is not inflated by the events it is meant to find (an empirical 99.9 % quantile of a set in which more than 0.1 % of the rows carry events sits inside the events). "empirical" uses fold-cross-validated quantiles of the current null rows (budget_thresholds()), which is only safe when the starting set is nearly clean. The default q (1e-4 tail per row) keeps the selection from discarding null cells for their expected 1 / 1,000 false calls (~6 % of cells at 63 chromosome + arm rows); the calling thresholds of caller_normal() are empirical at null_q on the selected set.

Only rows on chroms (default the autosomes) are scored: chrX in females carries X-inactivation driven allelic imbalance and male chrX / chrY are depth-only, so a chrX call says little about whether a cell's autosomes are a clean null.