For each cell x piece, the candidates of cell_piece_candidates() (1:1 plus every oriented (cn_a, cn_b) a kept
clone has on the piece; haploid pieces: one-copy states) are scored with the cell's own evidence
(cell_piece_data()); the cell's clone assignment is not used.
Depth:
ll_depth_shift(z, mu, tpar)withmu = c * log2(max(cn, 0.2) / base) / pmax(sd, sd_floor)(the shift model of the clone states,fit_clone_states()/assign_cells():base= the piece ploidy when the depth is centred on the reference pool, else 2), relative to the neutral state's shift (the neutral state's own depth term isll_depth_shift(z, 0) = 0), Student-t null per sd_class x stratum (fit_depth_null()parameters, fallbacks as inassign_cells()) or Gaussian whentparis NULL.Alleles: one-sided beta-binomial LLR vs 1:1 of the oriented votes
(oA, oN)at the expected cn_a fraction0.5 + a * (cn_a / cn - 0.5)(a= orientation attenuation of the clone model; 0.5 for cn = 0), overdispersionrho; haploid pieces have no allele term.MAP over the candidates with the prior (
neutral,uniformorclone_freq);posterioris the MAP's posterior andllr_neutralthe log-likelihood (no prior) of the MAP minus that of the neutral state.
Usage
cell_piece_states(
features,
pieces,
blocks = NULL,
cells = NULL,
params = caller_defaults(),
prior = c("neutral", "uniform", "clone_freq"),
p_neutral = 0.5,
clones = NULL,
c = NULL,
a = NULL,
rho = "ref",
tpar = NULL,
ref_cells = NULL,
loo = NULL,
normal = "N0",
sd_scale = TRUE,
ref_center = c("pseudobulk", "mean"),
center = TRUE,
s_sys = NULL,
haploid_sd = sqrt(2),
data = NULL,
keep_ll = FALSE,
rho_grid = c(0.005, 0.01, 0.02, 0.03, 0.05, 0.08, 0.12, 0.18, 0.25)
)Arguments
- features
scn_features list (see
cell_piece_data())- pieces
clone x piece table with
cn_a, cn_b(orient_clone_states()$pieces or the export's pieces.tsv), or amedicc2_orientation- blocks
block orientation (orient_clone_states()$blocks); NULL takes it from a
medicc2_orientation- cells
cells to score (default all)
- params
caller_defaults()(sd_floor,eps,tile_sizes)- prior
neutral(default),uniformorclone_freq(seecell_piece_candidates()). Under the uniform prior a short piece with many candidates and little evidence goes to whichever non-neutral state fits marginally better, so many rows of normal cells get non-neutral states;clone_freqgives uninformative cells the majority clone state (tumour states in normal cells)- p_neutral
neutral prior mass of
prior = "neutral"- clones
clones table (
clone, c, a, n_assigned); used for the defaultc/aand theclone_freqprior- c, a
global depth contrast and allelic attenuation (NULL = cell-weighted median of the tumour clones; 1 when
cloneslacks them)- rho
beta-binomial overdispersion of a cell's oriented votes on a piece: a number;
"ref"= fitted (fit_bb_rho(), f = 0.5) on the reference cells' oriented votes (diploid pieces; the reference pool is balanced everywhere, so it is the null of the allele channel, as it is the per-cell null of the caller);"auto"= the value ofrho_gridthat maximises the marginal likelihood of all scored cell x piece rows over their candidates (with the prior); NULL = the features' / run's allelic null rho. The run's null rho is fitted on votes oriented by the all-cell pseudobulk, which on event-free regions is a random orientation; in the true haplotype frame of the block orientation a single cell's votes on a piece are far more dispersed (often by an order of magnitude).- tpar
depth null t parameters (class, stratum, t_m, t_s, t_df) or NULL (Gaussian)
- ref_cells
reference pool for the depth centring
- loo
NULL or data.table cell, clone (see
cell_piece_data())- normal
name of the normal clone (excluded from the default c / a)
- sd_scale, ref_center, center, haploid_sd
- s_sys
systematic depth SD added to the per-cell SD (NULL = the cell-weighted median of the tumour clones'
s_sys, 0 whencloneslacks it); seecell_piece_data()- data
precomputed
cell_piece_data()output (skips the depth / vote aggregation)- keep_ll
return the per-candidate log-likelihoods
- rho_grid
grid of
rho = "auto"
Value
list of class cell_piece_states: states (one row per cell x piece: cell, piece, chrom, start, end,
ploidy, cn_a, cn_b, state (MAP), posterior, llr_neutral, ll_depth, ll_allele (MAP terms vs neutral), n_cand, z,
log2ratio, offset, sd, n_win, oA, oN (oriented votes), f_obs (oA / oN), n_blocks), candidates, ll (cell x piece x
candidate, when keep_ll), params (c, a, rho, rho_mode, rho_rows (reference rows of the rho fit), rho_ml (the
auto grid), s_sys, ref_center, center, prior, n_ref, loo, sd_scale, depth_null)
Details
c, a and s_sys are global (one value for every cell): by default the median over the tumour clones (kept clones
of pieces except normal), weighted by their assigned cells, of the clones' fitted c / a / s_sys (clones
table). A per-cell value would have to come from the cell's clone, which this function must not use.