Convert BIOM data from formal to basic type (export)

Description

Convert an object of class biom into a basic type: matrix, list, or character.

Usage

## S3 method for class 'biom'
as.matrix(x, expand=NULL, ...)

## S3 method for class 'biom'
as.list(x, ...)

## S3 method for class 'biom'
as.character(x, ..., file=NULL)

Arguments

Details

BIOM (Biological Observation Matrix) is a simple prescription for storing an annotated table of data. It may be described as a format, standard, or data structure.

The JSON (JavaScript Object Notation) standard for expressing general data objects as text is employed to define BIOM. Therefore the native form of BIOM data is structured text, conforming to the JSON specification in general and the BIOM specification in particular. Familiarity with BIOM is assumed here.

The S3 class biom and its methods facilitate analyses by expressing BIOM data as objects in the R environment. Each function above transforms an object that is already of class biom into a basic R type.

as.matrix() returns the BIOM data table as a matrix. If the object is "dense", then dimnames() of the result are equal to the BIOM row and column ids. Otherwise, the three-column sparse representation matrix is returned, with ids given by attached attributes "rownames" and "colnames".

However, using expand=TRUE expands a sparse representation. (Setting expand=FALSE has no effect when the object is "dense".) Also, see below for an example using class "sparseMatrix" from the R package Matrix.

as.character() returns BIOM properly speaking, that is, data and annotations written in JSON text conforming to the BIOM specification. That text is written to file, if provided.

See below for an example of saving the data table, only, in CSV or TSV format. Of course, it is possible to bring biom objects in and out of the session with save() and load().

as.list() returns a list corresponding closely element-by-element to BIOM. The differences are: list element data is a matrix not list; elements rows and columns hold metadata only, and so do not include ids; instead, additional elements row.ids and column.ids are present; and format_url is missing.

Value

For as.matrix() and as.list(), as described.

For as.character(), a single string of JSON text, or simply file if it is not NULL.

Except that last case, these functions return invisibly.

Author(s)

Daniel T. Braithwaite

References

BIOM format
JSON

See Also

biom

Examples

tt <- tempfile()
xx <- biom (li3)
yy <- biom (smat, sparse=TRUE, quiet=TRUE)

##  extract objects of basic types:
print (as.matrix (xx))
head (as.matrix (yy, expand=TRUE))
as.character (xx)
as.character (xx, file=tt)
str (as.list (xx))

##  export to a CSV file:
write.table (as.matrix (xx), file=tt, sep=",")

## Not run: 
##  a classed sparse matrix (for computation or what have you):
zz <- as.matrix (yy)
zz[,1:2] <- 1 + zz[,1:2]
Matrix::sparseMatrix (i=zz[,1], j=zz[,2], x=zz[,3])

## End(Not run)

unlink(tt)