Assign cells to clones by their likelihood under the clone states
Source:R/clones_assign.R
assign_cells.RdPer cell and clone k: the sum over pieces of the depth term ll_depth_shift(z, c_k * log2(cn / 2) / pmax(sd_null, sd_floor), tpar) and the allele term ll_allelic(nA, n, 0.5 + a_k * (f_state - 0.5), rho, two_sided = FALSE) on the cell's votes oriented by clone k's pseudobulk (leave-one-out for k's members).
The depth z is taken relative to the reference cells' mean log2 ratio of each piece (ref_cells;
removes the shared per-region bias of the normalisation). With mixtures, every pair of clones is also
scored as a mixture (weights mix_w; copy numbers mixed; per piece the votes oriented by the pair's clone
that is imbalanced there, as for the single clones, with the other clone's haplotype agreement taken from its
pooled counts under that orientation).
Posterior over singles (prior prior, default uniform) and mixtures (total prior mix_prior); the
reported posterior is the best clone's posterior among the single clones.
Usage
assign_cells(
feat_pieces,
clones,
segments,
tpar,
rho,
par = NULL,
prior = NULL,
mixtures = TRUE,
min_post = 0.9,
mix_prior = 0.05,
ref_cells = NULL,
mix_w = 0.5,
mix_margin = 10,
mix_rel = 0.1,
params = caller_defaults(),
mix_pairs = NULL,
mult_prior = NULL,
trunks = NULL,
max_mix_prior = 0.5
)Arguments
- feat_pieces
list(features = per-cell depth features on the pieces (
region_features()), pieces = regions table, votes, atoms, cells = names in vote index order)- clones
data.table cell, clone: the clone members used for orientation (confident singlets)
- segments
segments table
- tpar
depth null t parameters (
fit_depth_null()) or NULL (Gaussian)- rho
per-cell beta-binomial overdispersion
- par
data.table clone, c, a (from
fit_clone_states()); default c = a = 1- prior
named clone prior (NULL = uniform; a size-proportional prior lets large diffuse clones absorb low-depth cells)
- mixtures
score pairwise 50:50 mixtures
- min_post
posterior needed for
assigned- mix_prior
total prior of the mixture hypotheses
- ref_cells
reference cells for the depth centring (NULL = none); the clone states must be relative to the same reference (
clone_profiles()ref_cells)- mix_w
mixture weights of the first clone of a pair (0.5 = 50:50; e.g. c(1/3, 1/2, 2/3) for unequal nuclei)
- mix_margin
a cell is
doublet_likewhen the mixtures' posterior is > 0.5 and the best mixture beats the best single clone by more than this (log-likelihood)- mix_rel
... and by more than this fraction of the cell's best single-clone log-likelihood ratio (deep cells fit any single clone less perfectly in absolute terms)
- params
- mix_pairs
optional 2-column matrix of the clone pairs scored as mixtures (default all pairs);
caller_tumour()passes the pairs whose states differ allelically on >=mix_min_distbp (clone_state_distance()): a mixture of near-identical (sibling) clones fits a cell between them better than either clone, which is not evidence of a doublet- mult_prior
optional named per-cell multiplet prior probability (e.g. a soft multiplet score): the cell's total mixture prior is max(
mix_prior, prior), capped atmax_mix_prior- trunks
optional named clone -> trunk vector (
clone_trunks()): addstrunkandp_trunk(posterior summed over the clones of the best clone's trunk)- max_mix_prior
cap of the per-cell mixture prior
Value
data.table cell, clone (the likelihood-best single clone, for every cell), posterior, ll_margin,
doublet_like, pair, ref_pool, p_mix, ll_mix_gain, ll_best, mix_prior, assigned / confident (posterior >= min_post
and not doublet-like) (plus trunk, p_trunk when trunks is given; attribute ll: cells x hypotheses log-likelihood matrix)
Details
The hypotheses are the clones with members plus the fixed normal clone N0 whenever segments has it
(caller_tumour() normal_hypothesis), even when no cell is labelled N0 yet: its state is all-neutral, so it
needs no orientation, and without it normal cells would be forced into a tumour clone. Its c is the median c
of par (attenuation 1) when par has no N0 row.