Convert a format 1 binary dosage file to Format 5

Description

Reads a format 1 binary dosage file (subformat 1 or 2) and converts it to a Format 5 file pair. If the source file does not contain genotype probabilities (subformat 1), those values are stored as missing in the output.

Usage

bd1tobd5(bdfiles, bdose_file)

Arguments

Value

NULL (invisibly)

Convert a format 2 binary dosage file to Format 5

Description

Reads a format 2 binary dosage file (subformat 1 or 2) and converts it to a Format 5 file pair. If the source file does not contain genotype probabilities (subformat 1), those values are stored as missing in the output.

Usage

bd2tobd5(bdfiles, bdose_file)

Arguments

Value

NULL (invisibly)

Convert a format 3 binary dosage file to Format 5

Description

Reads a format 3 binary dosage file (subformat 1, 2, 3, or 4) and converts it to a Format 5 file pair. If the source file does not contain genotype probabilities (subformats 1 and 3), those values are stored as missing in the output.

Usage

bd3tobd5(bdfiles, bdose_file)

Arguments

Value

NULL (invisibly)

Convert a format 4 binary dosage file to Format 5

Description

Reads a format 4 binary dosage file (subformat 1, 2, 3, or 4) and converts it to a Format 5 file pair. If the source file does not contain genotype probabilities (subformats 1 and 3), those values are stored as missing in the output.

Usage

bd4tobd5(bdfile, bdose_file)

Arguments

Value

NULL (invisibly)

Apply a function to each SNP in a binary dosage file

Description

A routine that reads in the SNP data serially from a binary dosage file and applies a user specified function to the data.

Usage

bdapply(bdinfo, func, ...)

Arguments

Value

A list with length equal to the number of SNPs in the binary dosage file. Each element of the list is the value returned by the user supplied function

See Also

Other Iterating functions: genapply(), vcfapply()

Examples

# Get information about a binary dosage file

vcf1abdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = vcf1abdfile)

# Apply the getaaf, get alternate allele frequency, function
# to all the SNPs in the binary dosage file

aaf <- bdapply(bdinfo = bdinfo,
               func = BinaryDosage:::getaaf)

Merge binary dosage files together

Description

Routine to merge binary dosage files together. The files don't have to be in the same format. They will be merged into a file with the format specified. Information about the SNPs, aaf, maf, avgcall, rsq, can be maintained for each file, or recalculated for the merged set.

Usage

bdmerge(
  mergefiles,
  format = 4,
  subformat = 0L,
  bdfiles,
  famfiles = character(),
  mapfiles = character(),
  onegroup = TRUE,
  bdoptions = character(),
  snpjoin = "inner"
)

Arguments

Value

None

Examples

bdvcf1afile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdvcf1bfile <- system.file("extdata", "vcf1b.bdose", package = "BinaryDosage")
mergefiles <- tempfile()

BinaryDosage:::bdmerge(mergefiles = mergefiles,
                       bdfiles = c(bdvcf1afile, bdvcf1bfile),
                       bdoptions = "maf")
bdinfo <- getbdinfo(mergefiles)

Close a persistent Format 5 connection

Description

Explicitly closes the connection opened by openbd5con. Calling this is optional — the finalizer will close it on garbage collection or R exit — but explicit close is preferred to release the file handle promptly.

Usage

closebd5con(bd5con)

Arguments

Value

NULL invisibly.

Apply a function to each SNP in a gen, impute2, file

Description

A routine that reads in the SNP data serially from a gen file and applies a user specified function to the data.

Usage

genapply(geninfo, func, ...)

Arguments

Value

A list with length equal to the number of SNPs in the vcf file. Each element of the list is the value returned by the user supplied function

See Also

Other Iterating functions: bdapply(), vcfapply()

Examples

# Get information about a gen, impute2, file

gen1afile <- system.file("extdata", "set1a.imp", package = "BinaryDosage")
geninfo <- getgeninfo(genfiles = gen1afile,
                      snpcolumns = c(1L, 3L, 2L, 4L, 5L),
                      header = TRUE)


aaf <- genapply(geninfo = geninfo,
                func = BinaryDosage:::getaaf)

Convert a gen file to a binary dosage file

Description

Routine to read information from a gen file and create a binary dosage file. Note: This routine can take a long time to run if the gen file is large.

Usage

gentobd(
  genfiles,
  snpcolumns = 1L:5L,
  startcolumn = 6L,
  impformat = 3L,
  chromosome = character(),
  header = c(FALSE, TRUE),
  gz = FALSE,
  sep = "\t",
  bdfiles,
  format = 4L,
  subformat = 0L,
  snpidformat = 0L,
  bdoptions = character(0)
)

Arguments

Value

None

Examples

# Find the gen file names
gen3afile <- system.file("extdata", "set3a.imp", package = "BinaryDosage")
gen3asample <- system.file("extdata", "set3a.sample", package = "BinaryDosage")
# Get temporary output file name
bdfiles <- tempfile()
# Convert the file
gentobd(genfiles = c(gen3afile, gen3asample),
        snpcolumns = c(0L, 2L:5L),
        bdfiles = bdfiles)
# Verify the file was written correctly
bdinfo <- getbdinfo(bdfiles = bdfiles)

Calculate alternate allele frequency

Description

Routine to calculate the alternate allele frequency given the dosages. Missing values for dosage ignored. This function is used internally and is exported for use in examples.

Usage

getaaf(dosage, p0, p1, p2)

Arguments

Value

Alternate allele frequency

Examples

# Get information about binary dosage file
bdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = bdfile)
snp1 <- getsnp(bdinfo = bdinfo, 1)
aaf <- getaaf(snp1$dosage)

Read a SNP from a Format 5 binary dosage file

Description

Seeks to the SNP's compressed block in the .bdose file, decompresses it, and returns the dosage and genotype probabilities for all samples.

Usage

getbd5snp(bd5info, snp)

Arguments

Value

A list with four numeric vectors, each of length n_samples:

dosage

DS values in [0, 2]; NA = missing.

p0

P(g=0) values in [0, 1]; NA = missing.

p1

P(g=1) values in [0, 1]; NA = missing.

p2

P(g=2) values in [0, 1]; NA = missing.

Read a Format 5 SNP into pre-allocated vectors (buffered variant)

Description

Like getbd5snp but writes results into caller-supplied vectors instead of allocating new ones. Intended for tight loops where thousands of SNPs are read sequentially; pre-allocating the output vectors once avoids repeated memory allocation.

Usage

getbd5snp_buf(bd5info, snp, dosage, p0, p1, p2)

Arguments

Details

The four output vectors must not have more than one R binding at the call site (no extra variables pointing to the same object); R's copy-on-modify semantics would otherwise prevent in-place update.

Value

NULL invisibly. dosage, p0, p1, and p2 are updated in place.

Read a Format 5 SNP using a persistent open connection

Description

Like getbd5snp_buf but reuses an already-open file connection instead of opening and closing it on every call. Use openbd5con before the loop and closebd5con (or let the finalizer handle it) after.

Usage

getbd5snp_con(bd5info, snp, dosage, p0, p1, p2, bd5con)

Arguments

Value

NULL invisibly. dosage, p0, p1, and p2 are updated in place.

Get information about a binary dosage file

Description

Routine to return information about a binary dosage file. This information is used by other routines to allow for quicker extraction of values from the file.

Usage

getbdinfo(bdfiles)

Arguments

Value

List with information about the binary dosage file. This includes family and subject IDs along with a list of the SNPs in the file. Other information needed to read the file is also included.

Examples

vcf1abdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = vcf1abdfile)

Get information about a gen, impute2, file

Description

Routine to return information about a gen file. This information is used by other routines to allow for quicker extraction of values from the file.

Usage

getgeninfo(
  genfiles,
  snpcolumns = 1L:5L,
  startcolumn = 6L,
  impformat = 3L,
  chromosome = character(),
  header = c(FALSE, TRUE),
  gz = FALSE,
  index = TRUE,
  snpidformat = 0L,
  sep = c("\t", "\t")
)

Arguments

Value

List with information about the gen file. This includes family and subject IDs along with a list of the SNPs in the file. Other information needed to read the file is also included.

Examples

# Get file names of th gen and sample file
gen3afile <- system.file("extdata", "set3a.imp", package = "BinaryDosage")
gen3ainfo <- system.file("extdata", "set3a.sample", package = "BinaryDosage")

# Get the information about the gen file
geninfo <- getgeninfo(genfiles = c(gen3afile, gen3ainfo),
                      snpcolumns = c(0L, 2L:5L))

Calculate minor allele frequency

Description

Routine to calculate the minor allele frequency given the dosages. Missing values for dosage ignored. This function is used internally and is exported for use in examples. Note: The minor allele in one data set may be different from another data set. This can make comparing minor allele frequencies between data sets nonsensical.

Usage

getmaf(dosage, p0, p1, p2)

Arguments

Value

Minor allele frequency

Examples

# Get information about binary dosage file
bdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = bdfile)
snp1 <- getsnp(bdinfo = bdinfo, 1)
maf <- getmaf(snp1$dosage)

Calculate imputation r squared

Description

Routine to calculate the imputation r squared given the dosages and Pr(g=2). This is an estimate for the imputation r squared returned from minimac and impute2. The r squared values are calculated slightly differently between the programs. This estimate is based on the method used by minimac. It does well for minor allele frequencies above 5%. This function is used internally and is exported for use in examples.

Usage

getrsq(dosage, p0, p1, p2)

Arguments

Value

Imputation r squared

Examples

# Get information about binary dosage file
bdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = bdfile)
snp1 <- getsnp(bdinfo = bdinfo, 1, dosageonly = FALSE)
rsq <- BinaryDosage:::getrsq(snp1$dosage, p2 = snp1$p2)

Read SNP data from a binary dosage file

Description

Routine to read the dosage and genetic probabilities about a SNP from a binary dosage file

Usage

getsnp(bdinfo, snp, dosageonly = TRUE)

Arguments

Value

A list with either the dosages or the dosages and the genetic probabilities.

Examples

# Get the information about the file
vcf1abdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo <- getbdinfo(bdfiles = vcf1abdfile)

# Read the first SNP
getsnp(bdinfo, 1, FALSE)

Get information about a vcf file

Description

Routine to return information about a vcf file. This information is used by other routines to allow for quicker extraction of values from the file.

Usage

getvcfinfo(vcffiles, gz = FALSE, index = TRUE, snpidformat = 0L)

Arguments

Value

List containing information about the VCF file to include file name, subject IDs, and information about the SNPs. Indices for faster reading will be included if index is set to TRUE

Examples

# Get file names of th vcf and infromation file
vcf1afile <- system.file("extdata", "set1a.vcf", package = "BinaryDosage")
vcf1ainfo <- system.file("extdata", "set1a.info", package = "BinaryDosage")

# Get the information about the vcf file
vcf1ainfo <- getvcfinfo(vcffiles = c(vcf1afile, vcf1ainfo))

Merge Format 5 binary dosage files

Description

Merges two or more Format 5 binary dosage files into a single Format 5 output file. The merge type is determined automatically:

Usage

mergebd(bdose_files, bdose_file)

Arguments

Details

• If subject IDs do not overlap across files, a subject merge is performed: the output contains all subjects from every file and the SNPs common to all files.

• If SNP IDs do not overlap across files, a SNP merge is performed: the output contains all SNPs from every file and the subjects common to all files.

If both subject IDs and SNP IDs overlap across files the merge cannot be performed and an error is returned.

SNPs are identified by chromosome, position, reference allele, and alternate allele.

Value

NULL (invisibly)

Examples

bdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo_src <- getbdinfo(bdfile)

# Create two format 5 files with non-overlapping subjects
bdose_a   <- tempfile(fileext = ".bdose")
bdose_b   <- tempfile(fileext = ".bdose")
bdose_tmp <- tempfile(fileext = ".bdose")
updatebd(bdfiles = bdfile, bdose_file = bdose_tmp)
subsetbd(bdfiles    = bdose_tmp,
         bdose_file = bdose_a,
         subjectids = bdinfo_src$samples$sid[1:30])
subsetbd(bdfiles    = bdose_tmp,
         bdose_file = bdose_b,
         subjectids = bdinfo_src$samples$sid[31:60])

bdose_out <- tempfile(fileext = ".bdose")
mergebd(bdose_files = c(bdose_a, bdose_b),
        bdose_file  = bdose_out)

Open a persistent connection to a Format 5 binary dosage file

Description

Opens the .bdose file for reading and returns an object that holds the connection open across multiple calls to getbd5snp_con. The connection is closed automatically when the object is garbage-collected or when R exits; call closebd5con to close it explicitly.

Usage

openbd5con(bd5info)

Arguments

Value

An object of class "bd5con" to be passed to getbd5snp_con and closebd5con.

Subset a binary dosage file

Description

Creates a new Format 5 binary dosage file containing a subset of the SNPs and/or subjects from an existing binary dosage file. The input file may be in any format (1-5). At least one filtering criterion must be supplied, and all supplied criteria must be met for a SNP or subject to be retained.

Usage

subsetbd(
  bdfiles,
  bdose_file,
  minmaf = NULL,
  locations = NULL,
  startloc = NULL,
  endloc = NULL,
  subjectids = NULL
)

Arguments

Value

NULL (invisibly)

Examples

bdfile <- system.file("extdata", "vcf1a.bdose", package = "BinaryDosage")
bdinfo     <- getbdinfo(bdfile)
bdose_file <- tempfile(fileext = ".bdose")
subsetbd(bdfiles    = bdfile,
         bdose_file = bdose_file,
         subjectids = bdinfo$samples$sid[1:30])

Update a binary dosage file to Format 5

Description

Reads a binary dosage file in format 1, 2, 3, or 4, detects the format automatically, and converts it to a Format 5 file pair by calling the appropriate conversion routine. If the source file does not contain genotype probabilities, those values are stored as missing in the output.

Usage

updatebd(bdfiles, bdose_file)

Arguments

Value

NULL (invisibly)

Examples

vcf1afile <- system.file("extdata", "set1a.vcf", package = "BinaryDosage")
bdfile <- tempfile()
suppressWarnings(
  vcftobdlegacy(vcffiles = vcf1afile,
                bdfiles = bdfile,
                format = 4L)
)
bdose_file <- tempfile(fileext = ".bdose")
updatebd(bdfiles    = bdfile,
         bdose_file = bdose_file)

Apply a function to each SNP in a vcf file

Description

A routine that reads in the SNP data serially from a vcf file and applies a user specified function to the data.

Usage

vcfapply(vcfinfo, func, ...)

Arguments

Value

A list with length equal to the number of SNPs in the vcf file. Each element of the list is the value returned by the user supplied function

See Also

Other Iterating functions: bdapply(), genapply()

Examples

# Get information about a vcf file

vcf1afile <- system.file("extdata", "set1a.vcf", package = "BinaryDosage")
vcfinfo <- getvcfinfo(vcffiles = vcf1afile)

# Apply the getaaf, get alternate allele frequency, function
# to all the SNPs in the vcf file

aaf <- vcfapply(vcfinfo = vcfinfo,
                func = BinaryDosage:::getaaf)

Convert a VCF file to Format 5 binary dosage files

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.

Usage

vcftobd(
  vcffile,
  bdose_file,
  region = NULL,
  snpidformat = 0L,
  bdoptions = character(0)
)

Arguments

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 "genetic-info" with the following elements:

filename

Path to the associated .bdose file.

usesfid

Logical; always FALSE for VCF-sourced files.

samples

data.frame with columns fid (empty) and sid (sample IDs).

onechr

Logical; TRUE if all SNPs are on a single chromosome.

snpidformat

Numeric; resolved SNP ID format (see snpidformat parameter).

snps

data.frame with columns chromosome, location, snpid, reference, alternate.

snpinfo

Named list of per-SNP annotations requested via 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.

additionalinfo

List of class "bdose-info" with format, subformat, headersize, numgroups, and groups.

datasize

Integer vector of length 0 (unused in Format 5).

indices

Numeric vector of byte offsets into .bdose, one per SNP.

Value

NULL (invisibly)

Convert a VCF file to a binary dosage file

Description

Routine to read information from a VCF file and create a binary dosage file. The function is designed to use files return from the Michigan Imputation Server but will run on other VCF files if they contain dosage and genetic probabilities. Note: This routine can take a long time to run if the VCF file is large.

Usage

vcftobdlegacy(
  vcffiles,
  gz = FALSE,
  bdfiles,
  format = 4L,
  subformat = 0L,
  snpidformat = 0,
  bdoptions = character(0)
)

Arguments

Value

None

Examples

# Find the vcf file names
vcf1afile <- system.file("extdata", "set1a.vcf", package = "BinaryDosage")
vcf1ainfo <- system.file("extdata", "set1a.info", package = "BinaryDosage")
bdfiles <- tempfile()
# Convert the file
vcftobdlegacy(vcffiles = c(vcf1afile, vcf1ainfo), bdfiles = bdfiles)
# Verify the file was written correctly
bdinfo <- getbdinfo(bdfiles)