BIOM.utils (version 0.9)

BIOM Import: Attach formal type to BIOM data (import)

Description

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

Usage

biom(x, ...)
"biom"(x, ..., file=NULL, quiet=FALSE)
"biom"(x, type=biom_table_types, sparse=NULL, ..., quiet=FALSE)
"biom"(x, ..., quiet=FALSE)

Arguments

x
an object convertible to biom
type
the type of BIOM table to be constructed (string)
sparse
dims 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)

Value

An object of class biom, invisibly.

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 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().

References

BIOM format JSON

See Also

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

Examples

Run this code
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)

Run the code above in your browser using DataCamp Workspace