null cells: the features'
null_cellcolumn, orselect_null_cells()(null_cells = "auto"selects when the column is missing, all NA or all TRUE), nevermultiplets; 2. Student-t depth null per class x stratum and allelic rho on the null arm rows; 3.score_cells()with the normal state set; 4. fold-CV budget thresholds (budget_thresholds()); 5. per-cell calls bycall_policy(); 6. pools within cell type (make_pools()) and, with anembedding, kNN pools (knn_pools()), pooled null thresholds (pooled_thresholds()) and pooled calls; 7. events (consolidate_calls()). Rows witheligible = FALSEare dropped first.
Usage
caller_normal(
feat,
params = caller_defaults(),
cell_meta = NULL,
multiplets = NULL,
regions = NULL,
embedding = NULL,
null_cells = c("auto", "features", "select"),
depth_model = c("t", "gauss"),
n_draws = 20000,
pool_classes = c("chrom", "arm", "50Mb", "20Mb", "10Mb", "5Mb", "event"),
select_args = list(),
sex = NULL,
resolve_gains = TRUE,
gain_min_dl = 0,
gain_gate = "dl",
gain_gate_q = 0.95,
pool_loo = TRUE,
pool_standardize = TRUE,
null_chroms = paste0("chr", 1:22)
)Arguments
- feat
features long table (
vignette("scphasedcn-outputs", package = "scphasedcn"))- params
- cell_meta
optional table
cell(+cell_type) overriding the features' cell types- multiplets
cells flagged as multiplets (never null cells, never pooled)
- regions
regions table (default
regions_from_features())- embedding
optional chromatin embedding (cells x components, row names = cells) for kNN pools
- null_cells
"auto", "features" or "select"
- depth_model
"t" or "gauss"
- n_draws
null pool-regions per class for the pooled thresholds
- pool_classes
region classes that are pooled
- select_args
extra arguments for
select_null_cells()- sex
"female", "male" (case-insensitive, or "F" / "M"; any other value stops) or NULL (inferred: female when chrX rows carry allele votes); sets the chrX rule of
call_policy()- resolve_gains
apply
resolve_nested()to the per-cell calls- gain_min_dl
min_dl_gainofresolve_nested()(gain_gate = "dl")- gain_gate
depth gate of the per-cell gains,
gateofresolve_nested():"dl"(default: gain depth LLR abovegain_min_dl, i.e. z above the midpoint of neutral and the gain shift) or"z"(opt-in: z also above thegain_gate_qquantile of the depth null of the row's class x stratum. About1 - gain_gate_qof all null-depth rows pass; among rows already called as gains with weak allelic support, and on female chrX, up to about two to three times that in simulation. Not benchmarked on real data as a default)- gain_gate_q
null quantile of the
"z"gain gate (0.95)- pool_loo
call pools on the leave-one-out robust score
s_rob(pool_scores())- pool_standardize
standardise the pooled best LLR per region (
pool_scale()of the null pools of the same construction) before the per-class pooled thresholds- null_chroms
chromosomes whose rows can be null rows (default the autosomes, the chromosomes
select_null_cells()checks); NULL = everynull_region
Value
scphasedcn (mode normal) with scores, thresholds (column level:
cell, pool_type, pool_knn), calls (cell and pool level; resolved for gains changed by
resolve_nested(); with gain_gate = "z" also its gate_z, gate_thr), events, pools, null_fit = list(tpar, rho, null_cells, selection, pool_scale, sex, vote_bins, rho_chrom) (vote_bins: the vote_bins() table with params$calib = "votes"; rho_chrom: the
rho_by_chrom() table with params$calib_rho = "chrom")
Details
Calibration policy (defaults): null cells are selected on autosomal rows
and null rows are autosomal (select_null_cells() chroms, null_chroms);
per-cell chromosome gains need depth support and lose to a stronger nested
loss / CN-LOH (resolve_nested(), resolve_gains; opt-in gain_gate = "z" gates on a null quantile of z
instead of the sign of the gain depth LLR); pooled state scores are
standardised per region by the median / MAD of the null pools of the same
construction (pool_scale(), pool_standardize), and a pooled call must
survive dropping its most influential cell (pool_loo: pools are called on
s_rob, thresholded on null pools of the same statistic); chrX pools are
not reportable in females (call_policy() sex).
Opt-in calibrations: params$calib = "votes" keys the per-cell thresholds on class x stratum x vote stratum
(hstratum, bins of n_hap of the null rows, vote_bins()); params$calib_rho = "chrom" scores the allele
channel with a per-chromosome rho shrunk to the global (rho_by_chrom()). params$pool_tail_q > 0 (the
default) adds a per-region tail factor to the pooled region scale (pool_scale()), cross-fitted with
params$pool_tail_xfit (pooled_thresholds()). Named event regions (no null rows) borrow the per-cell
thresholds of their sd_class (budget_thresholds()); their pools are called only with params$pool_events
(experimental, off by default: caller_defaults()). Removed options stop with
an error: calib "region" / "region_votes" / "votes_cont", calib_rho "cell" / "chrom_cell".