% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/format5.R
\name{vcftobd}
\alias{vcftobd}
\title{Convert a VCF file to Format 5 binary dosage files}
\usage{
vcftobd(
  vcffile,
  bdose_file,
  region = NULL,
  snpidformat = 0L,
  bdoptions = character(0)
)
}
\arguments{
\item{vcffile}{Path to the bgzipped, tabix-indexed VCF file.}

\item{bdose_file}{Path for the output .bdose file. The companion .bdi
metadata file is written to \code{paste0(bdose_file, ".bdi")}.}

\item{region}{Optional genomic region string in bcftools format
(e.g. \code{"chr21"} or \code{"chr21:1-5000000"}).  Requires a
tabix index.  Default \code{NULL} processes the entire file.}

\item{snpidformat}{Integer controlling how SNP IDs are stored.
\describe{
\item{-1}{Generate IDs as \code{chr:pos:ref:alt}; equivalent to 2 for
Format 5.}
\item{0}{Use the IDs as they appear in the VCF file (default).
Auto-detects format 1 or 2 if all IDs match.}
\item{1}{Store IDs as \code{chr:pos}.  An error is raised if the VCF
already uses \code{chr:pos:ref:alt} format, as information would be
lost.}
\item{2}{Store IDs as \code{chr:pos:ref:alt}.}
\item{3}{Store IDs as \code{chr:pos_ref_alt}.}
}}

\item{bdoptions}{Character vector specifying which per-SNP statistics to
store.  Any combination of \code{"aaf"} (alternate allele frequency),
\code{"maf"} (minor allele frequency), and \code{"rsq"} (imputation
r-squared).  For each statistic, the corresponding VCF INFO field is used
when present for the first SNP (AF, MAF, R2 respectively); otherwise the
value is calculated from the dosage data.  Default \code{character(0)}
stores no statistics.}
}
\value{
NULL (invisibly)
}
\description{
Reads the DS (dosage) and GP (genotype probabilities) FORMAT fields from a
bgzipped, tabix-indexed VCF file — as produced by imputation servers such
as the Michigan Imputation Server — and writes a pair of Format 5
BinaryDosage files.
}
\details{
The .bdose file begins with a 4-byte magic number followed by one
gzip-compressed block per SNP.  Each block contains the DS values for all
samples followed by the GP values, encoded as unsigned 16-bit integers
(round(value * 10000); 0xffff = missing).

The .bdi file is an RDS-serialised R list of class \code{"genetic-info"}
with the following elements:
\describe{
\item{filename}{Path to the associated .bdose file.}
\item{usesfid}{Logical; always FALSE for VCF-sourced files.}
\item{samples}{data.frame with columns \code{fid} (empty) and
\code{sid} (sample IDs).}
\item{onechr}{Logical; TRUE if all SNPs are on a single chromosome.}
\item{snpidformat}{Numeric; resolved SNP ID format (see \code{snpidformat}
parameter).}
\item{snps}{data.frame with columns chromosome, location, snpid,
reference, alternate.}
\item{snpinfo}{Named list of per-SNP annotations requested via
\code{bdoptions}.  Each element is a numeric vector of length equal to
the number of SNPs.  Values are read from the VCF INFO column when
available for the first SNP (AF for aaf, MAF for maf, R2 for rsq);
otherwise they are calculated from the dosage values.}
\item{additionalinfo}{List of class \code{"bdose-info"} with format,
subformat, headersize, numgroups, and groups.}
\item{datasize}{Integer vector of length 0 (unused in Format 5).}
\item{indices}{Numeric vector of byte offsets into .bdose, one per SNP.}
}
}
