Creates a DuckDB table from a VCF or BCF file using the DuckHTS extension. This follows the RBCFTools pattern of creating a table that can be queried.
Usage
rduckhts_bcf(
con,
table_name,
path,
region = NULL,
index_path = NULL,
tidy_format = FALSE,
additional_csq_column_types = NULL,
scan_mode = NULL,
decompression_threads = 0,
decode_error_policy = "null",
overwrite = FALSE,
samples = NULL,
regions_var = NULL,
include_file_offset = FALSE,
duplicate_names = "error"
)Arguments
- con
A DuckDB connection with DuckHTS loaded
- table_name
Name for the created table
- path
Path to the VCF/BCF file
- region
Optional genomic region (e.g., "chr1:1000-2000")
- index_path
Optional explicit path to index file (.csi/.tbi)
- tidy_format
Logical. If TRUE, FORMAT columns are returned in tidy format
- additional_csq_column_types
Optional bcftools-style `PATTERN TYPE` overrides for CSQ/ANN/BCSQ subfield typing, separated by newlines or `;`
- scan_mode
Optional scan mode. Use
"auto"(default extension behavior) or"sequential"to force full-file streaming instead of index-backed count/parallel scan paths. Sequential mode is incompatible with `region`.- decompression_threads
Integer. Number of htslib decompression worker threads per file handle. Default `0`. Use `0` to keep BCF/VCF reads single-threaded.
- decode_error_policy
Character. VCF/BCF decode policy:
"null"returns NULL for header-vs-payload type clashes or oversized numeric scalars,"warn"emits a DuckHTS warning and returns NULL, and"error"raises a DuckDB/R error. Missing elements count toward scalar cardinality; vector-end padding does not. A malformed FORMAT tag is withheld for every selected sample on that record. Physical read errors and OOM always fail.- overwrite
Logical. If TRUE, overwrites existing table
- samples
Optional HTSlib sample selector: `NULL` or `"-"` keeps all, `""` keeps none, comma-separated names include samples, and a leading `"^"` excludes them. Unknown names error; selected samples retain header order.
- regions_var
Optional name of a session variable on `con` that holds typed intervals, `STRUCT(chrom VARCHAR, start BIGINT, "end" BIGINT)[]` with 0-based half-open coordinates (a VCF position `p` is `[p - 1, p)`). The name is quoted into `regions := getvariable('<name>')`; create the variable with `SET VARIABLE` on the same connection. A `NULL` variable value keeps the ordinary scan, an empty list selects no records, and `region` and `regions_var` are mutually exclusive. Typed regions need an index and are incompatible with `scan_mode = "sequential"`. Chromosome names are literal (not region expressions); overlapping and adjacent intervals are merged natively. Limits: 1,000,000 intervals and 128 MiB. Aggregate with `coalesce(list(...), []::STRUCT(...)[])`: `list()` over no rows is `NULL`, which means the ordinary full scan.
- include_file_offset
Logical. If `TRUE`, add a `FILE_OFFSET` column after `FILTER`: the BGZF virtual position just after each record. It increases strictly in file order and is the same for every scan mode, so ordering by it restores file order, also among records at one position. Input that is not BGZF-compressed gives `NA`. The default keeps the existing schema.
- duplicate_names
`"error"` (default) or `"suffix"`. VCF keys and sample IDs may differ only in case, while DuckDB column names ignore case; `"suffix"` keeps the first name in header order and renames later ones `name__2`, `name__3`.
Examples
library(DBI)
library(duckdb)
con <- rduckhts_connect()
bcf_path <- system.file("extdata", "vcf_file.bcf", package = "Rduckhts")
rduckhts_bcf(con, "variants", bcf_path, overwrite = TRUE)
dbGetQuery(con, "SELECT * FROM variants LIMIT 2")
#> CHROM POS ID REF ALT QUAL FILTER INFO_TEST INFO_DP4 INFO_AC INFO_AN
#> 1 1 3000150 <NA> C T 59.2 PASS NA NULL 2 4
#> 2 1 3000151 <NA> C T 59.2 PASS NA NULL 2 4
#> INFO_INDEL INFO_STR FORMAT_TT_A FORMAT_GT_A FORMAT_GQ_A FORMAT_DP_A
#> 1 FALSE <NA> NULL 0/1 245 NA
#> 2 FALSE <NA> NULL 0/1 245 32
#> FORMAT_GL_A FORMAT_TT_B FORMAT_GT_B FORMAT_GQ_B FORMAT_DP_B FORMAT_GL_B
#> 1 NULL NULL 0/1 245 NA NULL
#> 2 NULL NULL 0/1 245 32 NULL
dbDisconnect(con, shutdown = TRUE)