genomicmatrix: Transform a Matrix to a Compressed Matrix

Description

Coerce to or create a compressed genomic matrix

Usage

genomicmatrix(snps, individuals, file.type,
              coding, header, IndividualsPerColumn,
	      DoubledIndividuals, leadingcolumns, loading,
              …)
# S3 method for genomicmatrix
as(object, …)

Arguments

object, snps

integer, matrix, vector, a haplomatrix or file name. See Details.

individuals

integer. See Details

file.type

if object is a filename then the precise coding of preceding headers, preceding columns, and the coding of the data can be very different. Instead of giving all the arguments coding, …, leadingcolumns, the file.type can be given:

‘beagle’: i.e.coding="AB? "
‘plink’: i.e. coding="AB? "
‘plink2’: i.e. coding="12? ",
‘plinkbinary’: i.e. coding="12345"

coding

if object is a filename then coding is a string of 4 or 5 characters.

In case of 5 characters, a file with genomic data is assumed and the characters have the following meaning:

1st: code for $0$
2nd: code for $1$
3rd: code for $2$
4th: code for $NA$
5th: the field separator character

In case of 4 characters, a file with haplotype information is assumed and the characters have the following meaning:

1st: code for $0$
2nd: code for $1$
3rd: code for $NA$
4th: the field separator character

The haplotype data is turned into genomic data.

header

integer. If object is a filename then header has the following meaning

positive header:: header gives the number of preceding lines in the file that will be ignored. An ASCII file is assumed in this case.
negative header:: a binary file is assumed and $-$header gives the number of preceding characters that will be jumped.

IndividualsPerColumn

Logical. If IndividualsPerColumn=TRUE then the first argument indicates a (SNPs $\times$ Individ) matrix. Otherwise, the first argument indicates a (Individ $\times$ SNPs) matrix, which will be transposed before storage.

DoubledIndividuals

Logical. If DoubledIndividuals=TRUE the haplotype information for the second chromosome is given in direction of the individuals, i.e. if additionally IndividualsPerColumn=TRUE, the number of columns are doubled. Otherwise, the information is given in the other direction. The information at one locus is always given back-to-back. If object is a filename, coding has 4 characters (i.e. it is a haplo file)

leadingcolumns

Integer. If object is a filename then leadingcolumns gives the number of first columns in the file that are ignored.

logical. If object is a filename then loading decides whether the file contents is read into RAM. Otherwise the file is read on the fly whenever possible. loading is TRUE for genomicmatrix and FALSE otherwise.

…

options, see RFoptions

Value

an object of class genomatrix

Details

genomicmatrix creates a compressed matrix according to the coding scheme given by RFoptions()$genetics$snpcoding.

In case snps is a string, i.e., a file name, the extension of the file name predefines the file.type:

‘.txt’: =‘beagle’
‘.bgl’: =‘beagle’
‘.phased’: =‘plink’
‘.tped’: =‘plink2’
‘.ped’: =‘plink2’
‘.bed’: =‘plinkbinary’

The definition can be overwritten by file.type. The latter can be overwritten by all other options (except individuals).

If individuals is given, genomicmatrix creates a snps $\times$ individuals compressed data matrix filled with zeros. The matrix can be modified afterwards by fillGeno.

If a haplomatrix is given, it is transformed into a genomicmatrix.

If genomicmatrix is given, the matrix is returned as is and a warning is given.

Both functions, genomicmatrix and as have exactly the same behavior execept for loading which is TRUE for genomicmatrix by default and fixed to be FALSE for as.genomicmatrix.

Examples

Run this code

# NOT RUN {
 
# }
# NOT RUN {
<!-- %    library(miraculix) -->
# }
# NOT RUN {
set.seed(0)  
snps <- 100
indiv <- 10
M <- matrix(sample(0:2, snps * indiv, replace=TRUE), nrow = snps)
(GM <- genomicmatrix(M))
stopifnot(all(as.matrix(GM) == M))


## There is a difference between genomicmatrix and as.genomicmatrix
## in case of files: 'as.genomicmatrix' creates only a pointer to
## the file, while 'genomicmatrix' reads the file
file <- "miraculix"
if (interactive() && !file.exists(paste0(file, ".bgl"))) {
  f <- rhaplo(indiv=100, loci=1000, file=file, file.type="beagle")
  print(f)
  print(G <- as.genomicmatrix(f))
  print(g <- genomicmatrix(f))
  Print(object.size(G), object.size(g)) ## g needs much more memory
  file.remove(f)
}

# }