BIOMto: Attach formal type to BIOM data (import)
In BIOM.utils: Utilities for the BIOM (Biological Observation Matrix) Format

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Construct an object of class biom from given data, supplementing missing fields as necessary.

biom(x, ...)

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

## S3 method for class 'matrix'
biom(x, type=biom_table_types, sparse=NULL, ..., quiet=FALSE)

## S3 method for class 'list'
biom(x, ..., quiet=FALSE)

`x`	an object convertible to `biom`
`type`	the type of BIOM table to be constructed (string)
`sparse`	`dim`s or `dimnames` when sparse (`integer` or `list`, length-two)
`...`	arguments to `fromJSON()`
`file`	file containing JSON text for BIOM data (string)
`quiet`	print messages and warnings? (`logical`)

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 of a basic R type into class biom.

The character method is suitable for importing BIOM data properly speaking, that is, JSON text conforming to the BIOM specification. The data is read from file, when provided. Arguments from ... are passed to fromJSON() in order to allow for different character encodings,

To make a biom object from a TSV or CSV file, see examples below. Of course, it is possible to bring biom objects in and out of the session with save() and load().

The matrix method accepts an ordinary ("dense") matrix or a three-column sparse matrix representation (using indices starting at zero, per BIOM). If the latter, sparse should also be provided, as a length-two integer giving the data table's shape, or a length-two list giving its row and column ids. It may also be simply TRUE, in which case the smallest possible shape is assigned.

The list method accepts a list of components allowed or required by BIOM, inventing something reasonable for missing components, with certain qualifications:

shape is required if matrix_type is specified as "sparse"; data may be given as a list of rows, a list of triples sparsely representing a matrix, or a matrix; in the last case, its dimnames() may be used to provide row and column ids; but ids from rows and columns, if provided, supercede dimnames().

An object of class biom, invisibly.

A biom object reflects its matrix_element_type implicitly with the storage.mode() of its data. Accordingly, applying storage.mode<-() prior to biom() can be useful. See examples below.

Also, note that values seeming to be integers in R often are not.

Daniel T. Braithwaite

BIOM format
JSON

as.character.biom, as.matrix.biom, dim.biom, print.biom, storage.mode

tt <- tempfile()

##  two ways to the same result:
ff <- exampleBiomFile()
txt <- readLines (ff)
biom (txt)
biom (file=ff)

##  choose what fields to include with a list:
biom (list (data=smat, matrix_type="sparse", shape=c(266,4),
	matrix_element_type="unicode", comment="no comment"), quiet=TRUE)

xx <- matrix2list (cbind (LETTERS[1:20], paste ("some metadata for row", 1:20)))
xx <- lapply (xx, "names<-", c("id", "metadata"))
biom (list (data=dmat, type="Gene table", rows=xx, id="1234567890"), quiet=TRUE)

##  the same result in two ways, again:
write.table (dmat, file=tt, sep=",")
biom (dmat, "Function table")
biom (as.matrix (read.table (file=tt, sep=",")), "Func")

##  all the same:
biom (smat, sparse=TRUE, quiet=TRUE)
biom (smat, sparse=c(266,4), quiet=TRUE)
biom (smat, sparse=list (paste ("row", 1:266), paste ("column", 1:4)), quiet=TRUE)

##  enforce matrix_element_type to be "int":
mm <- dmat
storage.mode (mm) <- "integer"
biom (mm, quiet=TRUE)

unlink (tt)