Skip to contents

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 cell and optional qc_pass, cell_type, flat, fold, group, stratum, n_frag (passed to cell_features(): without cells only its cells that pass cell_qc() are called, and with a qc_pass column only those that also have qc_pass TRUE; flat becomes 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, multiplets and named groups lose 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 sex column of cells_qc.tsv if 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, see region_set()); scored as event regions; in tumour mode their chromosomes are excluded from the null rows

null_cells

NULL / "auto" (the features' null_cell when informative, else selected), "features", "select" (select_null_cells()), or the null cells themselves (vector or file). Tumour mode: given null cells (like flat cells of cell_meta) are the cells whose null rows fit the input depth t null and allelic rho when the features carry no null_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 to caller_tumour(), which sets aside the cells above its multiplet_prob option (default 0.9). The multiplet column 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 optional normal / tumour blocks (caller_params()) are the default arguments of caller_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 also cells, groups, cell_meta; in normal mode cell_meta columns other than cell_type) are then not used, with a warning

embedding

TRUE (compute scn_embedding() from dir; 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 as null_check and written as null_selection_check.tsv

caller_args

extra arguments for caller_normal() / caller_tumour() (e.g. n_draws, opts); they take precedence over params$normal / params$tumour (tumour: opts merged key by key)

phasing

phasing / block orientation of the allele features (cell_features(): "auto", "chromosome", "block", "loo" or "mirrored"; both modes; ignored with precomputed features). Normal mode with loo on 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). chromosome on 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)