rduckhts_somalier_matched_contamination: Estimate Directional Contamination Against Matched Anchors
In Rduckhts: 'DuckDB' High Throughput Sequencing File Formats Reader Extension

rduckhts_somalier_matched_contamination

R Documentation

Estimate Directional Contamination Against Matched Anchors

Description

Estimate one contamination fraction for each explicitly ordered receiver/anchor pair. The pair relation must contain distinct nonempty 'receiver_id' and 'anchor_id' columns. Every listed sample must have one count tuple for every ordered panel site. Both samples and population-B frequencies use the panel's A/B orientation; the anchor supplies the expected uncontaminated receiver genotype and is not interpreted as the contaminating donor. Reversing a pair is therefore a different analysis.

Usage

rduckhts_somalier_matched_contamination(
  con,
  evidence_table = NULL,
  evidence_parquet = NULL,
  panel_table = NULL,
  panel_parquet = NULL,
  frequency_table = NULL,
  frequency_parquet = NULL,
  pairs_table = NULL,
  pairs_parquet = NULL,
  table_name = NULL,
  min_depth = 15,
  max_depth = 1e+06,
  hom_minor_rate = 0.05,
  hom_tail_alpha = 0.001,
  error_rate = 0.002,
  min_probability = 1e-10,
  min_prior_frequency = 1e-06,
  alpha_min = 0,
  alpha_max = 1,
  grid_step = 0.01,
  refine_tolerance = 1e-10,
  max_evaluations = 4096,
  max_threshold_work = 1.6e+07,
  max_sites = 1e+06,
  overwrite = FALSE
)

Arguments

`con`	A DuckDB connection with DuckHTS loaded.
`evidence_table`	Name of an ordinary evidence table or view.
`evidence_parquet`	Path to an evidence Parquet file, instead of 'evidence_table'.
`panel_table`	Name of the required ordered panel table or view. Panel assembly and region values are each limited to 1,024 bytes.
`panel_parquet`	Path to the required ordered panel Parquet file, instead of 'panel_table'.
`frequency_table`	Name of the required population-frequency table or view.
`frequency_parquet`	Path to the required population-frequency Parquet file, instead of 'frequency_table'.
`pairs_table`	Name of an ordinary ordered-pair table or view.
`pairs_parquet`	Path to an ordered-pair Parquet file, instead of 'pairs_table'.
`table_name`	Optional output table. 'NULL' returns a data frame.
`min_depth`	Minimum measured receiver A+B depth for matched-contamination eligibility.
`max_depth`	Maximum supported A+B depth for the binomial eligibility test, at most 1,000,000.
`hom_minor_rate`	Expected minor-read rate used to recognize homozygous-like anchors.
`hom_tail_alpha`	Binomial upper-tail threshold for homozygous-like eligibility.
`error_rate`	Count error probability used by the fitted likelihood.
`min_probability`	Positive probability floor used in logarithms.
`min_prior_frequency`	Lower population-frequency clamp.
`alpha_min`, `alpha_max`	Closed contamination search range, satisfying '0 <= alpha_min < alpha_max <= 1'.
`grid_step`	Positive initial grid spacing, at most one.
`refine_tolerance`	Positive local-refinement tolerance.
`max_evaluations`	Positive bound on likelihood evaluations.
`max_threshold_work`	Positive cumulative limit on exact binomial certification steps, at most 100,000,000. Distinct observed depths are certified once per call and shared across samples.
`max_sites`	Positive per-sample panel capacity, at most 100,000,000.
`overwrite`	Whether an existing output table may be replaced.

Details

Sample identifiers and assembly strings are limited to 1,024 bytes, including when prepared profiles are persisted and supplied directly.

The returned score omits alpha-independent binomial coefficients. It compares alpha candidates for the same observed receiver/anchor pair and is not an absolute likelihood comparable between pairs. No usable evidence yields status 'no_evidence' with NULL alpha and relative log-likelihood.