rduckhts_somalier_sex: Infer X/Y Dosage Sex Evidence

In Rduckhts: 'DuckDB' High Throughput Sequencing File Formats Reader Extension

Infer X/Y Dosage Sex Evidence

Description

Report, per sample, the X and Y depth relative to autosomal depth, the heterozygous and homozygous-alternate counts of usable X sites, and a call of '"XX"', '"XY"' or '"ambiguous"' following Somalier v0.3.4 ('relate.nim'). The counts relation comes from 'rduckhts_somalier_vcf_counts()' or 'rduckhts_somalier_bam_counts()' over a panel that includes X/Y sites (see 'rduckhts_somalier_import_sites()'); every selected sample needs one row for every panel site.

Usage

rduckhts_somalier_sex(
  con,
  counts_table = NULL,
  counts_parquet = NULL,
  panel_table = NULL,
  panel_parquet = NULL,
  table_name = NULL,
  sample_ids = NULL,
  min_depth = 7,
  min_sex_site_depth = 7,
  min_het_balance = 0.3,
  hom_balance_cutoff = 0.01,
  min_usable_x_sites = 11,
  xy_max_het_ratio = 0.05,
  xx_min_het_ratio = 0.4,
  y_signal_min = 0.4,
  y_gate = c("sample", "cohort"),
  overwrite = FALSE
)

Arguments

con	A DuckDB connection with DuckHTS loaded.
counts_table	Name of a count relation table or view.
counts_parquet	Path to a count relation Parquet file, instead of 'counts_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'.
table_name	Optional output table. 'NULL' returns a data frame.
sample_ids	Optional nonempty vector of distinct sample IDs to retain.
min_depth	Minimum A+B depth of an autosomal site in the normaliser.
min_sex_site_depth	Minimum A+B depth of a usable X or Y site.
min_het_balance	Lower B balance accepted as heterozygous.
hom_balance_cutoff	B balance below which a site is homozygous A.
min_usable_x_sites	Usable X sites required for an XX or XY call.
xy_max_het_ratio, xx_min_het_ratio	X het/hom-alt ratio limits for XY (below) and XX (above), with 'xy_max_het_ratio <= xx_min_het_ratio'.
y_signal_min	Y depth ratio above which the Y signal is present.
y_gate	Either '"sample"' or '"cohort"'.
overwrite	Whether an existing output table may be replaced.

Details

Depth ratios are '2 * mean A+B depth over usable sites / autosomal mean depth', with the autosomal mean taken over sites passing the relatedness allele-balance gate. The call is '"XY"' when at least 'min_usable_x_sites' X sites are usable and their het/hom-alt ratio is below 'xy_max_het_ratio', '"XX"' when it exceeds 'xx_min_het_ratio', and otherwise '"ambiguous"'; an XX dosage with a present Y signal is also '"ambiguous"'. Metrics are 'NA' without usable sites or autosomal depth, with a 'status' naming why. The call is evidence for review, not a diagnosis or determination of sex.

Somalier applies its Y check only when the cohort has Y depth, which makes a sample's call depend on the rest of the batch. 'y_gate = "sample"' (the default) applies it whenever the sample has a Y signal; '"cohort"' reproduces Somalier's gate, computed among the selected samples, and 'cohort_has_y' reports it.

Value

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

Rduckhts documentation built on Oct. 25, 2026, 1:08 a.m.