Skip to contents

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

Value

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

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`.

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"))
#>   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)