Skip to contents

Import a phased biallelic VCF reference panel

Source: R/vcf_public.R
gsim_import_vcf.Rd

Imports a plain, gzip, or BGZF VCF directly into chromosome-wise packed HAP v1 storage with aligned BIM and FAM metadata. The supported VCF subset is deliberately bounded: retained selected-sample calls are diploid, complete, phased 0|0, 0|1, 1|0, or 1|1, and retained variants are biallelic uppercase A/C/G/T SNPs. GT may occur anywhere in FORMAT. Unsupported biological records are counted and either skipped or rejected; malformed VCF is always rejected. Nothing is phased, imputed, normalized, flipped, split, or modified.

Usage

gsim_import_vcf(
  vcf,
  map,
  output,
  sample_metadata = NULL,
  samples = NULL,
  chromosome = NULL,
  region = NULL,
  unsupported = c("skip", "error"),
  overwrite = FALSE
)

Arguments

vcf

Path to a plain .vcf, gzip VCF, or BGZF VCF. Compression is detected from file bytes rather than the name. BCF is unsupported.

map

A data frame containing chromosome, genetic_position_cm, and exactly one alignment key. variant_id requests exact per-variant alignment. base_pair_position supplies at least two strictly increasing sparse knots per imported chromosome; cumulative cM is copied at knots and linearly interpolated between them without extrapolation.

output

Extension-free output prefix for .hap, .bim, and .fam.

sample_metadata

Optional data frame keyed by exact individual_id. It may supply family_id and sex codes 0/1/2. Parent IDs must be 0. The defaults are FID reference, unknown sex, and missing phenotype.

samples

NULL for all VCF samples, or unique exact sample IDs in the desired HAP/FAM order. Unselected sample genotype fields are not decoded.

chromosome

NULL or one exact chromosome label.

region

NULL or inclusive positive base-pair bounds c(start, end). A region requires chromosome; the compressed stream is scanned rather than accessed through a tabix index.

unsupported

Either "skip" to count and omit ordinary unsupported biological records or "error" to stop at the first one.

overwrite

Whether to replace an existing complete triplet.

Value

A lightweight gsim_reference descriptor. Biological alleles remain in packed files and are not returned as matrices.

Details

VCF REF is stored as bit 0 and BIM A2; VCF ALT is bit 1 and BIM A1. The left and right phased GT alleles become H1 and H2. Memory is bounded by one chromosome's two one-bit planes, one logical VCF line, a fixed 64 KiB decompression buffer, and a two-byte-per-selected-sample allele buffer. Sparse interpolation evaluates cm_left + (cm_right - cm_left) * (bp - bp_left) / (bp_right - bp_left) in that order using R double arithmetic. Exact knot positions copy the supplied value. Duplicate knots and repeated chromosome blocks are errors.