A diluted sub-chromosomal imbalance (a 1p loss, a distal CN-LOH) makes the
whole chromosome look like a 2:1 gain: at chromosome scale the allelic term
of the nested event dominates while its depth contrast is diluted, and the
gain state (f 2/3) fits a diluted haplotype fraction better than 1:0 / 2:0.
Per cell, a reportable gain call of a classes region therefore needs
depth support, so that the allelic term alone cannot carry a gain label:
gate = "dl"(default): the gain depth LLR of the row itself is positive (dl_gain > min_dl_gain; for the Student-t null, z above the midpoint between neutral and the gain shift,t_m + mu / 2withmu = shifts["gain"] / pmax(sd_null, sd_floor)). For a noisy cell (largesd_null)muis small and the gate is weak;gate = "z"(opt-in): the row's z exceedsmax(t_m + mu / 2, t_m + t_s * qt(gate_q, t_df))with the Student-t null of the row's class x stratum (tpar,match_depth_null(); withtpar = NULLthe Gaussian null,max(mu / 2, qnorm(gate_q))): the midpoint stays as a floor and the null quantile is added on top. Over all null-depth rows the gate passes about1 - gate_qof them whatever theirsd_null; this level is unconditional. Among rows already called as gains (weak allelic support), and on female chrX (no null rows of its own), the pass rate of null-depth rows is higher: up to about two to three times1 - gate_qin simulation. The gate is opt-in and has not been benchmarked on real data as a default. A row with NA z has no depth support.min_dl_gainis not used. The gate is on z, not ondl_gain: the Student-t LLR falls back towards 0 for very large z (ll_depth_shift()), so a quantile ondl_gainwould reject the strongest gains; and
(class
chrom) no nested explanation: no called loss / CN-LOH row of the same cell and chromosome innestedclasses (arm, 50 Mb, 20 Mb) with a higher score. A gain failing either rule stays in the table withcalled = TRUEbutreportable = FALSEandresolvednaming the reason (no_depth,nested <region> <state>). Withpromote, the best (highest-score) nested loss / CN-LOH call that explains a dropped chromosome gain is made reportable (resolved = "replaces <region> gain"; arm and 50 Mb losses are reportable anyway, a 20 Mb one is promoted). Losses are not gated: the loss vs CN-LOH label is decided by the scores (score_cells()).
Usage
resolve_nested(
calls,
scores = NULL,
min_dl_gain = 0,
classes = c("chrom", "event"),
nested = c("arm", "50Mb", "20Mb"),
promote = TRUE,
gate = c("dl", "z"),
gate_q = 0.95,
tpar = NULL,
params = caller_defaults()
)Arguments
- calls
cell-level calls table (
call_table())- scores
scored rows (
cell,region,dl_gain; withgate = "z"alsoz,sd_nulland, withtpar,class,stratum); NULL whencallshas these columns- min_dl_gain
minimal gain depth LLR of a reportable gain (
gate = "dl")- classes
classes whose reportable gains need depth support
- nested
classes of the nested calls that can explain a chromosome gain
- promote
make the explaining nested call reportable
- gate
depth gate of a gain:
"dl"(gain depth LLR abovemin_dl_gain) or"z"(z above the midpoint and above thegate_qquantile of the row's depth null)- gate_q
null quantile of the
"z"gate (0.95: about 5 % of all null-depth rows pass; more among rows already called as gains and on female chrX, see Details)- tpar
"z"gate: the Student-t fits per class x stratum (fit_depth_null(), completed as incaller_normal()); NULL = the Gaussian depth null N(0, 1). A gated row whose class x stratum has no fit (a namedevent: no null rows) takes the fit of itssd_class(ascorescolumn) in that stratum; without one it is an error (match_depth_null()); a row with NA class or stratum has no depth support- params
caller_defaults()(shifts,sd_floor; the"z"gate)