Estimate Directional Contamination Against Matched Anchors — rduckhts_somalier_matched

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.

Value

A data frame if `table_name` is `NULL`; otherwise invisible `TRUE`.

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.