write_bed: Write a genotype matrix into Plink BED format

Description

This function accepts a standard R matrix containing genotypes (values in c( 0, 1, 2, NA )) and writes it into a Plink-formatted BED (binary) file. Each genotype per locus (m loci) and individual (n total) counts the number of alternative alleles or NA for missing data. No *.fam or *.bim files are created by this basic function.

Usage

write_bed(file, X, verbose = TRUE, append = FALSE)

Value

Nothing

Arguments

file: Output file path. .bed extension may be omitted (will be added automatically if it is missing).
X: The m-by-n genotype matrix. Row and column names, if present, are ignored.
verbose: If TRUE (default), function reports the path of the file being written (after autocompleting the extension).
append: If TRUE, appends variants onto the file. (Default is FALSE).

Details

Genotypes with values outside of [0, 2] cause an error, in which case the partial output is deleted. However, beware that decimals get truncated internally, so values that truncate to 0, 1, or 2 will not raise errors. The BED format does not accept fractional dosages, so such data will not be written as expected.

Examples

Run this code

# to write an existing matrix `X` into file "data.bed", run like this:
# write_bed("data", X)
# this also works
# write_bed("data.bed", X)

# The following example is more detailed but also more awkward
# because (only for these examples) the package must create the file in a *temporary* location

file_out <- tempfile('delete-me-example', fileext = '.bed') # will also work without extension
# create 10 random genotypes
X <- rbinom(10, 2, 0.5)
# replace 3 random genotypes with missing values
X[sample(10, 3)] <- NA
# turn into 5x2 matrix
X <- matrix(X, nrow = 5, ncol = 2)
# write this data to file in BED format
# (only *.bed gets created, no *.fam or *.bim in this call)
write_bed(file_out, X)
# delete output when done
file.remove(file_out)