Normal tissue (mode = "normal"): cell_features() with celltype (cell-type matched) depth and the oriented allele
channel -> optional chromatin embedding (scn_embedding()) for kNN pools -> caller_normal() (null cells,
Student-t / beta-binomial nulls, fold-cross-validated budget thresholds, per-cell calls, pooled calls,
events). Tumour (mode = "tumour"): cell_features() with model depth, automatic phasing and the pseudobulk
groups groups, event chromosomes excluded from the null -> caller_tumour() (clones, clone
segments, cell assignment, per-cell inherited / confirmed calls).
Usage
call_scn(
dir,
mode = c("normal", "tumour"),
cell_meta = NULL,
cells = NULL,
sex = NULL,
events = NULL,
null_cells = NULL,
multiplets = NULL,
control_regions = NULL,
groups = NULL,
params = caller_defaults(),
features = NULL,
embedding = TRUE,
verbose = TRUE,
keep_scores = TRUE,
null_check = FALSE,
caller_args = list(),
phasing = "auto",
...
)Arguments
- dir
extraction directory (bins_100kb.h5ad, fragments.tsv.gz + .tbi, cells_qc.tsv)
- mode
"normal" or "tumour"
- cell_meta
NULL, a table or a TSV path with
celland optionalqc_pass, cell_type, flat, fold, group, stratum, n_frag(passed tocell_features(): withoutcellsonly its cells that passcell_qc()are called, and with aqc_passcolumn only those that also haveqc_passTRUE;flatbecomes the features'null_cell)- cells
NULL (QC-pass cells) or the cells to call (vector or file; no cell QC). The barcodes of
cells,cell_meta,null_cells,multipletsand namedgroupslose a trailing-1(as the extractor writes them); the run notes give how many of them match the data's cells, and a warning says when none does- sex
"female" / "male" (case-insensitive, or "F" / "M"; any other value stops; required for real data; NULL uses a
sexcolumn ofcells_qc.tsvif there is one, as in simulated data; its non-missing values must agree)- events
named events: a table
region, chrom, start, end(0-based half-open),cli_events()output or a named vector of region strings (20q_gain = "chr20:28000000-"; unnamed ones are named after the region, seeregion_set()); scored aseventregions; in tumour mode their chromosomes are excluded from the null rows- null_cells
NULL / "auto" (the features'
null_cellwhen informative, else selected), "features", "select" (select_null_cells()), or the null cells themselves (vector or file). Tumour mode: given null cells (likeflatcells ofcell_meta) are the cells whose null rows fit the input depth t null and allelic rho when the features carry nonull_fit; they are not the reference pool (the caller finds and cleans the normal clone itself); "select" is ignored with a warning- multiplets
NULL or multiplet flags (
multiplet_table()forms); normal mode: cells with prob > 0.5 are never null cells and never pooled; tumour mode: passed tocaller_tumour(), which sets aside the cells above itsmultiplet_proboption (default 0.9). Themultipletcolumn of the cells table flags the cells each mode set aside- control_regions
tumour mode: control regions for the null (regions table)
- groups
tumour mode: pseudobulk groups of the block orientation (a column of
cell_meta, a vector named by cell, or one label per cell); ignored with a warning in normal mode- params
caller_params()/caller_defaults(); its optionalnormal/tumourblocks (caller_params()) are the default arguments ofcaller_normal()/caller_tumour()(opts)- features
NULL (computed) or a precomputed
scn_features(object or .rds path) to skip the feature step; the arguments of the feature step (sex,events,...; in tumour mode alsocells,groups,cell_meta; in normal modecell_metacolumns other thancell_type) are then not used, with a warning- embedding
TRUE (compute
scn_embedding()fromdir; skipped with a warning when that fails), FALSE, or a cells x components matrix with cell row names- verbose
log progress (also of
caller_tumour())- keep_scores
keep the per cell x region scores in the result (normal mode; large)
- null_check
normal mode: also run the selection-free check of the per-cell null (
null_selection_check(); about doubles the scoring time), stored asnull_checkand written asnull_selection_check.tsv- caller_args
extra arguments for
caller_normal()/caller_tumour()(e.g.n_draws,opts); they take precedence overparams$normal/params$tumour(tumour:optsmerged key by key)- phasing
phasing / block orientation of the allele features (
cell_features(): "auto", "chromosome", "block", "loo" or "mirrored"; both modes; ignored with precomputedfeatures). Normal mode withlooon block phasing (read-backed blocks without a population phase) gives a warning and a run note: it aligns allelic bias shared by all cells (false per-cell events) and cannot show allelic events carried by few cells, so chromosome-scale phasing is recommended (scphasedcn hybrid-phase;vignette("scphasedcn-inputs")for its limits).chromosomeon block phasing (overall, or on a chromosome with votes) and, in normal mode,mirrored(a diagnostic orientation) also give a warning and a run note; so does tumour mode on chromosome-scale phasing (read-based blocks, oriented per clone, are preferable there)- ...
extra arguments for
cell_features()(e.g.centromeres,classes,qc)
Value
scphasedcn with features (the long table), feature_info (path, cells, phasing, phasing_chrom (the
per-chromosome phasing regimes, phasing_by_chrom()), notes), scores
(normal, keep_scores), thresholds, calls, events, pools, null_fit, false_calls (normal:
null_false_calls()), normal mode: p, q, null_borrowed on the per-cell calls and null_cell, p, q,
null_borrowed on the events (event_fdr(); q is descriptive: not a false discovery rate, not a filter),
expected_false (expected false calls / events per class x state, event_fdr()), null_check (null_selection_check(), with null_check = TRUE), embedding, clone
components (tumour), params (the caller parameters plus the
arguments used: normal = every caller_normal() argument of the run, tumour = the full tumour options) and
notes (run time, host, inputs, git revision)