`ms_variants()` is the first link of the msuiter working grammar (`ms_variants() |> ms_tally() |> ...`). It is an S7 generic: given a file path it reads and validates VCF, TSV or MAF input (optionally gzip-compressed) at load time and returns an [MsVariants]; given a canonical data.frame it validates and constructs directly. All violations raise `msuiter_error_*` conditions.
Usage
ms_variants(
x,
genome,
caller,
matched_normal,
vaf_floor = NULL,
format = NULL,
chrom_col = NULL,
pos_col = NULL,
end_col = NULL,
ref_col = NULL,
alt_col = NULL,
filter_col = NULL,
vaf_col = NULL,
...
)Arguments
- x
A character string naming one variant file (`.vcf`, `.tsv` or `.maf`, optionally `.gz`; `.bcf` is rejected with an actionable message), or a data.frame in canonical form (columns `chrom`, `start`, `end`, `ref`, `alt`, plus optional `vaf` and `filter`).
- genome
Genome build label, e.g. `"GRCh38"`.
- caller
Variant caller label; required somaticness provenance.
- matched_normal
Matched normal sample id, or `"none"` for tumor-only calls; required somaticness provenance.
- vaf_floor
Optional single numeric in `[0, 1]`; somaticness VAF floor recorded in provenance.
- format
Force the input format: `"vcf"`, `"tsv"` or `"maf"`. Defaults to the file extension. `format = "bcf"` is an error.
- chrom_col, pos_col, end_col, ref_col, alt_col
Input column names for the canonical columns (file input only). Defaults per format: TSV `chrom/pos/ref/alt` plus an optional `end` column (when absent, `end` is derived as `pos + nchar(ref) - 1`); MAF standard names `Chromosome/Start_Position/Reference_Allele/Tumor_Seq_Allele2` with optional `End_Position`. Applies to TSV and MAF.
- filter_col
Optional name of a FILTER-like column passed through untouched into the canonical `filter` column (file input only).
- vaf_col
Optional name of a numeric VAF-like column passed through into the canonical `vaf` column (file input only).
- ...
No passthrough arguments: anything arriving in `...` is rejected as an argument-spelling error (`msuiter_error_input`).
Details
VCF parsing is minimally sufficient for filtered somatic caller output: the `##fileformat` line is kept as provenance, the `#CHROM` header names the columns, fixed columns `CHROM/POS/REF/ALT` are required and `FILTER` is passed through (`. ` kept verbatim). Multi-allelic ALT fields expand to one record per allele; symbolic (`<NON_REF>`), breakend, missing (`.`) and spanning (`*`) alleles are skipped into the provenance skip ledger. Sample genotype columns are not parsed in this unit. MAF rows whose `Variant_Classification` is not SBS-eligible are counted into the skip ledger, not routed – routing arrives with the catalog layer. The excluded set aligns with the SPMG default MAF filter: frame-shift/in-frame indels, structural variation, `Silent` and `Splice_Site`.
The returned `provenance` carries the somaticness signal fields plus `source` (path), `format`, the `##fileformat` note (VCF) and `parse` statistics (`n_lines`, `n_records`, `n_multiallelic_sites`, `n_skipped`, `skip_reasons`, `skip_classifications`).
Examples
lines <- c(
"##fileformat=VCFv4.2",
"#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO",
"chr7\t55191822\t.\tC\tT\t.\tPASS\t.",
"chr17\t7676594\t.\tCA\tC\t.\t.\t."
)
path <- tempfile(fileext = ".vcf")
writeLines(lines, path)
v <- ms_variants(path, "GRCh38",
caller = "synthetic", matched_normal = "none")
v
#> <MsVariants> 2 variants | genome: GRCh38
unlink(path)
# Canonical data.frame: validated direct construction
tab <- data.frame(chrom = "chr7", start = 55191822, end = 55191822,
ref = "C", alt = "T")
ms_variants(tab, "GRCh38", caller = "synthetic", matched_normal = "none")
#> <MsVariants> 1 variants | genome: GRCh38