rduckhts_geno_sites: Fetch Exact Alleles at Requested Sites

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

Fetch Exact Alleles at Requested Sites

Description

Fetch full-site genotypes for requested (chromosome, position, REF, ALT) alleles from an indexed VCF/BCF. Positions become 0-based half-open intervals for one native indexed scan through 'read_geno(regions := ...)', then exact alleles are restored with an equality join. Everything runs on 'con': the request snapshot and the plan variable are session-local, are removed on exit even after an error, and no private connection is opened.

Usage

rduckhts_geno_sites(
  con,
  path,
  sites,
  source_build,
  table_name = NULL,
  samples = NULL,
  format_fields = NULL,
  index_path = NULL,
  decode_error_policy = "error",
  overwrite = FALSE
)

Arguments

con	A DuckDB connection with DuckHTS loaded
path	Path to the VCF/BCF file
sites	A relation name (character), a [DBI::Id()], or a [DBI::SQL()] query evaluated on 'con', with columns 'request_id' (unique, non-NULL), 'build', 'chrom', 'pos' (integer type, at least 1), 'ref' and 'alt' (one allele, non-empty, no comma). Extra columns are preserved; the names 'record_index', 'full_alt', 'alt_index', 'calls' and 'match_status' are reserved. Duplicate (chrom, pos, ref, alt) rows are separate requests.
source_build	Single string that every 'sites$build' must equal.
table_name	Optional table to create with the result (a regular table, replaced only when 'overwrite = TRUE'); its name is returned invisibly. 'NULL' returns a data frame.
samples, index_path, format_fields, decode_error_policy	See [rduckhts_geno()]. 'format_fields' such as 'c("GP", "DS", "HS")' are kept for the whole site without any allele remapping. The decode policy defaults to '"error"' here.
overwrite	Logical. If TRUE, overwrites existing table

Details

Coordinates in 'sites' are 1-based VCF positions. Requested alleles are compared verbatim: nothing is trimmed, left-aligned, strand-flipped, split or lifted over, and 'source_build' is only a caller-asserted label that every request must carry (contig names cannot prove assembly identity). The 'match_status' labels are position-level diagnostics, not claims about normalization equivalence.

The result holds every request column followed by:

'record_index'

Scan-local record ordinal (not a persistent locator).

'full_alt'

The record's complete 'ALT' list in file order.

'alt_index'

1-based ordinal of the matching ALT slot.

'calls'

The full-site 'calls' list of [rduckhts_geno()], including 'format_fields' members such as 'GP', 'DS' or 'HS'.

'match_status'

‘"matched"': chrom, pos, REF and ALT equal a record’s ALT slot (one row per matching record and ALT slot, so physical duplicate records and duplicated ALT slots each return a row). '"allele_not_at_site"': a record at chrom and pos has an equal REF but none of its ALTs equals 'alt'. '"ref_mismatch"': records exist at chrom and pos but none has an equal REF. '"absent"': no record starts at chrom and pos (an unknown contig is absent).

Unmatched requests have one row with 'NULL' record and call fields; no reference genotype is fabricated. Reference and missing calls at a matched site are returned because 'non_reference_only' is fixed to 'FALSE'. Rows carry no implicit order: use 'ORDER BY request_id, record_index, alt_index'.

Value

A data frame, or invisibly 'table_name' when it is given.

See Also

[rduckhts_geno()]

Examples

con <- rduckhts_connect()
path <- system.file("extdata", "geno_sites.bcf", package = "Rduckhts")
DBI::dbWriteTable(con, "requests", data.frame(
  request_id = 1:2, build = "GRCh38", chrom = "chr1", pos = c(100L, 100L),
  ref = "A", alt = c("G", "T")))
rduckhts_geno_sites(con, path, "requests", "GRCh38", format_fields = c("GP", "DS"))
DBI::dbDisconnect(con, shutdown = TRUE)

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