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`.
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"))
#> request_id build chrom pos ref alt record_index full_alt alt_index
#> 1 1 GRCh38 chr1 100 A G 0 C, G 2
#> 2 1 GRCh38 chr1 100 A G 1 C, G 2
#> 3 2 GRCh38 chr1 100 A T NA NULL NA
#> calls
#> 1 0.00, 1.00, 2.00, 0.00, 1.00, 1.00, 2.00, NA, NA, 1.00, 1.00, 1.00, 1.00, 0.00, 0.00, NA, NA, NA, 0.10, 0.80, 0.05, 0.02, 0.02, 0.01, 0.01, 0.02, 0.03, 0.04, 0.90, 0.00, NA, 0.90, 0.06, 0.94, 1.00, NA
#> 2 0.00, 1.00, 2.00, 0.00, 1.00, 1.00, 2.00, NA, NA, 1.00, 1.00, 1.00, 1.00, 0.00, 0.00, NA, NA, NA, 0.10, 0.80, 0.05, 0.02, 0.02, 0.01, 0.01, 0.02, 0.03, 0.04, 0.90, 0.00, NA, 0.90, 0.06, 0.94, 1.00, NA
#> 3 NULL
#> match_status
#> 1 matched
#> 2 matched
#> 3 allele_not_at_site
DBI::dbDisconnect(con, shutdown = TRUE)