[med-svn] [r-bioc-biomformat] 06/08: New upstream version 1.2.0
Andreas Tille
tille at debian.org
Sun Sep 24 07:03:37 UTC 2017
This is an automated email from the git hooks/post-receive script.
tille pushed a commit to branch master
in repository r-bioc-biomformat.
commit 8194683c64e9efe4e4ce2e4e40b1f50cfec1b2f9
Author: Andreas Tille <tille at debian.org>
Date: Sun Sep 24 08:59:48 2017 +0200
New upstream version 1.2.0
---
DESCRIPTION | 25 +
NAMESPACE | 29 +
NEWS | 78 +++
R/BIOM-class.R | 829 ++++++++++++++++++++++++++
R/IO-methods.R | 184 ++++++
R/allClasses.R | 51 ++
R/allPackage.R | 19 +
R/validity-methods.R | 115 ++++
README.md | 43 ++
build/vignette.rds | Bin 0 -> 218 bytes
debian/README.test | 8 -
debian/changelog | 14 -
debian/compat | 1 -
debian/control | 33 -
debian/copyright | 29 -
debian/docs | 3 -
debian/patches/series | 1 -
debian/patches/use_debian_packaged_hdf5.patch | 23 -
debian/rules | 4 -
debian/source/format | 1 -
debian/tests/control | 3 -
debian/tests/run-unit-test | 13 -
debian/watch | 3 -
inst/doc/biomformat.R | 61 ++
inst/doc/biomformat.Rmd | 151 +++++
inst/doc/biomformat.html | 237 ++++++++
inst/extdata/min_dense_otu_table.biom | 32 +
inst/extdata/min_sparse_otu_table.biom | 43 ++
inst/extdata/min_sparse_otu_table_hdf5.biom | Bin 0 -> 33800 bytes
inst/extdata/rich_dense_char.biom | 56 ++
inst/extdata/rich_dense_otu_table.biom | 56 ++
inst/extdata/rich_sparse_char.biom | 66 ++
inst/extdata/rich_sparse_otu_table.biom | 66 ++
inst/extdata/rich_sparse_otu_table_hdf5.biom | Bin 0 -> 46952 bytes
man/biom-class.Rd | 51 ++
man/biom-methods.Rd | 73 +++
man/biom-package.Rd | 21 +
man/biom_data-methods.Rd | 87 +++
man/biom_shape-methods.Rd | 35 ++
man/colnames-methods.Rd | 35 ++
man/header-methods.Rd | 29 +
man/make_biom.Rd | 103 ++++
man/matrix_element_type-methods.Rd | 35 ++
man/ncol-methods.Rd | 35 ++
man/nrow-methods.Rd | 35 ++
man/observation_metadata-methods.Rd | 70 +++
man/read_biom.Rd | 67 +++
man/read_hdf5_biom.Rd | 46 ++
man/rownames-methods.Rd | 35 ++
man/sample_metadata-methods.Rd | 68 +++
man/show-methods.Rd | 26 +
man/write_biom.Rd | 48 ++
tests/testthat-biomformat.R | 12 +
tests/testthat/test-IO.R | 71 +++
tests/testthat/test-accessors.R | 191 ++++++
vignettes/biomformat.Rmd | 151 +++++
56 files changed, 3465 insertions(+), 136 deletions(-)
diff --git a/DESCRIPTION b/DESCRIPTION
new file mode 100644
index 0000000..92f0b53
--- /dev/null
+++ b/DESCRIPTION
@@ -0,0 +1,25 @@
+Package: biomformat
+Version: 1.2.0
+Date: 2016-04-16
+Maintainer: Paul J. McMurdie <mcmurdie at stanford.edu>
+License: GPL-2
+Title: An interface package for the BIOM file format
+Type: Package
+Author: Paul J. McMurdie <mcmurdie at stanford.edu> and Joseph N Paulson <jpaulson at jimmy.harvard.edu>
+BugReports: https://github.com/joey711/biomformat/issues
+URL: https://github.com/joey711/biomformat/, http://biom-format.org/
+Description: This is an R package for interfacing with the BIOM format. This package includes basic tools for reading biom-format files, accessing and
+ subsetting data tables from a biom object (which is more complex than a single table), as well as limited support for writing a biom-object
+ back to a biom-format file. The design of this API is intended to match the python API and other tools included with the biom-format
+ project, but with a decidedly "R flavor" that should be familiar to R users. This includes S4 classes and methods, as well as extensions of
+ common core functions/methods.
+Imports: plyr (>= 1.8), jsonlite (>= 0.9.16), Matrix (>= 1.2), rhdf5
+Depends: R (>= 3.2), methods
+Suggests: testthat (>= 0.10), knitr (>= 1.10), BiocStyle (>= 1.6),
+ rmarkdown (>= 0.7)
+VignetteBuilder: knitr
+Collate: 'allClasses.R' 'allPackage.R' 'IO-methods.R' 'BIOM-class.R'
+ 'validity-methods.R'
+biocViews: DataImport, Metagenomics, Microbiome
+NeedsCompilation: no
+Packaged: 2016-10-18 00:07:59 UTC; biocbuild
diff --git a/NAMESPACE b/NAMESPACE
new file mode 100644
index 0000000..f1a7f9e
--- /dev/null
+++ b/NAMESPACE
@@ -0,0 +1,29 @@
+# Generated by roxygen2 (4.1.1): do not edit by hand
+
+export(biom)
+export(biom_data)
+export(biom_shape)
+export(header)
+export(make_biom)
+export(matrix_element_type)
+export(observation_metadata)
+export(read_biom)
+export(read_hdf5_biom)
+export(sample_metadata)
+export(write_biom)
+exportClasses(biom)
+exportMethods(colnames)
+exportMethods(ncol)
+exportMethods(nrow)
+exportMethods(rownames)
+exportMethods(show)
+import(Matrix)
+import(methods)
+importFrom(jsonlite,fromJSON)
+importFrom(jsonlite,toJSON)
+importFrom(plyr,alply)
+importFrom(plyr,d_ply)
+importFrom(plyr,laply)
+importFrom(plyr,ldply)
+importFrom(plyr,llply)
+importFrom(rhdf5,h5read)
diff --git a/NEWS b/NEWS
new file mode 100644
index 0000000..a9844f8
--- /dev/null
+++ b/NEWS
@@ -0,0 +1,78 @@
+CHANGES IN VERSION 0.3.13
+-------------------------
+
+USER-VISIBLE CHANGES
+
+ - Added make_biom function. Creates biom object from standard R data table(s).
+
+CHANGES IN VERSION 0.3.12
+-------------------------
+
+USER-VISIBLE CHANGES
+
+ - No user-visible changes. All future compatibility changes.
+
+BUG FIXES
+
+ - Unit test changes to work with upcoming R release and new testthat version.
+
+ - This solves Issue 4: https://github.com/joey711/biom/issues/4
+
+CHANGES IN VERSION 0.3.11
+-------------------------
+
+USER-VISIBLE CHANGES
+
+ - No user-visible changes. All future CRAN compatibility changes.
+
+BUG FIXES
+
+ - Clarified license and project in the README.md
+
+ - Added TODO.html, README.html, and TODO.md to .Rbuildignore (requested by CRAN)
+
+ - Moved `biom-demo.Rmd` to `vignettes/`
+
+ - Updated `inst/NEWS` (this) file to official format
+
+ - Removed pre-built vignette HTML so that it is re-built during package build.
+ This updates things like the build-date in the vignette, but also ensures that
+ the user sees in the vignette the results of code that just worked with their
+ copy of the package.
+
+CHANGES IN VERSION 0.3.10
+-------------------------
+
+USER-VISIBLE CHANGES
+
+ - These changes should not affect any package behavior.
+
+ - Some of the top-level documentation has been changed to reflect new development
+ location on GitHub.
+
+BUG FIXES
+
+ - Minor fixes for CRAN compatibility
+
+ - This addresses Issue 1: https://github.com/joey711/biom/issues/1
+
+CHANGES IN VERSION 0.3.9
+-------------------------
+
+SIGNIFICANT USER-VISIBLE CHANGES
+
+ - speed improvement for sparse matrices
+
+NEW FEATURES
+
+ - The `biom_data` parsing function now uses a vectorized (matrix-indexed)
+ assignment while parsing sparse matrices.
+
+ - Unofficial benchmarks estimate a few 100X speedup.
+
+CHANGES IN VERSION 0.3.8
+-------------------------
+
+SIGNIFICANT USER-VISIBLE CHANGES
+
+ - First release version released on CRAN
diff --git a/R/BIOM-class.R b/R/BIOM-class.R
new file mode 100644
index 0000000..c5480ea
--- /dev/null
+++ b/R/BIOM-class.R
@@ -0,0 +1,829 @@
+################################################################################
+#' Build and return an instance of the biom-class.
+#'
+#' This is for instantiating a biom object within R (\code{\link{biom-class}}),
+#' and assumes relevant data is already available in R.
+#' This is different than reading a biom file into R.
+#' If you are instead interested in importing a biom file into R,
+#' you should use the \code{\link{read_biom}} function.
+#' This function is made available (exported) so that
+#' advanced-users/developers
+#' can easily represent analogous data in this structure if needed.
+#' However, most users are expected to instead rely on the
+#' \code{\link{read_biom}} function for data import, followed by
+#' accessor functions that extract R-friendly
+#' subsets of the data stored in the biom-format derived list.
+#'
+#' \code{biom()} is a constructor method. This is the main method
+#' suggested for constructing an experiment-level (\code{\link{biom-class}})
+#' object from its component data.
+#'
+#' @param x (REQUIRED). A named list conforming to conventions arising from
+#' the \code{\link{fromJSON}} function reading a biom-format file with
+#' default settings. See \code{\link{read_biom}} for more details about
+#' data import and
+#' \code{\link{biom-class}} for more details about accessor functions
+#' that extract R-friendly
+#' subsets of the data and metadata stored in \code{x}.
+#'
+#' @return An instance of the \code{\link{biom-class}}.
+#'
+#' @seealso
+#'
+#' Function to create a biom object from R data,
+#' \code{\link{make_biom}}.
+#'
+#' Definition of the
+#' \code{\link{biom-class}}.
+#'
+#' The \code{\link{read_biom}} import function.
+#'
+#' Function to write a biom format file from a biom object,
+#' \code{\link{write_biom}}
+#'
+#' Accessor functions like \code{\link{header}}.
+#'
+#' @rdname biom-methods
+#' @export
+#' @examples #
+#' # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' x = read_biom(biom_file)
+#' show(x)
+#' print(x)
+#' header(x)
+#' biom_data(x)
+#' biom_shape(x)
+#' nrow(x)
+#' ncol(x)
+#' observation_metadata(x)
+#' sample_metadata(x)
+setGeneric("biom", function(x) standardGeneric("biom"))
+#' @rdname biom-methods
+setMethod("biom", c("list"), function(x){
+ # Some instantiation checks chould go here,
+ # or wrap them in validity methods.
+ # Depends on how strict the check should be.
+ biom = new("biom", x)
+ return(biom)
+})
+################################################################################
+#' Create a \code{\link{biom-class}}
+#' from \code{\link{matrix-class}}
+#' or \code{\link{data.frame}}.
+#'
+#' This function creates a valid instance of the \code{\link{biom-class}}
+#' from standard base-R objects like
+#' \code{\link{matrix-class}} or \code{\link{data.frame}}.
+#' This makes it possible to export any contingency table data
+#' represented in R to
+#' \href{http://biom-format.org/documentation/biom_format.html}{the biom-format},
+#' regardless of its source.
+#' The object returned by this function is appropriate for writing to
+#' a \code{.biom} file using the \code{\link{write_biom}} function.
+#' The sparse biom-format is not (yet) supported.
+#'
+#' The BIOM file format (canonically pronounced biome) is designed to be
+#' a general-use format for representing biological sample by observation
+#' contingency tables. BIOM is a recognized standard for the
+#' \href{http://www.earthmicrobiome.org/}{Earth Microbiome Project}
+#' and is a \href{http://gensc.org/}{Genomics Standards Consortium}
+#' candidate project. Please see
+#' \href{http://biom-format.org/}{the biom-format home page}
+#' for more details.
+#'
+#' @param data (Required).
+#' \code{\link{matrix-class}} or \code{\link{data.frame}}.
+#' A contingency table.
+#' Observations / features / OTUs / species are rows,
+#' samples / sites / libraries are columns.
+#'
+#' @param sample_metadata (Optional).
+#' A \code{\link{matrix-class}} or \code{\link{data.frame}}
+#' with the number of rows equal to the number of samples in \code{data}.
+#' Sample covariates associated with the count data.
+#' This should look like the table returned by
+#' \code{\link{sample_metadata}} on a valid instance
+#' of the \code{\link{biom-class}}.
+#'
+#' @param observation_metadata (Optional).
+#' A \code{\link{matrix-class}} or \code{\link{data.frame}}
+#' with the number of rows equal to the number of
+#' features / species / OTUs / genes in \code{data}.
+#' This should look like the table returned by
+#' \code{\link{observation_metadata}} on a valid instance
+#' of the \code{\link{biom-class}}.
+#'
+#' @param id (Optional). Character string. Identifier for the project.
+#'
+#' @param matrix_element_type (Optional). Character string. Either 'int' or 'float'
+#'
+#' @return An object of \code{\link{biom-class}}.
+#'
+#' @references \url{http://biom-format.org/}
+#'
+#' @seealso
+#'
+#' \code{\link{write_biom}}
+#'
+#' \code{\link{biom-class}}
+#'
+#' \code{\link{read_biom}}
+#'
+#' @importFrom plyr alply
+#'
+#' @export
+#'
+#' @examples
+#' # import with default parameters, specify a file
+#' biomfile = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+#' x = read_biom(biomfile)
+#' data = biom_data(x)
+#' data
+#' smd = sample_metadata(x)
+#' smd
+#' omd = observation_metadata(x)
+#' omd
+#' # Make a new biom object from component data
+#' y = make_biom(data, smd, omd)
+#' # Won't be identical to x because of header info.
+#' identical(x, y)
+#' # The data components should be, though.
+#' identical(observation_metadata(x), observation_metadata(y))
+#' identical(sample_metadata(x), sample_metadata(y))
+#' identical(biom_data(x), biom_data(y))
+#' ## Quickly show that writing and reading still identical.
+#' # Define a temporary directory to write .biom files
+#' tempdir = tempdir()
+#' write_biom(x, biom_file=file.path(tempdir, "x.biom"))
+#' write_biom(y, biom_file=file.path(tempdir, "y.biom"))
+#' x1 = read_biom(file.path(tempdir, "x.biom"))
+#' y1 = read_biom(file.path(tempdir, "y.biom"))
+#' identical(observation_metadata(x1), observation_metadata(y1))
+#' identical(sample_metadata(x1), sample_metadata(y1))
+#' identical(biom_data(x1), biom_data(y1))
+make_biom <- function(data, sample_metadata=NULL, observation_metadata=NULL, id=NULL, matrix_element_type="int"){
+ # The observations / features / OTUs / rows "meta" data table
+ if(!is.null(observation_metadata)){
+ rows = mapply(list, SIMPLIFY=FALSE, id=as.list(rownames(data)),
+ metadata=alply(as.matrix(observation_metadata), 1, .expand=FALSE, .dims=TRUE))
+ } else {
+ rows = mapply(list, id=as.list(rownames(data)), metadata=NA, SIMPLIFY=FALSE)
+ }
+ # The samples / sites / columns "meta" data table
+ if(!is.null(sample_metadata)){
+ columns = mapply(list, SIMPLIFY=FALSE, id=as.list(colnames(data)),
+ metadata=alply(as.matrix(sample_metadata), 1, .expand=FALSE, .dims=TRUE))
+ } else {
+ columns = mapply(list, id=as.list(colnames(data)), metadata=NA, SIMPLIFY=FALSE)
+ }
+ # Convert the contingency table to a list
+ datalist = as.list(as.data.frame(as(t(data), "matrix")))
+ names(datalist) <- NULL
+ # Define the list, instantiate as biom-format, and return
+ # (Might eventually expose some of these list elements as function arguments)
+ format_url = "http://biom-format.org/documentation/format_versions/biom-1.0.html"
+ return(biom(list(id=id,
+ format = "Biological Observation Matrix 1.0.0-dev",
+ format_url = format_url,
+ type = "OTU table",
+ generated_by = sprintf("biomformat %s", packageVersion("biomformat")),
+ date = as.character(Sys.time()),
+ matrix_type = "dense",
+ matrix_element_type = matrix_element_type,
+ shape = dim(data),
+ rows = rows,
+ columns = columns,
+ data = datalist)
+ ))
+}
+################################################################################
+#' Method extensions to show for biom objects.
+#'
+#' See the general documentation of \code{\link[methods]{show}} method for
+#' expected behavior.
+#'
+#' @seealso \code{\link[methods]{show}}
+#'
+#' @param object biom-class object
+#'
+#' @export
+#'
+#' @rdname show-methods
+#'
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' show(x)
+setMethod("show", "biom", function(object){
+ cat("biom object. \n")
+ cat("type:", object$type, "\n")
+ cat("matrix_type:", object$matrix_type, "\n")
+ cat(biom_shape(object)[1], "rows and", biom_shape(object)[2], "columns \n")
+})
+################################################################################
+#' Extract the header from a \code{\link{biom-class}} object as a list.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @return A list containing the header data.
+#' That is, all the required elements that are not
+#' the main data or index metadata.
+#'
+#' @docType methods
+#' @rdname header-methods
+#' @export
+#' @examples
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' x = read_biom(biom_file)
+#' header(x)
+setGeneric("header", function(x) standardGeneric("header"))
+#' @rdname header-methods
+setMethod("header", c("biom"), function(x){
+ biomheadkeys = c("id", "format", "format_url", "type", "generated_by", "date",
+ "matrix_type", "matrix_element_type", "shape")
+ return(x[biomheadkeys])
+})
+################################################################################
+#' The matrix dimensions
+#' of a \code{\link{biom-class}} object.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @return A length two \code{\link{integer-class}} vector
+#' indicating the \code{\link{nrow}} and \code{\link{ncol}}
+#' of the main data matrix stored in \code{x}.
+#'
+#' @seealso
+#'
+#' \code{\link{biom-class}}
+#'
+#' @export
+#' @docType methods
+#' @rdname biom_shape-methods
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' biom_shape(x)
+setGeneric("biom_shape", function(x) standardGeneric("biom_shape"))
+#' @rdname biom_shape-methods
+setMethod("biom_shape", c("biom"), function(x){
+ return(as(c(nrow=x$shape[1], ncol=x$shape[2]), "integer"))
+})
+################################################################################
+#' Access class of data in the matrix elements
+#' of a \code{\link{biom-class}} object
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @return A \code{\link{character-class}} string indicating
+#' the class of the data stored in the main observation matrix of \code{x},
+#' with expected values \code{"int"}, \code{"float"}, \code{"unicode"}.
+#'
+#' @seealso
+#'
+#' \code{\link{biom-class}}
+#'
+#' @export
+#' @docType methods
+#' @rdname matrix_element_type-methods
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' matrix_element_type(x)
+setGeneric("matrix_element_type", function(x) standardGeneric("matrix_element_type"))
+#' @rdname matrix_element_type-methods
+setMethod("matrix_element_type", c("biom"), function(x){
+ return(x$matrix_element_type)
+})
+################################################################################
+#' Method extensions to \code{\link[base]{nrow}}
+#' for \code{\link{biom-class}} objects.
+#'
+#' See the general documentation of \code{\link[base]{nrow}} method for
+#' expected behavior.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @return The number of rows in \code{x}.
+#' A length 1 \code{\link{integer-class}}.
+#'
+#' @seealso
+#'
+#' \code{\link{ncol}}
+#'
+#' \code{\link[base]{nrow}}
+#'
+#' \code{\link{biom_shape}}
+#'
+#' @export
+#' @docType methods
+#' @rdname nrow-methods
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' nrow(x)
+setMethod("nrow", c("biom"), function(x){
+ return( biom_shape(x)["nrow"] )
+})
+################################################################################
+#' Method extensions to \code{\link[base]{ncol}}
+#' for \code{\link{biom-class}} objects.
+#'
+#' See the general documentation of \code{\link[base]{ncol}} method for
+#' expected behavior.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @return The number of columns in \code{x}.
+#' A length 1 \code{\link{integer-class}}.
+#'
+#' @seealso
+#'
+#' \code{\link{nrow}}
+#'
+#' \code{\link[base]{ncol}}
+#'
+#' \code{\link{biom_shape}}
+#'
+#' @export
+#' @docType methods
+#' @rdname ncol-methods
+#' @examples
+#' # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' ncol(x)
+setMethod("ncol", c("biom"), function(x){
+ return( biom_shape(x)["ncol"] )
+})
+################################################################################
+#' Method extensions to \code{\link[base]{rownames}}
+#' for \code{\link{biom-class}} objects.
+#'
+#' See the general documentation of \code{\link[base]{rownames}} method for
+#' expected behavior.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#' @return The number of columns in \code{x}.
+#' A length 1 \code{\link{integer-class}}.
+#'
+#' @seealso
+#'
+#' \code{\link{nrow}}
+#'
+#' \code{\link[base]{rownames}}
+#'
+#' \code{\link{biom_shape}}
+#'
+#' @export
+#' @docType methods
+#' @rdname rownames-methods
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' rownames(x)
+setMethod("rownames", c("biom"), function(x){
+ sapply(x$rows, function(i) i$id)
+})
+################################################################################
+#' Method extensions to \code{\link[base]{colnames}}
+#' for \code{\link{biom-class}} objects.
+#'
+#' See the general documentation of \code{\link[base]{colnames}} method for
+#' expected behavior.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#' @return The number of columns in \code{x}.
+#' A length 1 \code{\link{integer-class}}.
+#'
+#' @seealso
+#'
+#' \code{\link{nrow}}
+#'
+#' \code{\link[base]{colnames}}
+#'
+#' \code{\link{biom_shape}}
+#'
+#' @export
+#' @docType methods
+#' @rdname colnames-methods
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' (x = read_biom(biom_file) )
+#' colnames(x)
+setMethod("colnames", c("biom"), function(x){
+ sapply(x$columns, function(i) i$id)
+})
+################################################################################
+#' Access main data observation matrix data from \code{\link{biom-class}}.
+#'
+#' Retrieve and organize main data from \code{\link{biom-class}},
+#' represented as a matrix with index names.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#' @param rows (Optional). The subset of row indices described in the
+#' returned object. For large datasets, specifying the row subset here,
+#' rather than after creating the whole matrix first,
+#' can improve speed/efficiency.
+#' Can be vector of index numbers (\code{\link{numeric-class}}) or
+#' index names (\code{\link{character-class}}).
+#' @param columns (Optional). The subset of column indices described in the
+#' returned object. For large datasets, specifying the column subset here,
+#' rather than after creating the whole matrix first,
+#' can improve speed/efficiency.
+#' Can be vector of index numbers (\code{\link{numeric-class}}) or
+#' index names (\code{\link{character-class}}).
+#' @param parallel (Optional). Logical. Whether to perform the accession parsing
+#' using a parallel-computing backend supported by the \code{\link{plyr-package}}
+#' via the \code{\link[foreach]{foreach-package}}. Note: At the moment, the header
+#' accessor does not need nor does it support parallel-computed parsing.
+#'
+#' @return A matrix containing the main observation data, with index names.
+#' The type of data (numeric or character)
+#' will depend on the results of \code{\link{matrix_element_type}(x)}.
+#' The class of the matrix returned will depend on the sparsity of the data,
+#' and whether it has numeric or character data.
+#' For now, only numeric data can be stored in a \code{\link{Matrix-class}},
+#' which will be stored sparsely, if possible.
+#' Character data will be returned as a vanilla \code{\link{matrix-class}}.
+#'
+#' @rdname biom_data-methods
+#' @export
+#' @examples
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+#' rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+#' rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+#' rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+#' # Read the biom-format files
+#' x1 = read_biom(min_dense_file)
+#' x2 = read_biom(min_sparse_file)
+#' x3 = read_biom(rich_dense_file)
+#' x4 = read_biom(rich_sparse_file)
+#' x5 = read_biom(rich_dense_char)
+#' x6 = read_biom(rich_sparse_char)
+#' # Extract the data matrices
+#' biom_data(x1)
+#' biom_data(x2)
+#' biom_data(x3)
+#' biom_data(x4)
+#' biom_data(x5)
+#' biom_data(x6)
+setGeneric("biom_data", function(x, rows, columns, parallel=FALSE){
+ standardGeneric("biom_data")
+})
+# All methods funnel toward signature biom,numeric,numeric
+#' @rdname biom_data-methods
+setMethod("biom_data", c("biom", "missing", "missing"), function(x, rows, columns, parallel){
+ # Dispatch with full rows and cols
+ biom_data(x, 1:nrow(x), 1:ncol(x), parallel)
+})
+#' @rdname biom_data-methods
+setMethod("biom_data", c("biom", "character", "ANY"), function(x, rows, columns, parallel){
+ rows = which(rownames(x) %in% rows)
+ # Dispatch with specified numeric rows and pass cols
+ biom_data(x, rows, columns)
+})
+#' @rdname biom_data-methods
+setMethod("biom_data", c("biom", "ANY", "character"), function(x, rows, columns, parallel){
+ columns = which(colnames(x) %in% columns)
+ # Dispatch with specified numeric columns and pass rows
+ biom_data(x, rows, columns)
+})
+#' @rdname biom_data-methods
+setMethod("biom_data", c("biom", "numeric", "missing"), function(x, rows, columns, parallel){
+ # Dispatch with specified rows and full cols
+ biom_data(x, rows, 1:ncol(x), parallel)
+})
+#' @rdname biom_data-methods
+setMethod("biom_data", c("biom", "missing", "numeric"), function(x, rows, columns, parallel){
+ # Dispatch with full rows and specified cols
+ biom_data(x, 1:nrow(x), columns, parallel)
+})
+#' @rdname biom_data-methods
+#' @import Matrix
+#' @importFrom plyr d_ply
+#' @importFrom plyr ldply
+#' @importFrom plyr laply
+setMethod("biom_data", c("biom", "numeric", "numeric"), function(x, rows, columns, parallel){
+ if( identical(length(rows), 0) ){
+ stop("argument `rows` must have non-zero length.")
+ }
+ if( identical(length(columns), 0) ){
+ stop("argument `columns` must have non-zero length.")
+ }
+ # Begin matrix section
+ if( identical(x$matrix_type, "dense") ){
+ # Begin dense section
+ # If matrix is stored as dense, create "vanilla" R matrix, m
+ m = laply(x$data[rows], function(i) i[columns], .parallel=parallel)
+ if( length(rows) > 1L &
+ length(columns) > 1L &
+ matrix_element_type(x) %in% c("int", "float")
+ ){
+ # If either dimension is length-one, don't call coerce to "Matrix"
+ # Note that laply() does still work in this case.
+ # If both dimension lengths > 1 & data is numeric,
+ # attempt to coerce to Matrix-inherited class,
+ # Mainly because it might still be sparse and this is a good way
+ # to handle it in R.
+ m = Matrix(m)
+ }
+ } else {
+ # Begin sparse section
+ ## Initialize sparse matrix as either Matrix or matrix, depending on data class
+ biom_shape = biom_shape(x)
+ if(matrix_element_type(x) %in% c("int", "float")){
+ # If data is numeric, initialize with Matrix (numeric data only)
+ m = Matrix(0, nrow=nrow(x), ncol=ncol(x), sparse=TRUE)
+ # Create an assignment data.frame
+ adf = ldply(x$data)
+ } else {
+ # Else, matrix_element_type must be "unicode" for a unicode string.
+ # Use a standard R character matrix
+ m = matrix(NA_character_, nrow(x), ncol(x))
+ # Create an assignment data.frame.
+ # Is slightly more complicated for sparse JSON w/ character values
+ adf = ldply(x$data, function(x){
+ data.frame(r=x[[1]], c=x[[2]], data=x[[3]], stringsAsFactors=FALSE)
+ })
+ }
+ colnames(adf) <- c("r", "c", "data")
+ # indices start at 0 in biom sparse format,
+ # and are first two columns
+ adf[, c("r", "c")] <- cbind(r = as.integer(adf$r) + 1L,
+ c = as.integer(adf$c) + 1L)
+ # Subset to just indices that are in both arguments `rows` and `columns`
+ adf <- adf[(adf$r %in% rows & adf$c %in% columns), ]
+ # Fill in data values in matrix, m.
+ # Vectorized for speed using matrix indexing.
+ # See help("Extract") for details about matrix indexing. Diff than 2-vec index.
+ m[as(adf[, 1:2], "matrix")] <- adf$data
+ # Subset this biggest-size m to just `rows` and `columns`
+ m = m[rows, columns]
+ # End sparse section
+ }
+ # Add row and column names
+ if( identical(length(rows), 1L) | identical(length(columns), 1L) ){
+ # If either dimension is length-one
+ # Try naming by colnames first, then rownames
+ if( identical(length(rows), 1L) ){
+ names(m) <- sapply(x$columns[columns], function(i) i$id )
+ } else {
+ names(m) <- sapply(x$rows[rows], function(i) i$id )
+ }
+ } else {
+ # Else, both dimensions are longer than 1,
+ # can assume is a matrix and assign names to both dimensions
+ rownames(m) <- sapply(x$rows[rows], function(i) i$id )
+ colnames(m) <- sapply(x$columns[columns], function(i) i$id )
+ }
+ return(m)
+})
+################################################################################
+#' Access meta data from \code{\link{biom-class}}.
+#'
+#' Retrieve and organize meta data from \code{\link{biom-class}},
+#' represented as a \code{\link{data.frame}} (if possible, or a list)
+#' with proper index names.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @param columns (Optional). The subset of column indices described in the
+#' returned object. For large datasets, specifying the column subset here,
+#' rather than after creating the whole matrix first,
+#' can improve speed/efficiency.
+#' Can be vector of index numbers (\code{\link{numeric-class}}) or
+#' index names (\code{\link{character-class}}).
+#'
+#' @param parallel (Optional). Logical. Whether to perform the accession parsing
+#' using a parallel-computing backend supported by the \code{\link{plyr-package}}
+#' via the \code{\link[foreach]{foreach-package}}.
+#'
+#' @return A \code{\link{data.frame}} or \code{\link{list}} containing
+#' the meta data, with index names. The precise form of the object returned
+#' depends on the metadata stored in \code{x}. A \code{data.frame} is
+#' created if possible.
+#'
+#' @rdname sample_metadata-methods
+#' @export
+#' @examples
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+#' rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+#' rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+#' rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+#' # Read the biom-format files
+#' x1 = read_biom(min_dense_file)
+#' x2 = read_biom(min_sparse_file)
+#' x3 = read_biom(rich_dense_file)
+#' x4 = read_biom(rich_sparse_file)
+#' x5 = read_biom(rich_dense_char)
+#' x6 = read_biom(rich_sparse_char)
+#' # Extract metadata
+#' sample_metadata(x1)
+#' sample_metadata(x2)
+#' sample_metadata(x3)
+#' sample_metadata(x3, 1:4)
+#' sample_metadata(x4)
+#' sample_metadata(x5)
+#' sample_metadata(x6)
+setGeneric("sample_metadata", function(x, columns, parallel=FALSE){
+ standardGeneric("sample_metadata")
+})
+# All methods funnel toward signature biom,numeric
+#' @rdname sample_metadata-methods
+setMethod("sample_metadata", c("biom", "missing"), function(x, columns, parallel=FALSE){
+ # Dispatch with full rows and cols
+ sample_metadata(x, 1:ncol(x), parallel)
+})
+#' @rdname sample_metadata-methods
+setMethod("sample_metadata", c("biom", "character"), function(x, columns, parallel=FALSE){
+ columns = which(sapply(x$columns, function(j) j$id) %in% columns)
+ if( length(columns)==0 ){
+ stop("The column ID names you provided do not match the column IDs in x")
+ }
+ # Dispatch with specified numeric columns
+ sample_metadata(x, columns, parallel)
+})
+#' @rdname sample_metadata-methods
+setMethod("sample_metadata", c("biom", "numeric"), function(x, columns, parallel=FALSE){
+ if( any(columns > ncol(x)) ){
+ warning(paste0("column indices ",
+ paste0(columns[columns > ncol(x)], collapse=" "),
+ " are greater than available columns in data. They were ignored."))
+ columns = columns[columns <= ncol(x)]
+ }
+ return(extract_metadata(x, "columns", columns, parallel))
+})
+################################################################################
+#' Access observation (row) meta data from \code{\link{biom-class}}.
+#'
+#' Retrieve and organize meta data from \code{\link{biom-class}},
+#' represented as a \code{\link{data.frame}} (if possible)
+#' or a list, with proper index names.
+#'
+#' @param x (Required). An instance of the \code{\link{biom-class}}.
+#'
+#' @param rows (Optional). The subset of row indices described in the
+#' returned object. For large datasets, specifying the row subset here,
+#' -- rather than first creating the complete data object --
+#' can improve speed/efficiency.
+#' This parameter can be vector of index numbers (\code{\link{numeric-class}}) or
+#' index names (\code{\link{character-class}}).
+#'
+#' @param parallel (Optional). Logical. Whether to perform the accession parsing
+#' using a parallel-computing backend supported by the \code{\link{plyr-package}}
+#' via the \code{\link[foreach]{foreach-package}}.
+#'
+#' @return A \code{\link{data.frame}} or \code{\link{list}} containing
+#' the meta data, with index names. The precise form of the object returned
+#' depends on the metadata stored in \code{x}. A \code{data.frame} is
+#' created if possible.
+#'
+#' @rdname observation_metadata-methods
+#' @export
+#' @examples
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+#' rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+#' rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+#' rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+#' rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+#' # Read the biom-format files
+#' x1 = read_biom(min_dense_file)
+#' x2 = read_biom(min_sparse_file)
+#' x3 = read_biom(rich_dense_file)
+#' x4 = read_biom(rich_sparse_file)
+#' x5 = read_biom(rich_dense_char)
+#' x6 = read_biom(rich_sparse_char)
+#' # Extract metadata
+#' observation_metadata(x1)
+#' observation_metadata(x2)
+#' observation_metadata(x3)
+#' observation_metadata(x3, 2:4)
+#' observation_metadata(x3, 2)
+#' observation_metadata(x3, c("GG_OTU_3", "GG_OTU_4", "whoops"))
+#' observation_metadata(x4)
+#' observation_metadata(x5)
+#' observation_metadata(x6)
+setGeneric("observation_metadata", function(x, rows, parallel=FALSE){
+ standardGeneric("observation_metadata")
+})
+# All methods funnel toward signature biom,numeric
+#' @rdname observation_metadata-methods
+setMethod("observation_metadata", c("biom", "missing"), function(x, rows, parallel=FALSE){
+ # Dispatch with full rows and cols
+ observation_metadata(x, 1:nrow(x), parallel)
+})
+#' @rdname observation_metadata-methods
+setMethod("observation_metadata", c("biom", "character"), function(x, rows, parallel=FALSE){
+ rows = which(sapply(x$rows, function(j) j$id) %in% rows)
+ if( length(rows)==0 ){
+ stop("The row ID names you provided do not match the row IDs in x")
+ }
+ # Dispatch with specified numeric rows
+ observation_metadata(x, rows, parallel)
+})
+#' @rdname observation_metadata-methods
+setMethod("observation_metadata", c("biom", "numeric"), function(x, rows, parallel=FALSE){
+ if( any(rows > nrow(x)) ){
+ warning(paste0("Row indices ",
+ paste0(rows[rows > nrow(x)], collapse=" "),
+ " are greater than available rows in data. They were ignored."))
+ rows = rows[rows <= nrow(x)]
+ }
+ return(extract_metadata(x, "rows", rows, parallel))
+})
+################################################################################
+# Generic internal function for extracting metadata from either rows or columns
+#' @importFrom plyr ldply
+#' @importFrom plyr llply
+#' @keywords internal
+extract_metadata = function(x, indextype, indices, parallel=FALSE){
+ # Immediately extract just those index indicated by `index` argument
+ metalist = x[[indextype]][indices]
+ # Extract metadata elements as a list, for checking dimensions, NULL, etc.
+ rx = llply(metalist, function(i) unlist(i$metadata), .parallel=parallel)
+ if( all(sapply(rx, is.null)) ){
+ # If there is no metadata (all NULL),
+ # then set metadata to NULL, representing empty.
+ metadata = NULL
+ } else {
+ # Else, extract names and metadata (both required)
+ # Extract names
+ metaids = sapply(metalist, function(i) i$id)
+ # Test if length of metadata entries is same for all indices.
+ rxlengths = sapply(rx, length)
+ if( all( rxlengths == rxlengths[1]) ){
+ # If so, can parse it as data.frame with ldply
+ # return a data.frame with colnames
+ metadata = ldply(rx, .parallel=parallel)
+ rownames(metadata) <- metaids
+ } else {
+ # Else, should keep it as a list. But should name the entries
+ metadata = rx
+ names(metadata) <- metaids
+ }
+ }
+ return(metadata)
+}
+################################################################################
+# Generic internal function for generating the count matrix.
+#' @keywords internal
+generate_matrix <- function(x){
+ indptr = x$sample$matrix$indptr+1
+ indices = x$sample$matrix$indices+1
+ data = x$sample$matrix$data
+ nr = length(x$observation$ids)
+
+ counts = sapply(2:length(indptr),function(i){
+ x = rep(0,nr)
+ seq = indptr[i-1]:(indptr[i]-1)
+ x[indices[seq]] = data[seq]
+ x
+ })
+ rownames(counts) = x$observation$ids
+ colnames(counts) = x$sample$ids
+ # I wish this next line wasn't necessary
+ lapply(1:nrow(counts),function(i){
+ counts[i,]
+ })
+}
+################################################################################
+# Generic internal function for generating the metadata.
+#' @keywords internal
+generate_metadata <- function(x){
+ metadata = x$metadata
+ metadata = lapply(1:length(x$ids),function(i){
+ id_metadata = lapply(metadata,function(j){
+ if(length(dim(j))>1){ as.vector(j[,i,drop=FALSE]) }
+ else{ j[i] }
+ })
+ list(id = x$ids[i],metadata=id_metadata)
+ })
+ return(metadata)
+}
+################################################################################
+# Generic internal function for generating a named list.
+#' @keywords internal
+namedList <- function(...) {
+ L <- list(...)
+ snm <- sapply(substitute(list(...)),deparse)[-1]
+ if (is.null(nm <- names(L))) nm <- snm
+ if (any(nonames <- nm=="")) nm[nonames] <- snm[nonames]
+ setNames(L,nm)
+}
+################################################################################
diff --git a/R/IO-methods.R b/R/IO-methods.R
new file mode 100644
index 0000000..0cd4240
--- /dev/null
+++ b/R/IO-methods.R
@@ -0,0 +1,184 @@
+################################################################################
+################################################################################
+#' Read a biom-format file, returning a \code{biom-class}.
+#'
+#' Import the data from a biom-format file into R, represented as an instance
+#' of the \code{\link{biom-class}}; essentially a \code{\link{list}} with
+#' special constraints that map to \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+#'
+#' The BIOM file format (canonically pronounced biome) is designed to be a general-use format for representing biological sample by observation contingency tables. BIOM is a recognized standard for the \href{http://www.earthmicrobiome.org/}{Earth Microbiome Project} and is a \href{http://gensc.org/}{Genomics Standards Consortium} candidate project. Please see \href{http://biom-format.org/}{the biom-format home page} for more details.
+#'
+#' It is tempting to include an argument identifying the
+#' biom-format version number of the data file being imported.
+#' However, the biom-format version number is a required
+#' field in the biom-format definition.
+#' Rather than duplicate this formal specification
+#' and allow the possibility of a conflict, the version
+#' number of the biom format will be referred to only by
+#' the "format" field in the biom formatted data,
+#' or its representation in R.
+#'
+#' @usage read_biom(biom_file)
+#'
+#' @param biom_file (Required). A character string indicating the
+#' file location of the biom formatted file. This is a HDF5 or JSON formatted file
+#' specific to biological datasets.
+#' The format is formally defined at \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}
+#' and depends on the versioning.
+#'
+#' @return An instance of the \code{biom-class}.
+#'
+#' @seealso
+#'
+#' Function to create a biom object from R data,
+#' \code{\link{make_biom}}.
+#'
+#' Definition of the
+#' \code{\link{biom-class}}.
+#'
+#' Function to write a biom format file from a biom object,
+#' \code{\link{write_biom}}
+#'
+#' Accessor functions like \code{\link{header}}.
+#'
+#' @references \url{http://biom-format.org/}
+#'
+#' @importFrom jsonlite fromJSON
+#' @export
+#' @examples
+#' # # # import with default parameters, specify a file
+#' biom_file <- system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' biom_file
+#' read_biom(biom_file)
+#' biom_file <- system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+#' biom_file
+#' read_biom(biom_file)
+#' ## The previous examples use system.file() because of constraints in specifying a fixed
+#' ## path within a reproducible example in a package.
+#' ## In practice, however, you can simply provide "hard-link"
+#' ## character string path to your file:
+#' # mybiomfile <- "path/to/my/biomfile.biom"
+#' # read_biom(mybiomfile)
+read_biom <- function(biom_file){
+ # Read the file, storing as a list
+ # generated by jsonlite w/ default JSON parsing params
+ trash = try(silent=TRUE,
+ expr = {
+ x <- fromJSON(biom_file, simplifyDataFrame = FALSE, simplifyMatrix = FALSE)
+ })
+ if(inherits(trash, "try-error")){
+ # If JSON interpretation attempt failed, try HDF5
+ trash = try(silent=TRUE,
+ expr = {x <- read_hdf5_biom(biom_file)})
+ }
+ if(inherits(trash, "try-error")){
+ # If still bad, throw helpful error.
+ stop("Both attempts to read input file:\n",
+ biom_file, "\n",
+ "either as JSON (BIOM-v1) or HDF5 (BIOM-v2).\n",
+ "Check file path, file name, file itself, then try again.")
+ }
+ # Use the biom() constructor function to
+ # instantiate a biom-class, perform validity checks. Return.
+ return( biom(x) )
+}
+################################################################################
+#' Write a biom-format v1 file, returning a \code{biom-class}.
+#'
+#' @param x (Required). A biom object that is going to be written to file
+#' as a proper biom formatted file, adhering to
+#' \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+#'
+#' @param biom_file (Required). A character string indicating the
+#' file location of the biom formatted file. This is a JSON formatted file
+#' specific to biological datasets.
+#' The format is formally defined at
+#' \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}
+#'
+#' @return Nothing. The first argument, \code{x}, is written to a file.
+#'
+#' @seealso
+#'
+#' Function to create a biom object from R data,
+#' \code{\link{make_biom}}.
+#'
+#' Definition of the
+#' \code{\link{biom-class}}.
+#'
+#' The \code{\link{read_biom}} import function.
+#'
+#' Accessor functions like \code{\link{header}}.
+#'
+#' @references \url{http://biom-format.org/}
+#'
+#' @export
+#' @importFrom jsonlite toJSON
+#' @examples
+#' biom_file <- system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' x = read_biom(biom_file)
+#' outfile = tempfile()
+#' write_biom(x, outfile)
+#' y = read_biom(outfile)
+#' identical(x, y)
+write_biom <- function(x, biom_file){
+ cat(toJSON(x), file=biom_file)
+}
+################################################################################
+#' Read in a biom-format vs 2 file, returning a \code{list}.
+#'
+#' This function is meant only to be used if the user knows the file is
+#' a particular version / hdf5 format. Otherwise, the `read_biom` file should be used.
+#'
+#' @param biom_file (Required). A biom object that is going to be written to file
+#' as a proper biom formatted file, adhering to
+#' \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+#'
+#' @return Nothing. The first argument, \code{x}, is written to a file.
+#'
+#' @seealso
+#'
+#' Function to create a biom object from R data,
+#' \code{\link{make_biom}}.
+#'
+#' Definition of the
+#' \code{\link{biom-class}}.
+#'
+#' The \code{\link{read_hdf5_biom}} import function.
+#'
+#' Accessor functions like \code{\link{header}}.
+#'
+#' @references \url{http://biom-format.org/}
+#'
+#' @export
+#' @importFrom rhdf5 h5read
+#' @examples
+#' biom_file <- system.file("extdata", "rich_sparse_otu_table_hdf5.biom", package = "biomformat")
+#' x = read_hdf5_biom(biom_file)
+#' x = biom(x)
+#' outfile = tempfile()
+#' write_biom(x, outfile)
+#' y = read_biom(outfile)
+#' identical(observation_metadata(x),observation_metadata(y))
+#' identical(sample_metadata(x),sample_metadata(y))
+#' identical(biom_data(x), biom_data(y))
+read_hdf5_biom<-function(biom_file){
+ x = h5read(biom_file,"/",read.attributes = TRUE)
+ data = generate_matrix(x)
+ rows = generate_metadata(x$observation)
+ columns = generate_metadata(x$sample)
+ shape = c(length(data),length(data[[1]]))
+
+ id = attr(x,"id")
+ vs = attr(x,"format-version")
+ format = sprintf("Biological Observation Matrix %s.%s",vs[1],vs[2])
+ format_url = attr(x,"format-url")
+ type = "OTU table"
+ generated_by = attr(x,"generated-by")
+ date = attr(x,"creation-date")
+ matrix_type = "dense"
+ matrix_element_type = "int"
+
+ namedList(id,format,format_url,type,generated_by,date,matrix_type,matrix_element_type,
+ rows,columns,shape,data)
+}
+################################################################################
\ No newline at end of file
diff --git a/R/allClasses.R b/R/allClasses.R
new file mode 100644
index 0000000..d49fb6f
--- /dev/null
+++ b/R/allClasses.R
@@ -0,0 +1,51 @@
+################################################################################
+#' The biom format data class.
+#'
+#' This class inherits from the \code{\link{list-class}},
+#' with validity checks specific to the definition to the biom-format.
+#' Effectively this means the list must have certain index names,
+#' some elements of which must have a specific structure or value.
+#' For further details see
+#' \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+#' Importantly, this means other special properties of lists,
+#' like operations with \code{$} and single- or double-square-braces
+#' are also supported; as-is the \code{apply}-family function
+#' that can operate on lists.
+#' Note that some features of the biom-format can be essentially empty,
+#' represented by the string \code{"null"} in the file.
+#' These fields are returned as \code{\link{NULL}} when accessed
+#' by an accessor function.
+#'
+#' @seealso
+#' The constructor, \code{\link{biom}}
+#'
+#' Accessor functions:
+#'
+#' \code{\link{header}},
+#' \code{\link{biom_shape}},
+#' \code{\link{nrow}},
+#' \code{\link{ncol}},
+#' \code{\link{matrix_element_type}},
+#' \code{\link{biom_data}},
+#' \code{\link{observation_metadata}},
+#' \code{\link{sample_metadata}}
+#'
+#' @name biom-class
+#' @rdname biom-class
+#' @exportClass biom
+#'
+#' @examples
+#' biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+#' x = read_biom(biom_file)
+#' header(x)
+#' biom_shape(x)
+#' nrow(x)
+#' ncol(x)
+#' rownames(x)
+#' colnames(x)
+#' matrix_element_type(x)
+#' biom_data(x)
+#' observation_metadata(x)
+#' sample_metadata(x)
+setClass("biom", contains="list")
+################################################################################
diff --git a/R/allPackage.R b/R/allPackage.R
new file mode 100644
index 0000000..fd5bdaf
--- /dev/null
+++ b/R/allPackage.R
@@ -0,0 +1,19 @@
+###############################################
+#' This is an R package for interfacing with the biom format.
+#'
+#' This is an R package for interfacing with the biom-format.
+#' It includes basic utilities for reading and writing BIOM format using R,
+#' and native R methods for interacting with biom-data
+#' that maps to functionality in other languages
+#' that support biom-format, like python.
+#'
+#' @import methods
+#' @name biom-package
+#' @author Paul J. McMurdie II \email{mcmurdie@@stanford.edu}
+#' @references
+#' \url{http://www.biom-format.org/}
+#'
+#' @docType package
+#' @keywords package
+NA
+###############################################
diff --git a/R/validity-methods.R b/R/validity-methods.R
new file mode 100644
index 0000000..2bcca03
--- /dev/null
+++ b/R/validity-methods.R
@@ -0,0 +1,115 @@
+################################################################################
+# Validity methods:
+#
+# These are delicate, because they are effectively at the S4 infrastructure
+# level, in between "new" and the constructor. Some of the issues that might
+# otherwise go here can be also be dealt with in the constructors, if needed.
+################################################################################
+validbiom = function(object){
+
+ # All the required top-level keys are present
+ biomreqdkeys = c("id", "format", "format_url", "type", "generated_by", "date",
+ "rows", "columns", "matrix_type", "matrix_element_type", "shape", "data")
+
+ if( !all(biomreqdkeys %in% names(object)) ){
+ missingkeysmessage = paste("",
+ "Not all required top-level keys are present in biom-object.",
+ "Required keys are:", paste0(biomreqdkeys, collapse="\n"),
+ sep="\n")
+ return(missingkeysmessage)
+ }
+
+ met = matrix_element_type(object)
+ if(!identical(length(met), 1L)){
+ return("biom matrix_element_type field should have only 1 element")
+ }
+ if( !met %in% c("int", "float", "unicode") ){
+ return("biom matrix_element_type value is unsupported.")
+ }
+
+ # Basic biom_shape value validity.
+ bshape = biom_shape(object)
+ if(!inherits(bshape, "integer")){
+ return("problem with biom shape value type")
+ }
+ if(!identical(length(bshape), 2L)){
+ return("problem with biom shape value length")
+ }
+ if(any(bshape < 0)){
+ return("problem with biom shape value: negative value")
+ }
+
+ # Matrix shape and number of row/col elements matches
+ if( ncol(object) > length(object$columns) ){
+ return("shape field specifies more cols than are present in metadata")
+ }
+ if( nrow(object) > length(object$rows) ){
+ return("shape field specifies more rows than are present in metadata")
+ }
+ if( ncol(object) < length(object$columns) ){
+ return("more metadata cols than specified by shape field")
+ }
+ if( nrow(object) < length(object$rows) ){
+ return("more metadata rows than specified by shape field")
+ }
+
+ # The type field has an acceptable value
+ biomtypevals = c("OTU table",
+ "Pathway table",
+ "Function table",
+ "Ortholog table",
+ "Gene table",
+ "Metabolite table",
+ "Taxon table"
+ )
+ if( !object$type %in% biomtypevals ){
+ return("type field has unsupported value")
+ }
+
+ # The matrix_type has an acceptable value
+ biommatrixtypes = c("sparse", "dense")
+ if( !object$matrix_type %in% biommatrixtypes ){
+ return("matrix_type field has unsupported value")
+ }
+
+ # The matrix_element_type has an acceptable value
+ biommatrixelemtypes = c("int", "float", "unicode")
+ if( !object$matrix_element_type %in% biommatrixelemtypes ){
+ return("matrix_element_type field has unsupported value")
+ }
+
+ # If sparse, all data fields should have length of 3 (row, col, val)
+ if( identical(object$matrix_type, "sparse") ){
+ if( !all(sapply(object$data, length)==3L) ){
+ return("Some data fields for this sparse biom format do not have 3 elements")
+ }
+ }
+ # If dense, data fields should have length equal to ncol
+ if( identical(object$matrix_type, "dense") ){
+ if( !all(sapply(object$data, length)==ncol(object)) ){
+ return(paste("Some data fields for this dense biom format",
+ "do not have the expected number columns:", ncol(object), sep=" "))
+ }
+ }
+
+ # metadata ids -- rownames and colnames -- must be unique
+ dupr = duplicated(rownames(object))
+ dupc = duplicated(colnames(object))
+ if( any(dupr) ){
+ return(paste("The following row ids were duplicated: \n",
+ paste0(rownames(object)[dupr], collapse="\n"), sep=""))
+ }
+ if( any(dupc) ){
+ return(paste("The following col ids were duplicated: \n",
+ paste0(colnames(object)[dupc], collapse="\n"), sep=""))
+ }
+
+ # If we get all the way here without returning a string,
+ # then consider it a valid object.
+ # In which case should return TRUE.
+ return(TRUE)
+}
+################################################################################
+## assign the function as the validity method for the biom-class
+setValidity("biom", validbiom)
+################################################################################
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2a6dbf8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+
+# The biomformat Package for R
+
+[](https://travis-ci.org/joey711/biomformat)
+
+# About
+
+This is an R package for interfacing with both the JSON and HDF5 versions of the [biom file format](http://biom-format.org/). This package includes basic tools for reading biom-format files, accessing and subsetting data tables from a biom object, as well as limited support for writing a biom-object back to a biom-format file.
+
+# Design
+
+The design of this API is intended to match the python API where appropriate, while maintaining a decidedly "R flavor" that should be familiar to R users. This includes S4 classes and methods, as well as extensions of common core functions/methods.
+
+# Installation
+
+To install the latest stable release of the biomformat package enter the following in an R session (after official release).
+
+```S
+source("http://bioconductor.org/biocLite.R")
+biocLite("biomformat")
+```
+
+Before official release, or to install the latest development version, enter the following into an R session.
+
+```S
+install.packages("devtools") # if not already installed
+devtools::install_github("joey711/biomformat")
+```
+
+# Support
+
+ * Please post feature or support requests and bugs at the [Issues Tracker for the biomformat package](https://github.com/joey711/biomformat/issues) on GitHub.
+ Issues related to the format itself and not the R interface should be posted on the [issues tracker for the biom-format team](https://github.com/biocore/biom-format/issues).
+
+ * Note that this is a separate (but friendly!) project from the biom-format team, and the software license is different between this package and much of the rest of the biom-format software, which has switched to BSD.
+
+ * This package is scheduled for inclusion in the next stable release of the Bioconductor project (BioC).
+ BioC is also where [the rhdf5 package](http://bioconductor.org/packages/release/bioc/html/rhdf5.html) lives.
+
+ * The original release of this package was [made available through CRAN](http://cran.r-project.org/web/packages/biom/index.html),
+ as the "biom" package, supporting version 1.x (JSON) only.
+ The current plan is to let "biom" remain on CRAN in maintenance-only mode until "biomformat" is released on Bioconductor. At which point "biom" will be considered deprecated, and eventually removed.
+
diff --git a/build/vignette.rds b/build/vignette.rds
new file mode 100644
index 0000000..3a83c03
Binary files /dev/null and b/build/vignette.rds differ
diff --git a/debian/README.test b/debian/README.test
deleted file mode 100644
index 53fb4d7..0000000
--- a/debian/README.test
+++ /dev/null
@@ -1,8 +0,0 @@
-Notes on how this package can be tested.
-────────────────────────────────────────
-
-This package can be tested by running the provided test:
-
- sh ./run-unit-test
-
-in order to confirm its integrity.
diff --git a/debian/changelog b/debian/changelog
deleted file mode 100644
index c8a5ad7..0000000
--- a/debian/changelog
+++ /dev/null
@@ -1,14 +0,0 @@
-r-bioc-biomformat (1.2.0-1) unstable; urgency=medium
-
- * New upstream version
- * Convert to dh-r
- * Generic BioConductor homepage
- * d/watch: version=4
-
- -- Andreas Tille <tille at debian.org> Fri, 11 Nov 2016 09:51:06 +0100
-
-r-bioc-biomformat (1.0.2-1) unstable; urgency=low
-
- * Initial release (closes: #835579)
-
- -- Andreas Tille <tille at debian.org> Sat, 27 Aug 2016 11:21:59 +0200
diff --git a/debian/compat b/debian/compat
deleted file mode 100644
index ec63514..0000000
--- a/debian/compat
+++ /dev/null
@@ -1 +0,0 @@
-9
diff --git a/debian/control b/debian/control
deleted file mode 100644
index 25cdeba..0000000
--- a/debian/control
+++ /dev/null
@@ -1,33 +0,0 @@
-Source: r-bioc-biomformat
-Maintainer: Debian Med Packaging Team <debian-med-packaging at lists.alioth.debian.org>
-Uploaders: Andreas Tille <tille at debian.org>
-Section: gnu-r
-Priority: optional
-Build-Depends: debhelper (>= 9),
- dh-r,
- r-base-dev,
- r-cran-plyr,
- r-cran-jsonlite,
- r-cran-matrix,
- r-cran-hdf5
-Standards-Version: 3.9.8
-Vcs-Browser: https://anonscm.debian.org/viewvc/debian-med/trunk/packages/R/r-bioc-biomformat/trunk/
-Vcs-Svn: svn://anonscm.debian.org/debian-med/trunk/packages/R/r-bioc-biomformat/trunk/
-Homepage: https://bioconductor.org/packages/biomformat/
-
-Package: r-bioc-biomformat
-Architecture: all
-Depends: ${R:Depends},
- ${misc:Depends}
-Recommends: ${R:Recommends}
-Suggests: ${R:Suggests}
-Description: GNU R interface package for the BIOM file format
- This is an R package for interfacing with the BIOM format. This package
- includes basic tools for reading biom-format files, accessing and
- subsetting data tables from a biom object (which is more complex than a
- single table), as well as limited support for writing a biom-object back
- to a biom-format file. The design of this API is intended to match the
- Python API and other tools included with the biom-format project, but
- with a decidedly "R flavor" that should be familiar to R users. This
- includes S4 classes and methods, as well as extensions of common core
- functions/methods.
diff --git a/debian/copyright b/debian/copyright
deleted file mode 100644
index 98d17e2..0000000
--- a/debian/copyright
+++ /dev/null
@@ -1,29 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Name: biomformat
-Upstream-Contact: Paul J. McMurdie <mcmurdie at stanford.edu>
-Source: https://bioconductor.org/packages/biomformat/
-
-Files: *
-Copyright: 2012-2016 Paul J. McMurdie <mcmurdie at stanford.edu>
-License: GPL-2
-
-Files: debian/*
-Copyright: 2016 Andreas Tille <tille at debian.org>
-License: GPL-2
-
-License: GPL-2
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License.
- .
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- .
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
- .
- You can find the text of GNU General Public License version 2.0
- at /usr/share/common-licenses/GPL-2.
diff --git a/debian/docs b/debian/docs
deleted file mode 100644
index 960011c..0000000
--- a/debian/docs
+++ /dev/null
@@ -1,3 +0,0 @@
-tests
-debian/README.test
-debian/tests/run-unit-test
diff --git a/debian/patches/series b/debian/patches/series
deleted file mode 100644
index f8768ac..0000000
--- a/debian/patches/series
+++ /dev/null
@@ -1 +0,0 @@
-use_debian_packaged_hdf5.patch
diff --git a/debian/patches/use_debian_packaged_hdf5.patch b/debian/patches/use_debian_packaged_hdf5.patch
deleted file mode 100644
index fb75d25..0000000
--- a/debian/patches/use_debian_packaged_hdf5.patch
+++ /dev/null
@@ -1,23 +0,0 @@
-Author: Andreas Tille <tille at debian.org>
-Last-Update: Mon, 22 Aug 2016 22:15:51 +0200
-Description: It seems there is no need to package BioConductor rhdf5 and we
- wan go with r-cran-hdf5 - at least the test suite passes with this strategy
-
---- a/DESCRIPTION
-+++ b/DESCRIPTION
-@@ -13,7 +13,7 @@ Description: This is an R package for in
- back to a biom-format file. The design of this API is intended to match the python API and other tools included with the biom-format
- project, but with a decidedly "R flavor" that should be familiar to R users. This includes S4 classes and methods, as well as extensions of
- common core functions/methods.
--Imports: plyr (>= 1.8), jsonlite (>= 0.9.16), Matrix (>= 1.2), rhdf5
-+Imports: plyr (>= 1.8), jsonlite (>= 0.9.16), Matrix (>= 1.2)
- Depends: R (>= 3.2), methods
- Suggests: testthat (>= 0.10), knitr (>= 1.10), BiocStyle (>= 1.6),
- rmarkdown (>= 0.7)
---- a/NAMESPACE
-+++ b/NAMESPACE
-@@ -26,4 +26,3 @@ importFrom(plyr,d_ply)
- importFrom(plyr,laply)
- importFrom(plyr,ldply)
- importFrom(plyr,llply)
--importFrom(rhdf5,h5read)
diff --git a/debian/rules b/debian/rules
deleted file mode 100755
index 68d9a36..0000000
--- a/debian/rules
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/usr/bin/make -f
-
-%:
- dh $@ --buildsystem R
diff --git a/debian/source/format b/debian/source/format
deleted file mode 100644
index 163aaf8..0000000
--- a/debian/source/format
+++ /dev/null
@@ -1 +0,0 @@
-3.0 (quilt)
diff --git a/debian/tests/control b/debian/tests/control
deleted file mode 100644
index b044b0c..0000000
--- a/debian/tests/control
+++ /dev/null
@@ -1,3 +0,0 @@
-Tests: run-unit-test
-Depends: @, r-cran-testthat
-Restrictions: allow-stderr
diff --git a/debian/tests/run-unit-test b/debian/tests/run-unit-test
deleted file mode 100644
index f89e590..0000000
--- a/debian/tests/run-unit-test
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/sh -e
-
-oname=biomformat
-pkg=r-bioc-`echo $oname | tr '[A-Z]' '[a-z]'`
-
-if [ "$ADTTMP" = "" ] ; then
- ADTTMP=`mktemp -d /tmp/${pkg}-test.XXXXXX`
- trap "rm -rf $ADTTMP" 0 INT QUIT ABRT PIPE TERM
-fi
-cd $ADTTMP
-cp -a /usr/share/doc/${pkg}/tests/* $ADTTMP
-LC_ALL=C R --no-save < testthat-biomformat.R
-rm -fr $ADTTMP/*
diff --git a/debian/watch b/debian/watch
deleted file mode 100644
index 8ba7b51..0000000
--- a/debian/watch
+++ /dev/null
@@ -1,3 +0,0 @@
-version=4
-opts=downloadurlmangle=s?^(.*)\.\.?http:$1packages/release/bioc? \
- http://www.bioconductor.org/packages/release/bioc/html/biomformat.html .*/biomformat_([\d\.]+)\.tar\.gz
diff --git a/inst/doc/biomformat.R b/inst/doc/biomformat.R
new file mode 100644
index 0000000..5b39267
--- /dev/null
+++ b/inst/doc/biomformat.R
@@ -0,0 +1,61 @@
+## ----packages------------------------------------------------------------
+library("biomformat"); packageVersion("biomformat")
+
+## ----read-biom-examples--------------------------------------------------
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom",
+ package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom",
+ package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom",
+ package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom",
+ package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+x1
+
+## ----accessor-examples-table---------------------------------------------
+biom_data(x1)
+biom_data(x2)
+
+## ----matrix-coercion-----------------------------------------------------
+as(biom_data(x2), "matrix")
+
+## ----observ-meta---------------------------------------------------------
+observation_metadata(x1)
+observation_metadata(x2)
+observation_metadata(x3)
+observation_metadata(x4)[1:2, 1:3]
+class(observation_metadata(x4))
+
+## ----plot-examples-------------------------------------------------------
+sample_metadata(x1)
+sample_metadata(x2)
+sample_metadata(x3)
+sample_metadata(x4)[1:2, 1:3]
+class(sample_metadata(x4))
+
+## ----plot----------------------------------------------------------------
+plot(biom_data(x4))
+boxplot(as(biom_data(x4), "vector"))
+heatmap(as(biom_data(x4), "matrix"))
+
+## ----write-biom-examples-------------------------------------------------
+outfile = tempfile()
+write_biom(x4, outfile)
+y = read_biom(outfile)
+identical(x4, y)
+
+## ----compare-files-diff, eval=FALSE--------------------------------------
+# # On Unix OSes
+# system(paste0("diff ", rich_sparse_file, outfile))
+# # On windows
+# system(paste0("FC ", rich_sparse_file, outfile))
+
diff --git a/inst/doc/biomformat.Rmd b/inst/doc/biomformat.Rmd
new file mode 100644
index 0000000..d8cfbdb
--- /dev/null
+++ b/inst/doc/biomformat.Rmd
@@ -0,0 +1,151 @@
+---
+title: "The biomformat package vignette"
+author: "Paul J. McMurdie"
+output:
+ BiocStyle::html_document:
+ fig_height: 7
+ fig_width: 10
+ toc: yes
+ toc_depth: 2
+ number_sections: true
+vignette: >
+ %\VignetteIndexEntry{The biomformat package Vignette}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+`r library("knitr")`
+`r opts_chunk$set(cache=FALSE, fig.width=9, message=FALSE, warning=FALSE)`
+
+## Paul J. McMurdie & Joseph N. Paulson
+
+If you find *biomformat* and/or its tutorials useful,
+please acknowledge and cite *biomformat* in your publications:
+
+Paul J. McMurdie and Joseph N Paulson (2015). *biomformat: An interface package for the BIOM file format.* R/Bioconductor package version 1.0.0.
+
+
+## [phyloseq Home Page](https://github.com/joey711/biomformat/)
+
+phyloseq has many more utilities for interacting
+with this kind of data than are provided in this I/O-oriented package.
+
+
+## Motivation for the biomformat package
+
+This is an [R Markdown document](http://www.rstudio.com/ide/docs/r_markdown). Markdown is a simple formatting syntax for authoring web pages. Further details on [R markdown here](http://www.rstudio.com/ide/docs/r_markdown).
+
+The BIOM file format (canonically pronounced "biome") is designed to be a general-use format for representing biological sample by observation contingency tables. BIOM is a recognized standard for [the Earth Microbiome Project](http://www.earthmicrobiome.org/) and is a [Genomics Standards Consortium](http://gensc.org/) candidate project. Please see [the biom-format home page](http://biom-format.org/) for more details.
+
+This demo is designed to provide an overview of the biom package to get you started using it quickly. The biom package itself is intended to be a utility package that will be depended-upon by other packages in the future. It provides I/O functionality, and functions to make it easier to with data from biom-format files. It does not (and probably should not) provide statistical analysis functions. However, it does provide tools to access data from BIOM format files in ways that are extrem [...]
+
+**Package versions** at the time (`r date()`) of this build:
+
+```{r packages}
+library("biomformat"); packageVersion("biomformat")
+```
+
+
+# Read BIOM format
+
+Here is an example importing BIOM formats of different types into R using the `read_biom` function. The resulting data objects in R are given names beginning with `x`.
+
+```{r read-biom-examples}
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom",
+ package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom",
+ package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom",
+ package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom",
+ package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+x1
+```
+
+It would be hard to interpret and wasteful of RAM to stream all the data from a BIOM format file to the standard out when printed with `print` or `show` methods. Instead, a brief summary of the contents BIOM data is shown.
+
+
+# Access BIOM data
+
+To get access to the data in a familiar form appropriate for many standard R functions, we will need to use accessor functions, also included in the biom package.
+
+### Core observation data
+
+The core "observation" data is stored in either sparse or dense matrices in the BIOM format file, and sparse matrix support is carried through on the R side via [the Matrix package](http://cran.r-project.org/web/packages/Matrix/index.html). The variables `x1` and `x2`, assigned above from BIOM files, have similar (but not identical) data. They are small enough to observe directly as tables in standard output in an R session:
+
+```{r accessor-examples-table}
+biom_data(x1)
+biom_data(x2)
+```
+
+As you can see above, `x1` and `x2` are represented in R by slightly different matrix classes, assigned automatically based on the data. However, most operations in R will understand this automatically and you should not have to worry about the precise matrix class. However, if the R function you are attempting to use is having a problem with these fancier classes, you can easily coerce the data to the simple, standard `"matrix"` class using the `as` function:
+
+```{r matrix-coercion}
+as(biom_data(x2), "matrix")
+```
+
+### Observation Metadata
+
+Observation metadata is metadata associated with the individual units being counted/recorded in a sample, as opposed to measurements of properties of the samples themselves. For microbiome census data, for instance, observation metadata is often a taxonomic classification and anything else that might be known about a particular OTU/species. For other types of data, it might be metadata known about a particular genome, gene family, pathway, etc. In this case, the observations are counts o [...]
+
+```{r observ-meta}
+observation_metadata(x1)
+observation_metadata(x2)
+observation_metadata(x3)
+observation_metadata(x4)[1:2, 1:3]
+class(observation_metadata(x4))
+```
+
+### Sample Metadata
+
+Similarly, we can access metadata -- if available -- that describe properties of the samples. We access this sample metadata using the `sample_metadata` function.
+
+```{r plot-examples}
+sample_metadata(x1)
+sample_metadata(x2)
+sample_metadata(x3)
+sample_metadata(x4)[1:2, 1:3]
+class(sample_metadata(x4))
+```
+
+
+### Plots
+
+The data really is accessible to other R functions.
+
+```{r plot}
+plot(biom_data(x4))
+boxplot(as(biom_data(x4), "vector"))
+heatmap(as(biom_data(x4), "matrix"))
+```
+
+
+# Write BIOM format
+
+The biom objects in R can be written to a file/connection using the `write_biom` function. If you modified the biom object, this may still work as well, but no guarantees about this as we are still working on internal checks. The following example writes `x4` to a temporary file, then reads it back using `read_biom` and stores it as variable `y`. The exact comparison of these two objects using the `identical` function shows that they are exactly the same in R.
+```{r write-biom-examples}
+outfile = tempfile()
+write_biom(x4, outfile)
+y = read_biom(outfile)
+identical(x4, y)
+```
+
+Furthermore, it is possible to invoke standard operating system commands through the R `system` function -- in this case to invoke the `diff` command available on Unix-like systems or the `FC` command on Windows -- in order to compare the original and temporary files directly. Note that this is shown here for convenience, but not automatically run with the rest of the script because of the OS-dependence. During development, though, this same command is tested privately and no differences [...]
+
+```{r compare-files-diff, eval=FALSE}
+# On Unix OSes
+system(paste0("diff ", rich_sparse_file, outfile))
+# On windows
+system(paste0("FC ", rich_sparse_file, outfile))
+```
+
+
diff --git a/inst/doc/biomformat.html b/inst/doc/biomformat.html
new file mode 100644
index 0000000..0d5c559
--- /dev/null
+++ b/inst/doc/biomformat.html
@@ -0,0 +1,237 @@
+<!DOCTYPE html>
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+
+<meta charset="utf-8">
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="pandoc" />
+
+<meta name="author" content="Paul J. McMurdie" />
+
+
+<title>The biomformat package vignette</title>
+
+
+<style type="text/css">code{white-space: pre;}</style>
+<link href="data:text/css;charset=utf-8,pre%20%2Eoperator%2C%0Apre%20%2Eparen%20%7B%0Acolor%3A%20rgb%28104%2C%20118%2C%20135%29%0A%7D%0Apre%20%2Eliteral%20%7B%0Acolor%3A%20%23990073%0A%7D%0Apre%20%2Enumber%20%7B%0Acolor%3A%20%23099%3B%0A%7D%0Apre%20%2Ecomment%20%7B%0Acolor%3A%20%23998%3B%0Afont%2Dstyle%3A%20italic%0A%7D%0Apre%20%2Ekeyword%20%7B%0Acolor%3A%20%23900%3B%0Afont%2Dweight%3A%20bold%0A%7D%0Apre%20%2Eidentifier%20%7B%0Acolor%3A%20rgb%280%2C%200%2C%200%29%3B%0A%7D%0Apre%20%2Estri [...]
+<script src="data:application/x-javascript;base64,dmFyIGhsanM9bmV3IGZ1bmN0aW9uKCl7ZnVuY3Rpb24gbShwKXtyZXR1cm4gcC5yZXBsYWNlKC8mL2dtLCImYW1wOyIpLnJlcGxhY2UoLzwvZ20sIiZsdDsiKX1mdW5jdGlvbiBmKHIscSxwKXtyZXR1cm4gUmVnRXhwKHEsIm0iKyhyLmNJPyJpIjoiIikrKHA/ImciOiIiKSl9ZnVuY3Rpb24gYihyKXtmb3IodmFyIHA9MDtwPHIuY2hpbGROb2Rlcy5sZW5ndGg7cCsrKXt2YXIgcT1yLmNoaWxkTm9kZXNbcF07aWYocS5ub2RlTmFtZT09IkNPREUiKXtyZXR1cm4gcX1pZighKHEubm9kZVR5cGU9PTMmJnEubm9kZVZhbHVlLm1hdGNoKC9ccysvKSkpe2JyZWFrfX19ZnVuY3Rpb24gaCh0LH [...]
+<style type="text/css">
+ pre:not([class]) {
+ background-color: white;
+ }
+</style>
+<script type="text/javascript">
+if (window.hljs && document.readyState && document.readyState === "complete") {
+ window.setTimeout(function() {
+ hljs.initHighlighting();
+ }, 0);
+}
+</script>
+
+
+<link href="data:text/css;charset=utf-8,body%2C%20td%20%7B%0Afont%2Dfamily%3A%20sans%2Dserif%3B%0Abackground%2Dcolor%3A%20white%3B%0Afont%2Dsize%3A%2013px%3B%0A%7D%0Abody%20%7B%0Amax%2Dwidth%3A%20800px%3B%0Amargin%3A%200%20auto%3B%0Apadding%3A%201em%201em%202em%3B%0Aline%2Dheight%3A%2020px%3B%0A%7D%0A%0Adiv%23TOC%20li%20%7B%0Alist%2Dstyle%3Anone%3B%0Abackground%2Dimage%3Anone%3B%0Abackground%2Drepeat%3Anone%3B%0Abackground%2Dposition%3A0%3B%0A%7D%0A%0Ap%2C%20pre%20%7B%20margin%3A%200em%2 [...]
+
+<script type="text/javascript">
+document.addEventListener("DOMContentLoaded", function() {
+ var links = document.links;
+ for (var i = 0, linksLength = links.length; i < linksLength; i++)
+ if(links[i].hostname != window.location.hostname)
+ links[i].target = '_blank';
+});
+</script>
+
+</head>
+
+<body>
+
+
+<div id="header">
+<h1 class="title">The biomformat package vignette</h1>
+<h4 class="author"><em>Paul J. McMurdie</em></h4>
+</div>
+
+<h1>Contents</h1>
+<div id="TOC">
+<ul>
+<li><a href="#paul-j.-mcmurdie-joseph-n.-paulson"><span class="toc-section-number">0.1</span> Paul J. McMurdie & Joseph N. Paulson</a></li>
+<li><a href="#phyloseq-home-page"><span class="toc-section-number">0.2</span> <a href="https://github.com/joey711/biomformat/">phyloseq Home Page</a></a></li>
+<li><a href="#motivation-for-the-biomformat-package"><span class="toc-section-number">0.3</span> Motivation for the biomformat package</a></li>
+<li><a href="#read-biom-format"><span class="toc-section-number">1</span> Read BIOM format</a></li>
+<li><a href="#access-biom-data"><span class="toc-section-number">2</span> Access BIOM data</a></li>
+<li><a href="#write-biom-format"><span class="toc-section-number">3</span> Write BIOM format</a></li>
+</ul>
+</div>
+
+<div id="paul-j.-mcmurdie-joseph-n.-paulson" class="section level2">
+<h2><span class="header-section-number">0.1</span> Paul J. McMurdie & Joseph N. Paulson</h2>
+<p>If you find <em>biomformat</em> and/or its tutorials useful, please acknowledge and cite <em>biomformat</em> in your publications:</p>
+<p>Paul J. McMurdie and Joseph N Paulson (2015). <em>biomformat: An interface package for the BIOM file format.</em> R/Bioconductor package version 1.0.0.</p>
+</div>
+<div id="phyloseq-home-page" class="section level2">
+<h2><span class="header-section-number">0.2</span> <a href="https://github.com/joey711/biomformat/">phyloseq Home Page</a></h2>
+<p>phyloseq has many more utilities for interacting with this kind of data than are provided in this I/O-oriented package.</p>
+</div>
+<div id="motivation-for-the-biomformat-package" class="section level2">
+<h2><span class="header-section-number">0.3</span> Motivation for the biomformat package</h2>
+<p>This is an <a href="http://www.rstudio.com/ide/docs/r_markdown">R Markdown document</a>. Markdown is a simple formatting syntax for authoring web pages. Further details on <a href="http://www.rstudio.com/ide/docs/r_markdown">R markdown here</a>.</p>
+<p>The BIOM file format (canonically pronounced “biome”) is designed to be a general-use format for representing biological sample by observation contingency tables. BIOM is a recognized standard for <a href="http://www.earthmicrobiome.org/">the Earth Microbiome Project</a> and is a <a href="http://gensc.org/">Genomics Standards Consortium</a> candidate project. Please see <a href="http://biom-format.org/">the biom-format home page</a> for more details.</p>
+<p>This demo is designed to provide an overview of the biom package to get you started using it quickly. The biom package itself is intended to be a utility package that will be depended-upon by other packages in the future. It provides I/O functionality, and functions to make it easier to with data from biom-format files. It does not (and probably should not) provide statistical analysis functions. However, it does provide tools to access data from BIOM format files in ways that are ext [...]
+<p><strong>Package versions</strong> at the time (Mon Oct 17 20:07:58 2016) of this build:</p>
+<pre class="r"><code>library("biomformat"); packageVersion("biomformat")</code></pre>
+<pre><code>## [1] '1.2.0'</code></pre>
+</div>
+<div id="read-biom-format" class="section level1">
+<h1><span class="header-section-number">1</span> Read BIOM format</h1>
+<p>Here is an example importing BIOM formats of different types into R using the <code>read_biom</code> function. The resulting data objects in R are given names beginning with <code>x</code>.</p>
+<pre class="r"><code>min_dense_file = system.file("extdata", "min_dense_otu_table.biom",
+ package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom",
+ package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom",
+ package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom",
+ package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+x1</code></pre>
+<pre><code>## biom object.
+## type: OTU table
+## matrix_type: dense
+## 5 rows and 6 columns</code></pre>
+<p>It would be hard to interpret and wasteful of RAM to stream all the data from a BIOM format file to the standard out when printed with <code>print</code> or <code>show</code> methods. Instead, a brief summary of the contents BIOM data is shown.</p>
+</div>
+<div id="access-biom-data" class="section level1">
+<h1><span class="header-section-number">2</span> Access BIOM data</h1>
+<p>To get access to the data in a familiar form appropriate for many standard R functions, we will need to use accessor functions, also included in the biom package.</p>
+<div id="core-observation-data" class="section level3">
+<h3><span class="header-section-number">2.0.1</span> Core observation data</h3>
+<p>The core “observation” data is stored in either sparse or dense matrices in the BIOM format file, and sparse matrix support is carried through on the R side via <a href="http://cran.r-project.org/web/packages/Matrix/index.html">the Matrix package</a>. The variables <code>x1</code> and <code>x2</code>, assigned above from BIOM files, have similar (but not identical) data. They are small enough to observe directly as tables in standard output in an R session:</p>
+<pre class="r"><code>biom_data(x1)</code></pre>
+<pre><code>## 5 x 6 Matrix of class "dgeMatrix"
+## Sample1 Sample2 Sample3 Sample4 Sample5 Sample6
+## GG_OTU_1 0 0 1 0 0 0
+## GG_OTU_2 5 1 0 2 3 1
+## GG_OTU_3 0 0 1 4 2 0
+## GG_OTU_4 2 1 1 0 0 1
+## GG_OTU_5 0 1 1 0 0 0</code></pre>
+<pre class="r"><code>biom_data(x2)</code></pre>
+<pre><code>## 5 x 6 sparse Matrix of class "dgCMatrix"
+## Sample1 Sample2 Sample3 Sample4 Sample5 Sample6
+## GG_OTU_1 . . 1 . . .
+## GG_OTU_2 5 1 . 2 3 1
+## GG_OTU_3 . . 1 4 . 2
+## GG_OTU_4 2 1 1 . . 1
+## GG_OTU_5 . 1 1 . . .</code></pre>
+<p>As you can see above, <code>x1</code> and <code>x2</code> are represented in R by slightly different matrix classes, assigned automatically based on the data. However, most operations in R will understand this automatically and you should not have to worry about the precise matrix class. However, if the R function you are attempting to use is having a problem with these fancier classes, you can easily coerce the data to the simple, standard <code>"matrix"</code> class using [...]
+<pre class="r"><code>as(biom_data(x2), "matrix")</code></pre>
+<pre><code>## Sample1 Sample2 Sample3 Sample4 Sample5 Sample6
+## GG_OTU_1 0 0 1 0 0 0
+## GG_OTU_2 5 1 0 2 3 1
+## GG_OTU_3 0 0 1 4 0 2
+## GG_OTU_4 2 1 1 0 0 1
+## GG_OTU_5 0 1 1 0 0 0</code></pre>
+</div>
+<div id="observation-metadata" class="section level3">
+<h3><span class="header-section-number">2.0.2</span> Observation Metadata</h3>
+<p>Observation metadata is metadata associated with the individual units being counted/recorded in a sample, as opposed to measurements of properties of the samples themselves. For microbiome census data, for instance, observation metadata is often a taxonomic classification and anything else that might be known about a particular OTU/species. For other types of data, it might be metadata known about a particular genome, gene family, pathway, etc. In this case, the observations are count [...]
+<pre class="r"><code>observation_metadata(x1)</code></pre>
+<pre><code>## NULL</code></pre>
+<pre class="r"><code>observation_metadata(x2)</code></pre>
+<pre><code>## NULL</code></pre>
+<pre class="r"><code>observation_metadata(x3)</code></pre>
+<pre><code>## taxonomy1 taxonomy2 taxonomy3
+## GG_OTU_1 k__Bacteria p__Proteobacteria c__Gammaproteobacteria
+## GG_OTU_2 k__Bacteria p__Cyanobacteria c__Nostocophycideae
+## GG_OTU_3 k__Archaea p__Euryarchaeota c__Methanomicrobia
+## GG_OTU_4 k__Bacteria p__Firmicutes c__Clostridia
+## GG_OTU_5 k__Bacteria p__Proteobacteria c__Gammaproteobacteria
+## taxonomy4 taxonomy5 taxonomy6
+## GG_OTU_1 o__Enterobacteriales f__Enterobacteriaceae g__Escherichia
+## GG_OTU_2 o__Nostocales f__Nostocaceae g__Dolichospermum
+## GG_OTU_3 o__Methanosarcinales f__Methanosarcinaceae g__Methanosarcina
+## GG_OTU_4 o__Halanaerobiales f__Halanaerobiaceae g__Halanaerobium
+## GG_OTU_5 o__Enterobacteriales f__Enterobacteriaceae g__Escherichia
+## taxonomy7
+## GG_OTU_1 s__
+## GG_OTU_2 s__
+## GG_OTU_3 s__
+## GG_OTU_4 s__Halanaerobiumsaccharolyticum
+## GG_OTU_5 s__</code></pre>
+<pre class="r"><code>observation_metadata(x4)[1:2, 1:3]</code></pre>
+<pre><code>## taxonomy1 taxonomy2 taxonomy3
+## GG_OTU_1 k__Bacteria p__Proteobacteria c__Gammaproteobacteria
+## GG_OTU_2 k__Bacteria p__Cyanobacteria c__Nostocophycideae</code></pre>
+<pre class="r"><code>class(observation_metadata(x4))</code></pre>
+<pre><code>## [1] "data.frame"</code></pre>
+</div>
+<div id="sample-metadata" class="section level3">
+<h3><span class="header-section-number">2.0.3</span> Sample Metadata</h3>
+<p>Similarly, we can access metadata – if available – that describe properties of the samples. We access this sample metadata using the <code>sample_metadata</code> function.</p>
+<pre class="r"><code>sample_metadata(x1)</code></pre>
+<pre><code>## NULL</code></pre>
+<pre class="r"><code>sample_metadata(x2)</code></pre>
+<pre><code>## NULL</code></pre>
+<pre class="r"><code>sample_metadata(x3)</code></pre>
+<pre><code>## BarcodeSequence LinkerPrimerSequence BODY_SITE Description
+## Sample1 CGCTTATCGAGA CATGCTGCCTCCCGTAGGAGT gut human gut
+## Sample2 CATACCAGTAGC CATGCTGCCTCCCGTAGGAGT gut human gut
+## Sample3 CTCTCTACCTGT CATGCTGCCTCCCGTAGGAGT gut human gut
+## Sample4 CTCTCGGCCTGT CATGCTGCCTCCCGTAGGAGT skin human skin
+## Sample5 CTCTCTACCAAT CATGCTGCCTCCCGTAGGAGT skin human skin
+## Sample6 CTAACTACCAAT CATGCTGCCTCCCGTAGGAGT skin human skin</code></pre>
+<pre class="r"><code>sample_metadata(x4)[1:2, 1:3]</code></pre>
+<pre><code>## BarcodeSequence LinkerPrimerSequence BODY_SITE
+## Sample1 CGCTTATCGAGA CATGCTGCCTCCCGTAGGAGT gut
+## Sample2 CATACCAGTAGC CATGCTGCCTCCCGTAGGAGT gut</code></pre>
+<pre class="r"><code>class(sample_metadata(x4))</code></pre>
+<pre><code>## [1] "data.frame"</code></pre>
+</div>
+<div id="plots" class="section level3">
+<h3><span class="header-section-number">2.0.4</span> Plots</h3>
+<p>The data really is accessible to other R functions.</p>
+<pre class="r"><code>plot(biom_data(x4))</code></pre>
+<p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA2AAAAKgCAMAAADK0+6WAAADAFBMVEUAAAABAQECAgIDAwMEBAQFBQUGBgYHBwcICAgJCQkKCgoLCwsMDAwNDQ0ODg4PDw8QEBARERESEhITExMUFBQVFRUWFhYXFxcYGBgZGRkaGhobGxscHBwdHR0eHh4fHx8gICAhISEiIiIjIyMkJCQlJSUmJiYnJycoKCgpKSkqKiorKyssLCwtLS0uLi4vLy8wMDAxMTEyMjIzMzM0NDQ1NTU2NjY3Nzc4ODg5OTk6Ojo7Ozs8PDw9PT0+Pj4/Pz9AQEBBQUFCQkJDQ0NERERFRUVGRkZHR0dISEhJSUlKSkpLS0tMTExNTU1OTk5PT09QUFBRUVFSUlJTU1NUVFRVVVVWVlZXV1dYWFhZWVlaWlpbW1tcXFxdXV1eXl5fX19gYGBhYWFiYmJjY2NkZ [...]
+<pre class="r"><code>boxplot(as(biom_data(x4), "vector"))</code></pre>
+<p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA2AAAAKgCAMAAADK0+6WAAACslBMVEUAAAABAQECAgIDAwMEBAQFBQUGBgYHBwcICAgJCQkKCgoLCwsMDAwNDQ0ODg4PDw8QEBARERESEhITExMUFBQVFRUWFhYXFxcYGBgZGRkaGhobGxscHBwdHR0eHh4fHx8gICAiIiIjIyMkJCQlJSUmJiYnJycoKCgpKSkqKiorKyssLCwtLS0uLi4vLy8wMDAzMzM1NTU2NjY3Nzc4ODg6Ojo7Ozs8PDw9PT0/Pz9AQEBBQUFCQkJDQ0NERERGRkZHR0dJSUlKSkpMTExNTU1OTk5PT09QUFBRUVFSUlJTU1NUVFRVVVVWVlZXV1dYWFhZWVlaWlpbW1tcXFxeXl5fX19gYGBhYWFiYmJjY2NkZGRlZWVmZmZpaWlqampra2tsbGxtbW1ubm5wcHBxc [...]
+<pre class="r"><code>heatmap(as(biom_data(x4), "matrix"))</code></pre>
+<p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA2AAAAKgCAIAAAByb4nzAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAgAElEQVR4nOzdfVyV9f348c8lBw5yuBFRuRFNzHsRFOdIUxBNxaVlW0siN1rgmummFjOU5thUygc5pGVCW2tWm5pg25QcOrENRIsGePcVExBTE44yQW7i7nh+f5zfGB+0w+H2Ank9/9gjr3N9rut9bNmr65zrQjEajQIAAAD4r35qDwAAAICehUAEAACAhEAEAACARKP2AABaevHFF41Go1arVXuQHqGxsfHixYvjx49Xe5Ce4saNGwsXLnzyySfVHgTA/YxABHqcjz/+eO7cuW5ubmoP0iM0NjY6OTk5OzurPUhPkZ2dnZGRQSAC6FIEItDjODs7/+AHP3jooYfUHgQ9UWVlZf/+/dWeAsB9ju8gAgAAQEIgAgAAQEIgA [...]
+</div>
+</div>
+<div id="write-biom-format" class="section level1">
+<h1><span class="header-section-number">3</span> Write BIOM format</h1>
+<p>The biom objects in R can be written to a file/connection using the <code>write_biom</code> function. If you modified the biom object, this may still work as well, but no guarantees about this as we are still working on internal checks. The following example writes <code>x4</code> to a temporary file, then reads it back using <code>read_biom</code> and stores it as variable <code>y</code>. The exact comparison of these two objects using the <code>identical</code> function shows that t [...]
+<pre class="r"><code>outfile = tempfile()
+write_biom(x4, outfile)
+y = read_biom(outfile)
+identical(x4, y)</code></pre>
+<pre><code>## [1] FALSE</code></pre>
+<p>Furthermore, it is possible to invoke standard operating system commands through the R <code>system</code> function – in this case to invoke the <code>diff</code> command available on Unix-like systems or the <code>FC</code> command on Windows – in order to compare the original and temporary files directly. Note that this is shown here for convenience, but not automatically run with the rest of the script because of the OS-dependence. During development, though, this same command is t [...]
+<pre class="r"><code># On Unix OSes
+system(paste0("diff ", rich_sparse_file, outfile))
+# On windows
+system(paste0("FC ", rich_sparse_file, outfile))</code></pre>
+</div>
+
+
+
+<!-- dynamically load mathjax for compatibility with self-contained -->
+<script>
+ (function () {
+ var script = document.createElement("script");
+ script.type = "text/javascript";
+ script.src = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
+ document.getElementsByTagName("head")[0].appendChild(script);
+ })();
+</script>
+
+</body>
+</html>
diff --git a/inst/extdata/min_dense_otu_table.biom b/inst/extdata/min_dense_otu_table.biom
new file mode 100644
index 0000000..2baaf1a
--- /dev/null
+++ b/inst/extdata/min_dense_otu_table.biom
@@ -0,0 +1,32 @@
+ {
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":null},
+ {"id":"GG_OTU_2", "metadata":null},
+ {"id":"GG_OTU_3", "metadata":null},
+ {"id":"GG_OTU_4", "metadata":null},
+ {"id":"GG_OTU_5", "metadata":null}
+ ],
+ "columns": [
+ {"id":"Sample1", "metadata":null},
+ {"id":"Sample2", "metadata":null},
+ {"id":"Sample3", "metadata":null},
+ {"id":"Sample4", "metadata":null},
+ {"id":"Sample5", "metadata":null},
+ {"id":"Sample6", "metadata":null}
+ ],
+ "matrix_type": "dense",
+ "matrix_element_type": "int",
+ "shape": [5,6],
+ "data": [[0,0,1,0,0,0],
+ [5,1,0,2,3,1],
+ [0,0,1,4,2,0],
+ [2,1,1,0,0,1],
+ [0,1,1,0,0,0]]
+ }
+
diff --git a/inst/extdata/min_sparse_otu_table.biom b/inst/extdata/min_sparse_otu_table.biom
new file mode 100644
index 0000000..d84e039
--- /dev/null
+++ b/inst/extdata/min_sparse_otu_table.biom
@@ -0,0 +1,43 @@
+ {
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":null},
+ {"id":"GG_OTU_2", "metadata":null},
+ {"id":"GG_OTU_3", "metadata":null},
+ {"id":"GG_OTU_4", "metadata":null},
+ {"id":"GG_OTU_5", "metadata":null}
+ ],
+ "columns": [
+ {"id":"Sample1", "metadata":null},
+ {"id":"Sample2", "metadata":null},
+ {"id":"Sample3", "metadata":null},
+ {"id":"Sample4", "metadata":null},
+ {"id":"Sample5", "metadata":null},
+ {"id":"Sample6", "metadata":null}
+ ],
+ "matrix_type": "sparse",
+ "matrix_element_type": "int",
+ "shape": [5, 6],
+ "data":[[0,2,1],
+ [1,0,5],
+ [1,1,1],
+ [1,3,2],
+ [1,4,3],
+ [1,5,1],
+ [2,2,1],
+ [2,3,4],
+ [2,5,2],
+ [3,0,2],
+ [3,1,1],
+ [3,2,1],
+ [3,5,1],
+ [4,1,1],
+ [4,2,1]
+ ]
+ }
+
diff --git a/inst/extdata/min_sparse_otu_table_hdf5.biom b/inst/extdata/min_sparse_otu_table_hdf5.biom
new file mode 100644
index 0000000..b3c019b
Binary files /dev/null and b/inst/extdata/min_sparse_otu_table_hdf5.biom differ
diff --git a/inst/extdata/rich_dense_char.biom b/inst/extdata/rich_dense_char.biom
new file mode 100644
index 0000000..d632ac1
--- /dev/null
+++ b/inst/extdata/rich_dense_char.biom
@@ -0,0 +1,56 @@
+{
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}},
+ {"id":"GG_OTU_2", "metadata":{"taxonomy":["k__Bacteria", "p__Cyanobacteria", "c__Nostocophycideae", "o__Nostocales", "f__Nostocaceae", "g__Dolichospermum", "s__"]}},
+ {"id":"GG_OTU_3", "metadata":{"taxonomy":["k__Archaea", "p__Euryarchaeota", "c__Methanomicrobia", "o__Methanosarcinales", "f__Methanosarcinaceae", "g__Methanosarcina", "s__"]}},
+ {"id":"GG_OTU_4", "metadata":{"taxonomy":["k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Halanaerobiales", "f__Halanaerobiaceae", "g__Halanaerobium", "s__Halanaerobiumsaccharolyticum"]}},
+ {"id":"GG_OTU_5", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}}
+ ],
+ "columns":[
+ {"id":"Sample1", "metadata":{
+ "BarcodeSequence":"CGCTTATCGAGA",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample2", "metadata":{
+ "BarcodeSequence":"CATACCAGTAGC",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample3", "metadata":{
+ "BarcodeSequence":"CTCTCTACCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample4", "metadata":{
+ "BarcodeSequence":"CTCTCGGCCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample5", "metadata":{
+ "BarcodeSequence":"CTCTCTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample6", "metadata":{
+ "BarcodeSequence":"CTAACTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}}
+ ],
+ "matrix_type": "dense",
+ "matrix_element_type": "unicode",
+ "shape": [5,6],
+ "data": [["0","sky","1","0","clouds","0"],
+ ["5","1","0","2","3","1"],
+ ["0","lightning","1","4","2","0"],
+ ["2","1","1","0","gray","1"],
+ ["0","1","1","0","0","bottle"]]
+ }
+
diff --git a/inst/extdata/rich_dense_otu_table.biom b/inst/extdata/rich_dense_otu_table.biom
new file mode 100644
index 0000000..2cac771
--- /dev/null
+++ b/inst/extdata/rich_dense_otu_table.biom
@@ -0,0 +1,56 @@
+{
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}},
+ {"id":"GG_OTU_2", "metadata":{"taxonomy":["k__Bacteria", "p__Cyanobacteria", "c__Nostocophycideae", "o__Nostocales", "f__Nostocaceae", "g__Dolichospermum", "s__"]}},
+ {"id":"GG_OTU_3", "metadata":{"taxonomy":["k__Archaea", "p__Euryarchaeota", "c__Methanomicrobia", "o__Methanosarcinales", "f__Methanosarcinaceae", "g__Methanosarcina", "s__"]}},
+ {"id":"GG_OTU_4", "metadata":{"taxonomy":["k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Halanaerobiales", "f__Halanaerobiaceae", "g__Halanaerobium", "s__Halanaerobiumsaccharolyticum"]}},
+ {"id":"GG_OTU_5", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}}
+ ],
+ "columns":[
+ {"id":"Sample1", "metadata":{
+ "BarcodeSequence":"CGCTTATCGAGA",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample2", "metadata":{
+ "BarcodeSequence":"CATACCAGTAGC",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample3", "metadata":{
+ "BarcodeSequence":"CTCTCTACCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample4", "metadata":{
+ "BarcodeSequence":"CTCTCGGCCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample5", "metadata":{
+ "BarcodeSequence":"CTCTCTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample6", "metadata":{
+ "BarcodeSequence":"CTAACTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}}
+ ],
+ "matrix_type": "dense",
+ "matrix_element_type": "int",
+ "shape": [5,6],
+ "data": [[0,0,1,0,0,0],
+ [5,1,0,2,3,1],
+ [0,0,1,4,2,0],
+ [2,1,1,0,0,1],
+ [0,1,1,0,0,0]]
+ }
+
diff --git a/inst/extdata/rich_sparse_char.biom b/inst/extdata/rich_sparse_char.biom
new file mode 100644
index 0000000..8d8c04b
--- /dev/null
+++ b/inst/extdata/rich_sparse_char.biom
@@ -0,0 +1,66 @@
+{
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}},
+ {"id":"GG_OTU_2", "metadata":{"taxonomy":["k__Bacteria", "p__Cyanobacteria", "c__Nostocophycideae", "o__Nostocales", "f__Nostocaceae", "g__Dolichospermum", "s__"]}},
+ {"id":"GG_OTU_3", "metadata":{"taxonomy":["k__Archaea", "p__Euryarchaeota", "c__Methanomicrobia", "o__Methanosarcinales", "f__Methanosarcinaceae", "g__Methanosarcina", "s__"]}},
+ {"id":"GG_OTU_4", "metadata":{"taxonomy":["k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Halanaerobiales", "f__Halanaerobiaceae", "g__Halanaerobium", "s__Halanaerobiumsaccharolyticum"]}},
+ {"id":"GG_OTU_5", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}}
+ ],
+ "columns":[
+ {"id":"Sample1", "metadata":{
+ "BarcodeSequence":"CGCTTATCGAGA",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample2", "metadata":{
+ "BarcodeSequence":"CATACCAGTAGC",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample3", "metadata":{
+ "BarcodeSequence":"CTCTCTACCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample4", "metadata":{
+ "BarcodeSequence":"CTCTCGGCCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample5", "metadata":{
+ "BarcodeSequence":"CTCTCTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample6", "metadata":{
+ "BarcodeSequence":"CTAACTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}}
+ ],
+ "matrix_type": "sparse",
+ "matrix_element_type": "unicode",
+ "shape": [5, 6],
+ "data":[[0,2,"sky"],
+ [1,0,"clouds"],
+ [1,1,"lightning"],
+ [1,3,"gray"],
+ [1,4,"bottle"],
+ [1,5,"1"],
+ [2,2,"1"],
+ [2,3,"4"],
+ [2,5,"2"],
+ [3,0,"2"],
+ [3,1,"1"],
+ [3,2,"1"],
+ [3,5,"1"],
+ [4,1,"1"],
+ [4,2,"1"]
+ ]
+ }
diff --git a/inst/extdata/rich_sparse_otu_table.biom b/inst/extdata/rich_sparse_otu_table.biom
new file mode 100644
index 0000000..17d9e26
--- /dev/null
+++ b/inst/extdata/rich_sparse_otu_table.biom
@@ -0,0 +1,66 @@
+{
+ "id":null,
+ "format": "Biological Observation Matrix 1.0.0-dev",
+ "format_url": "http://biom-format.org",
+ "type": "OTU table",
+ "generated_by": "QIIME revision XYZ",
+ "date": "2011-12-19T19:00:00",
+ "rows":[
+ {"id":"GG_OTU_1", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}},
+ {"id":"GG_OTU_2", "metadata":{"taxonomy":["k__Bacteria", "p__Cyanobacteria", "c__Nostocophycideae", "o__Nostocales", "f__Nostocaceae", "g__Dolichospermum", "s__"]}},
+ {"id":"GG_OTU_3", "metadata":{"taxonomy":["k__Archaea", "p__Euryarchaeota", "c__Methanomicrobia", "o__Methanosarcinales", "f__Methanosarcinaceae", "g__Methanosarcina", "s__"]}},
+ {"id":"GG_OTU_4", "metadata":{"taxonomy":["k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Halanaerobiales", "f__Halanaerobiaceae", "g__Halanaerobium", "s__Halanaerobiumsaccharolyticum"]}},
+ {"id":"GG_OTU_5", "metadata":{"taxonomy":["k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria", "o__Enterobacteriales", "f__Enterobacteriaceae", "g__Escherichia", "s__"]}}
+ ],
+ "columns":[
+ {"id":"Sample1", "metadata":{
+ "BarcodeSequence":"CGCTTATCGAGA",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample2", "metadata":{
+ "BarcodeSequence":"CATACCAGTAGC",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample3", "metadata":{
+ "BarcodeSequence":"CTCTCTACCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"gut",
+ "Description":"human gut"}},
+ {"id":"Sample4", "metadata":{
+ "BarcodeSequence":"CTCTCGGCCTGT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample5", "metadata":{
+ "BarcodeSequence":"CTCTCTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}},
+ {"id":"Sample6", "metadata":{
+ "BarcodeSequence":"CTAACTACCAAT",
+ "LinkerPrimerSequence":"CATGCTGCCTCCCGTAGGAGT",
+ "BODY_SITE":"skin",
+ "Description":"human skin"}}
+ ],
+ "matrix_type": "sparse",
+ "matrix_element_type": "int",
+ "shape": [5, 6],
+ "data":[[0,2,1],
+ [1,0,5],
+ [1,1,1],
+ [1,3,2],
+ [1,4,3],
+ [1,5,1],
+ [2,2,1],
+ [2,3,4],
+ [2,5,2],
+ [3,0,2],
+ [3,1,1],
+ [3,2,1],
+ [3,5,1],
+ [4,1,1],
+ [4,2,1]
+ ]
+ }
diff --git a/inst/extdata/rich_sparse_otu_table_hdf5.biom b/inst/extdata/rich_sparse_otu_table_hdf5.biom
new file mode 100644
index 0000000..fe200fe
Binary files /dev/null and b/inst/extdata/rich_sparse_otu_table_hdf5.biom differ
diff --git a/man/biom-class.Rd b/man/biom-class.Rd
new file mode 100644
index 0000000..b2d168f
--- /dev/null
+++ b/man/biom-class.Rd
@@ -0,0 +1,51 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/allClasses.R
+\docType{class}
+\name{biom-class}
+\alias{biom-class}
+\title{The biom format data class.}
+\description{
+This class inherits from the \code{\link{list-class}},
+with validity checks specific to the definition to the biom-format.
+Effectively this means the list must have certain index names,
+some elements of which must have a specific structure or value.
+For further details see
+\href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+Importantly, this means other special properties of lists,
+like operations with \code{$} and single- or double-square-braces
+are also supported; as-is the \code{apply}-family function
+that can operate on lists.
+Note that some features of the biom-format can be essentially empty,
+represented by the string \code{"null"} in the file.
+These fields are returned as \code{\link{NULL}} when accessed
+by an accessor function.
+}
+\examples{
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+x = read_biom(biom_file)
+header(x)
+biom_shape(x)
+nrow(x)
+ncol(x)
+rownames(x)
+colnames(x)
+matrix_element_type(x)
+biom_data(x)
+observation_metadata(x)
+sample_metadata(x)
+}
+\seealso{
+The constructor, \code{\link{biom}}
+
+Accessor functions:
+
+\code{\link{header}},
+\code{\link{biom_shape}},
+\code{\link{nrow}},
+\code{\link{ncol}},
+\code{\link{matrix_element_type}},
+\code{\link{biom_data}},
+\code{\link{observation_metadata}},
+\code{\link{sample_metadata}}
+}
+
diff --git a/man/biom-methods.Rd b/man/biom-methods.Rd
new file mode 100644
index 0000000..093c387
--- /dev/null
+++ b/man/biom-methods.Rd
@@ -0,0 +1,73 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{biom}
+\alias{biom}
+\alias{biom,list-method}
+\title{Build and return an instance of the biom-class.}
+\usage{
+biom(x)
+
+\S4method{biom}{list}(x)
+}
+\arguments{
+\item{x}{(REQUIRED). A named list conforming to conventions arising from
+ the \code{\link{fromJSON}} function reading a biom-format file with
+ default settings. See \code{\link{read_biom}} for more details about
+ data import and
+ \code{\link{biom-class}} for more details about accessor functions
+ that extract R-friendly
+ subsets of the data and metadata stored in \code{x}.}
+}
+\value{
+An instance of the \code{\link{biom-class}}.
+}
+\description{
+This is for instantiating a biom object within R (\code{\link{biom-class}}),
+and assumes relevant data is already available in R.
+This is different than reading a biom file into R.
+If you are instead interested in importing a biom file into R,
+you should use the \code{\link{read_biom}} function.
+This function is made available (exported) so that
+advanced-users/developers
+can easily represent analogous data in this structure if needed.
+However, most users are expected to instead rely on the
+\code{\link{read_biom}} function for data import, followed by
+accessor functions that extract R-friendly
+subsets of the data stored in the biom-format derived list.
+}
+\details{
+\code{biom()} is a constructor method. This is the main method
+suggested for constructing an experiment-level (\code{\link{biom-class}})
+object from its component data.
+}
+\examples{
+#
+# import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+x = read_biom(biom_file)
+show(x)
+print(x)
+header(x)
+biom_data(x)
+biom_shape(x)
+nrow(x)
+ncol(x)
+observation_metadata(x)
+sample_metadata(x)
+}
+\seealso{
+Function to create a biom object from R data,
+\code{\link{make_biom}}.
+
+Definition of the
+\code{\link{biom-class}}.
+
+The \code{\link{read_biom}} import function.
+
+Function to write a biom format file from a biom object,
+\code{\link{write_biom}}
+
+Accessor functions like \code{\link{header}}.
+}
+
diff --git a/man/biom-package.Rd b/man/biom-package.Rd
new file mode 100644
index 0000000..65e03c1
--- /dev/null
+++ b/man/biom-package.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/allPackage.R
+\docType{package}
+\name{biom-package}
+\alias{biom-package}
+\title{This is an R package for interfacing with the biom format.}
+\description{
+This is an R package for interfacing with the biom-format.
+It includes basic utilities for reading and writing BIOM format using R,
+and native R methods for interacting with biom-data
+that maps to functionality in other languages
+that support biom-format, like python.
+}
+\author{
+Paul J. McMurdie II \email{mcmurdie at stanford.edu}
+}
+\references{
+\url{http://www.biom-format.org/}
+}
+\keyword{package}
+
diff --git a/man/biom_data-methods.Rd b/man/biom_data-methods.Rd
new file mode 100644
index 0000000..5a94f85
--- /dev/null
+++ b/man/biom_data-methods.Rd
@@ -0,0 +1,87 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{biom_data}
+\alias{biom_data}
+\alias{biom_data,biom,ANY,character-method}
+\alias{biom_data,biom,character,ANY-method}
+\alias{biom_data,biom,missing,missing-method}
+\alias{biom_data,biom,missing,numeric-method}
+\alias{biom_data,biom,numeric,missing-method}
+\alias{biom_data,biom,numeric,numeric-method}
+\title{Access main data observation matrix data from \code{\link{biom-class}}.}
+\usage{
+biom_data(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,missing,missing}(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,character,ANY}(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,ANY,character}(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,numeric,missing}(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,missing,numeric}(x, rows, columns, parallel = FALSE)
+
+\S4method{biom_data}{biom,numeric,numeric}(x, rows, columns, parallel = FALSE)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+
+\item{rows}{(Optional). The subset of row indices described in the
+returned object. For large datasets, specifying the row subset here,
+rather than after creating the whole matrix first,
+can improve speed/efficiency.
+Can be vector of index numbers (\code{\link{numeric-class}}) or
+index names (\code{\link{character-class}}).}
+
+\item{columns}{(Optional). The subset of column indices described in the
+returned object. For large datasets, specifying the column subset here,
+rather than after creating the whole matrix first,
+can improve speed/efficiency.
+Can be vector of index numbers (\code{\link{numeric-class}}) or
+index names (\code{\link{character-class}}).}
+
+\item{parallel}{(Optional). Logical. Whether to perform the accession parsing
+ using a parallel-computing backend supported by the \code{\link{plyr-package}}
+ via the \code{\link[foreach]{foreach-package}}. Note: At the moment, the header
+ accessor does not need nor does it support parallel-computed parsing.}
+}
+\value{
+A matrix containing the main observation data, with index names.
+ The type of data (numeric or character)
+ will depend on the results of \code{\link{matrix_element_type}(x)}.
+ The class of the matrix returned will depend on the sparsity of the data,
+ and whether it has numeric or character data.
+ For now, only numeric data can be stored in a \code{\link{Matrix-class}},
+ which will be stored sparsely, if possible.
+ Character data will be returned as a vanilla \code{\link{matrix-class}}.
+}
+\description{
+Retrieve and organize main data from \code{\link{biom-class}},
+represented as a matrix with index names.
+}
+\examples{
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+# Read the biom-format files
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+# Extract the data matrices
+biom_data(x1)
+biom_data(x2)
+biom_data(x3)
+biom_data(x4)
+biom_data(x5)
+biom_data(x6)
+}
+
diff --git a/man/biom_shape-methods.Rd b/man/biom_shape-methods.Rd
new file mode 100644
index 0000000..031415d
--- /dev/null
+++ b/man/biom_shape-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{biom_shape}
+\alias{biom_shape}
+\alias{biom_shape,biom-method}
+\title{The matrix dimensions
+of a \code{\link{biom-class}} object.}
+\usage{
+biom_shape(x)
+
+\S4method{biom_shape}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+A length two \code{\link{integer-class}} vector
+ indicating the \code{\link{nrow}} and \code{\link{ncol}}
+ of the main data matrix stored in \code{x}.
+}
+\description{
+The matrix dimensions
+of a \code{\link{biom-class}} object.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+biom_shape(x)
+}
+\seealso{
+\code{\link{biom-class}}
+}
+
diff --git a/man/colnames-methods.Rd b/man/colnames-methods.Rd
new file mode 100644
index 0000000..eb71745
--- /dev/null
+++ b/man/colnames-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{colnames,biom-method}
+\alias{colnames,biom-method}
+\title{Method extensions to \code{\link[base]{colnames}}
+for \code{\link{biom-class}} objects.}
+\usage{
+\S4method{colnames}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+The number of columns in \code{x}.
+ A length 1 \code{\link{integer-class}}.
+}
+\description{
+See the general documentation of \code{\link[base]{colnames}} method for
+expected behavior.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+colnames(x)
+}
+\seealso{
+\code{\link{nrow}}
+
+\code{\link[base]{colnames}}
+
+\code{\link{biom_shape}}
+}
+
diff --git a/man/header-methods.Rd b/man/header-methods.Rd
new file mode 100644
index 0000000..4136f6d
--- /dev/null
+++ b/man/header-methods.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{header}
+\alias{header}
+\alias{header,biom-method}
+\title{Extract the header from a \code{\link{biom-class}} object as a list.}
+\usage{
+header(x)
+
+\S4method{header}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+A list containing the header data.
+ That is, all the required elements that are not
+ the main data or index metadata.
+}
+\description{
+Extract the header from a \code{\link{biom-class}} object as a list.
+}
+\examples{
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+x = read_biom(biom_file)
+header(x)
+}
+
diff --git a/man/make_biom.Rd b/man/make_biom.Rd
new file mode 100644
index 0000000..059d9bf
--- /dev/null
+++ b/man/make_biom.Rd
@@ -0,0 +1,103 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\name{make_biom}
+\alias{make_biom}
+\title{Create a \code{\link{biom-class}}
+from \code{\link{matrix-class}}
+or \code{\link{data.frame}}.}
+\usage{
+make_biom(data, sample_metadata = NULL, observation_metadata = NULL,
+ id = NULL, matrix_element_type = "int")
+}
+\arguments{
+\item{data}{(Required).
+ \code{\link{matrix-class}} or \code{\link{data.frame}}.
+ A contingency table.
+ Observations / features / OTUs / species are rows,
+ samples / sites / libraries are columns.}
+
+\item{sample_metadata}{(Optional).
+ A \code{\link{matrix-class}} or \code{\link{data.frame}}
+ with the number of rows equal to the number of samples in \code{data}.
+ Sample covariates associated with the count data.
+ This should look like the table returned by
+ \code{\link{sample_metadata}} on a valid instance
+ of the \code{\link{biom-class}}.}
+
+\item{observation_metadata}{(Optional).
+ A \code{\link{matrix-class}} or \code{\link{data.frame}}
+ with the number of rows equal to the number of
+ features / species / OTUs / genes in \code{data}.
+ This should look like the table returned by
+ \code{\link{observation_metadata}} on a valid instance
+ of the \code{\link{biom-class}}.}
+
+\item{id}{(Optional). Character string. Identifier for the project.}
+
+\item{matrix_element_type}{(Optional). Character string. Either 'int' or 'float'}
+}
+\value{
+An object of \code{\link{biom-class}}.
+}
+\description{
+This function creates a valid instance of the \code{\link{biom-class}}
+from standard base-R objects like
+\code{\link{matrix-class}} or \code{\link{data.frame}}.
+This makes it possible to export any contingency table data
+represented in R to
+\href{http://biom-format.org/documentation/biom_format.html}{the biom-format},
+regardless of its source.
+The object returned by this function is appropriate for writing to
+a \code{.biom} file using the \code{\link{write_biom}} function.
+The sparse biom-format is not (yet) supported.
+}
+\details{
+The BIOM file format (canonically pronounced biome) is designed to be
+a general-use format for representing biological sample by observation
+contingency tables. BIOM is a recognized standard for the
+\href{http://www.earthmicrobiome.org/}{Earth Microbiome Project}
+and is a \href{http://gensc.org/}{Genomics Standards Consortium}
+candidate project. Please see
+\href{http://biom-format.org/}{the biom-format home page}
+for more details.
+}
+\examples{
+# import with default parameters, specify a file
+biomfile = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+x = read_biom(biomfile)
+data = biom_data(x)
+data
+smd = sample_metadata(x)
+smd
+omd = observation_metadata(x)
+omd
+# Make a new biom object from component data
+y = make_biom(data, smd, omd)
+# Won't be identical to x because of header info.
+identical(x, y)
+# The data components should be, though.
+identical(observation_metadata(x), observation_metadata(y))
+identical(sample_metadata(x), sample_metadata(y))
+identical(biom_data(x), biom_data(y))
+## Quickly show that writing and reading still identical.
+# Define a temporary directory to write .biom files
+tempdir = tempdir()
+write_biom(x, biom_file=file.path(tempdir, "x.biom"))
+write_biom(y, biom_file=file.path(tempdir, "y.biom"))
+x1 = read_biom(file.path(tempdir, "x.biom"))
+y1 = read_biom(file.path(tempdir, "y.biom"))
+identical(observation_metadata(x1), observation_metadata(y1))
+identical(sample_metadata(x1), sample_metadata(y1))
+identical(biom_data(x1), biom_data(y1))
+}
+\references{
+\url{http://biom-format.org/}
+}
+\seealso{
+\code{\link{write_biom}}
+
+\code{\link{biom-class}}
+
+\code{\link{read_biom}}
+}
+
diff --git a/man/matrix_element_type-methods.Rd b/man/matrix_element_type-methods.Rd
new file mode 100644
index 0000000..5715ee9
--- /dev/null
+++ b/man/matrix_element_type-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{matrix_element_type}
+\alias{matrix_element_type}
+\alias{matrix_element_type,biom-method}
+\title{Access class of data in the matrix elements
+of a \code{\link{biom-class}} object}
+\usage{
+matrix_element_type(x)
+
+\S4method{matrix_element_type}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+A \code{\link{character-class}} string indicating
+the class of the data stored in the main observation matrix of \code{x},
+with expected values \code{"int"}, \code{"float"}, \code{"unicode"}.
+}
+\description{
+Access class of data in the matrix elements
+of a \code{\link{biom-class}} object
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+matrix_element_type(x)
+}
+\seealso{
+\code{\link{biom-class}}
+}
+
diff --git a/man/ncol-methods.Rd b/man/ncol-methods.Rd
new file mode 100644
index 0000000..148b966
--- /dev/null
+++ b/man/ncol-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{ncol,biom-method}
+\alias{ncol,biom-method}
+\title{Method extensions to \code{\link[base]{ncol}}
+for \code{\link{biom-class}} objects.}
+\usage{
+\S4method{ncol}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+The number of columns in \code{x}.
+ A length 1 \code{\link{integer-class}}.
+}
+\description{
+See the general documentation of \code{\link[base]{ncol}} method for
+expected behavior.
+}
+\examples{
+# import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+ncol(x)
+}
+\seealso{
+\code{\link{nrow}}
+
+\code{\link[base]{ncol}}
+
+\code{\link{biom_shape}}
+}
+
diff --git a/man/nrow-methods.Rd b/man/nrow-methods.Rd
new file mode 100644
index 0000000..99ad450
--- /dev/null
+++ b/man/nrow-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{nrow,biom-method}
+\alias{nrow,biom-method}
+\title{Method extensions to \code{\link[base]{nrow}}
+for \code{\link{biom-class}} objects.}
+\usage{
+\S4method{nrow}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+The number of rows in \code{x}.
+ A length 1 \code{\link{integer-class}}.
+}
+\description{
+See the general documentation of \code{\link[base]{nrow}} method for
+expected behavior.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+nrow(x)
+}
+\seealso{
+\code{\link{ncol}}
+
+\code{\link[base]{nrow}}
+
+\code{\link{biom_shape}}
+}
+
diff --git a/man/observation_metadata-methods.Rd b/man/observation_metadata-methods.Rd
new file mode 100644
index 0000000..15f8b8d
--- /dev/null
+++ b/man/observation_metadata-methods.Rd
@@ -0,0 +1,70 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{observation_metadata}
+\alias{observation_metadata}
+\alias{observation_metadata,biom,character-method}
+\alias{observation_metadata,biom,missing-method}
+\alias{observation_metadata,biom,numeric-method}
+\title{Access observation (row) meta data from \code{\link{biom-class}}.}
+\usage{
+observation_metadata(x, rows, parallel = FALSE)
+
+\S4method{observation_metadata}{biom,missing}(x, rows, parallel = FALSE)
+
+\S4method{observation_metadata}{biom,character}(x, rows, parallel = FALSE)
+
+\S4method{observation_metadata}{biom,numeric}(x, rows, parallel = FALSE)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+
+\item{rows}{(Optional). The subset of row indices described in the
+ returned object. For large datasets, specifying the row subset here,
+ -- rather than first creating the complete data object --
+ can improve speed/efficiency.
+ This parameter can be vector of index numbers (\code{\link{numeric-class}}) or
+ index names (\code{\link{character-class}}).}
+
+\item{parallel}{(Optional). Logical. Whether to perform the accession parsing
+ using a parallel-computing backend supported by the \code{\link{plyr-package}}
+ via the \code{\link[foreach]{foreach-package}}.}
+}
+\value{
+A \code{\link{data.frame}} or \code{\link{list}} containing
+ the meta data, with index names. The precise form of the object returned
+ depends on the metadata stored in \code{x}. A \code{data.frame} is
+ created if possible.
+}
+\description{
+Retrieve and organize meta data from \code{\link{biom-class}},
+represented as a \code{\link{data.frame}} (if possible)
+or a list, with proper index names.
+}
+\examples{
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+# Read the biom-format files
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+# Extract metadata
+observation_metadata(x1)
+observation_metadata(x2)
+observation_metadata(x3)
+observation_metadata(x3, 2:4)
+observation_metadata(x3, 2)
+observation_metadata(x3, c("GG_OTU_3", "GG_OTU_4", "whoops"))
+observation_metadata(x4)
+observation_metadata(x5)
+observation_metadata(x6)
+}
+
diff --git a/man/read_biom.Rd b/man/read_biom.Rd
new file mode 100644
index 0000000..6c078be
--- /dev/null
+++ b/man/read_biom.Rd
@@ -0,0 +1,67 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/IO-methods.R
+\name{read_biom}
+\alias{read_biom}
+\title{Read a biom-format file, returning a \code{biom-class}.}
+\usage{
+read_biom(biom_file)
+}
+\arguments{
+\item{biom_file}{(Required). A character string indicating the
+ file location of the biom formatted file. This is a HDF5 or JSON formatted file
+ specific to biological datasets.
+ The format is formally defined at \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}
+ and depends on the versioning.}
+}
+\value{
+An instance of the \code{biom-class}.
+}
+\description{
+Import the data from a biom-format file into R, represented as an instance
+of the \code{\link{biom-class}}; essentially a \code{\link{list}} with
+special constraints that map to \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.
+}
+\details{
+The BIOM file format (canonically pronounced biome) is designed to be a general-use format for representing biological sample by observation contingency tables. BIOM is a recognized standard for the \href{http://www.earthmicrobiome.org/}{Earth Microbiome Project} and is a \href{http://gensc.org/}{Genomics Standards Consortium} candidate project. Please see \href{http://biom-format.org/}{the biom-format home page} for more details.
+
+It is tempting to include an argument identifying the
+biom-format version number of the data file being imported.
+However, the biom-format version number is a required
+field in the biom-format definition.
+Rather than duplicate this formal specification
+and allow the possibility of a conflict, the version
+number of the biom format will be referred to only by
+the "format" field in the biom formatted data,
+or its representation in R.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file <- system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+biom_file
+read_biom(biom_file)
+biom_file <- system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+biom_file
+read_biom(biom_file)
+## The previous examples use system.file() because of constraints in specifying a fixed
+## path within a reproducible example in a package.
+## In practice, however, you can simply provide "hard-link"
+## character string path to your file:
+# mybiomfile <- "path/to/my/biomfile.biom"
+# read_biom(mybiomfile)
+}
+\references{
+\url{http://biom-format.org/}
+}
+\seealso{
+Function to create a biom object from R data,
+\code{\link{make_biom}}.
+
+Definition of the
+\code{\link{biom-class}}.
+
+Function to write a biom format file from a biom object,
+\code{\link{write_biom}}
+
+Accessor functions like \code{\link{header}}.
+}
+
diff --git a/man/read_hdf5_biom.Rd b/man/read_hdf5_biom.Rd
new file mode 100644
index 0000000..5c06477
--- /dev/null
+++ b/man/read_hdf5_biom.Rd
@@ -0,0 +1,46 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/IO-methods.R
+\name{read_hdf5_biom}
+\alias{read_hdf5_biom}
+\title{Read in a biom-format vs 2 file, returning a \code{list}.}
+\usage{
+read_hdf5_biom(biom_file)
+}
+\arguments{
+\item{biom_file}{(Required). A biom object that is going to be written to file
+ as a proper biom formatted file, adhering to
+ \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.}
+}
+\value{
+Nothing. The first argument, \code{x}, is written to a file.
+}
+\description{
+This function is meant only to be used if the user knows the file is
+a particular version / hdf5 format. Otherwise, the `read_biom` file should be used.
+}
+\examples{
+biom_file <- system.file("extdata", "rich_sparse_otu_table_hdf5.biom", package = "biomformat")
+x = read_hdf5_biom(biom_file)
+x = biom(x)
+outfile = tempfile()
+write_biom(x, outfile)
+y = read_biom(outfile)
+identical(observation_metadata(x),observation_metadata(y))
+identical(sample_metadata(x),sample_metadata(y))
+identical(biom_data(x), biom_data(y))
+}
+\references{
+\url{http://biom-format.org/}
+}
+\seealso{
+Function to create a biom object from R data,
+\code{\link{make_biom}}.
+
+Definition of the
+\code{\link{biom-class}}.
+
+The \code{\link{read_hdf5_biom}} import function.
+
+Accessor functions like \code{\link{header}}.
+}
+
diff --git a/man/rownames-methods.Rd b/man/rownames-methods.Rd
new file mode 100644
index 0000000..da03500
--- /dev/null
+++ b/man/rownames-methods.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{rownames,biom-method}
+\alias{rownames,biom-method}
+\title{Method extensions to \code{\link[base]{rownames}}
+for \code{\link{biom-class}} objects.}
+\usage{
+\S4method{rownames}{biom}(x)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+}
+\value{
+The number of columns in \code{x}.
+ A length 1 \code{\link{integer-class}}.
+}
+\description{
+See the general documentation of \code{\link[base]{rownames}} method for
+expected behavior.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+rownames(x)
+}
+\seealso{
+\code{\link{nrow}}
+
+\code{\link[base]{rownames}}
+
+\code{\link{biom_shape}}
+}
+
diff --git a/man/sample_metadata-methods.Rd b/man/sample_metadata-methods.Rd
new file mode 100644
index 0000000..16e738c
--- /dev/null
+++ b/man/sample_metadata-methods.Rd
@@ -0,0 +1,68 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{sample_metadata}
+\alias{sample_metadata}
+\alias{sample_metadata,biom,character-method}
+\alias{sample_metadata,biom,missing-method}
+\alias{sample_metadata,biom,numeric-method}
+\title{Access meta data from \code{\link{biom-class}}.}
+\usage{
+sample_metadata(x, columns, parallel = FALSE)
+
+\S4method{sample_metadata}{biom,missing}(x, columns, parallel = FALSE)
+
+\S4method{sample_metadata}{biom,character}(x, columns, parallel = FALSE)
+
+\S4method{sample_metadata}{biom,numeric}(x, columns, parallel = FALSE)
+}
+\arguments{
+\item{x}{(Required). An instance of the \code{\link{biom-class}}.}
+
+\item{columns}{(Optional). The subset of column indices described in the
+ returned object. For large datasets, specifying the column subset here,
+ rather than after creating the whole matrix first,
+ can improve speed/efficiency.
+ Can be vector of index numbers (\code{\link{numeric-class}}) or
+ index names (\code{\link{character-class}}).}
+
+\item{parallel}{(Optional). Logical. Whether to perform the accession parsing
+ using a parallel-computing backend supported by the \code{\link{plyr-package}}
+ via the \code{\link[foreach]{foreach-package}}.}
+}
+\value{
+A \code{\link{data.frame}} or \code{\link{list}} containing
+ the meta data, with index names. The precise form of the object returned
+ depends on the metadata stored in \code{x}. A \code{data.frame} is
+ created if possible.
+}
+\description{
+Retrieve and organize meta data from \code{\link{biom-class}},
+represented as a \code{\link{data.frame}} (if possible, or a list)
+with proper index names.
+}
+\examples{
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+# Read the biom-format files
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+# Extract metadata
+sample_metadata(x1)
+sample_metadata(x2)
+sample_metadata(x3)
+sample_metadata(x3, 1:4)
+sample_metadata(x4)
+sample_metadata(x5)
+sample_metadata(x6)
+}
+
diff --git a/man/show-methods.Rd b/man/show-methods.Rd
new file mode 100644
index 0000000..6ca85d1
--- /dev/null
+++ b/man/show-methods.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/BIOM-class.R
+\docType{methods}
+\name{show,biom-method}
+\alias{show,biom-method}
+\title{Method extensions to show for biom objects.}
+\usage{
+\S4method{show}{biom}(object)
+}
+\arguments{
+\item{object}{biom-class object}
+}
+\description{
+See the general documentation of \code{\link[methods]{show}} method for
+expected behavior.
+}
+\examples{
+# # # import with default parameters, specify a file
+biom_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+(x = read_biom(biom_file) )
+show(x)
+}
+\seealso{
+\code{\link[methods]{show}}
+}
+
diff --git a/man/write_biom.Rd b/man/write_biom.Rd
new file mode 100644
index 0000000..7f49eae
--- /dev/null
+++ b/man/write_biom.Rd
@@ -0,0 +1,48 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/IO-methods.R
+\name{write_biom}
+\alias{write_biom}
+\title{Write a biom-format v1 file, returning a \code{biom-class}.}
+\usage{
+write_biom(x, biom_file)
+}
+\arguments{
+\item{x}{(Required). A biom object that is going to be written to file
+ as a proper biom formatted file, adhering to
+ \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}.}
+
+\item{biom_file}{(Required). A character string indicating the
+ file location of the biom formatted file. This is a JSON formatted file
+ specific to biological datasets.
+ The format is formally defined at
+ \href{http://biom-format.org/documentation/biom_format.html}{the biom-format definition}}
+}
+\value{
+Nothing. The first argument, \code{x}, is written to a file.
+}
+\description{
+Write a biom-format v1 file, returning a \code{biom-class}.
+}
+\examples{
+biom_file <- system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+x = read_biom(biom_file)
+outfile = tempfile()
+write_biom(x, outfile)
+y = read_biom(outfile)
+identical(x, y)
+}
+\references{
+\url{http://biom-format.org/}
+}
+\seealso{
+Function to create a biom object from R data,
+\code{\link{make_biom}}.
+
+Definition of the
+\code{\link{biom-class}}.
+
+The \code{\link{read_biom}} import function.
+
+Accessor functions like \code{\link{header}}.
+}
+
diff --git a/tests/testthat-biomformat.R b/tests/testthat-biomformat.R
new file mode 100644
index 0000000..92e0256
--- /dev/null
+++ b/tests/testthat-biomformat.R
@@ -0,0 +1,12 @@
+library("testthat")
+# As suggested for opt-out option on testing by users, recommended by CRAN
+# http://adv-r.had.co.nz/Testing.html
+# Previously, best practice was to put all test files in inst/tests and ensure that R CMD check ran them by putting the following code in tests/test-all.R:
+# library(testthat)
+# library(yourpackage)
+# test_package("yourpackage")
+# Now, recommended practice is to put your tests in tests/testthat, and ensure R CMD check runs them by putting the following code in tests/test-all.R:
+# library(testthat)
+# test_check("yourpackage")
+# The advantage of this new structure is that the user has control over whether or not tests are installed using the –install-tests parameter to R CMD install, or INSTALL_opts = c(“–install-tests”) argument to install.packages(). I’m not sure why you wouldn’t want to install the tests, but now you have the flexibility as requested by CRAN maintainers.
+test_check("biomformat")
\ No newline at end of file
diff --git a/tests/testthat/test-IO.R b/tests/testthat/test-IO.R
new file mode 100644
index 0000000..79d41ff
--- /dev/null
+++ b/tests/testthat/test-IO.R
@@ -0,0 +1,71 @@
+################################################################################
+# Use testthat to test file import and resulting class (and values)
+################################################################################
+library("biomformat"); library("testthat")
+packageVersion("biomformat")
+# # # # TESTS!
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+# Test read biom
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+
+
+
+# # # # TESTS!
+
+test_that("Classes are all biom", {
+ expect_is(x1, "biom")
+ expect_is(x2, "biom")
+ expect_is(x3, "biom")
+ expect_is(x4, "biom")
+ expect_is(x5, "biom")
+ expect_is(x6, "biom")
+})
+
+test_that("min/rich files have same biom_data", {
+ expect_that(biom_data(x2), is_identical_to(biom_data(x4)))
+ expect_that(biom_data(x1), is_identical_to(biom_data(x3)))
+})
+
+test_that("biom_datas can be manipulated mathematically", {
+ expect_that(2*biom_data(x2), is_identical_to(4*biom_data(x4)/2))
+ expect_that(2*biom_data(x1)-biom_data(x1), is_identical_to(biom_data(x3)))
+})
+
+test_that("empty stuff is NULL", {
+ expect_is(sample_metadata(x1), "NULL")
+ expect_is(sample_metadata(x1, 2:4), "NULL")
+ expect_is(observation_metadata(x1), "NULL")
+})
+
+test_that("Expected classes of non-empty components", {
+ expect_is(observation_metadata(x3), "data.frame")
+ expect_is(observation_metadata(x3, 2:4), "data.frame")
+ expect_is(observation_metadata(x3, 3), "data.frame")
+ expect_is(observation_metadata(x1), "NULL")
+ expect_that(sample_metadata(x3), is_a("data.frame"))
+ expect_that(biom_data(x3), is_a("Matrix"))
+ expect_that(header(x3), is_a("list"))
+})
+
+test_that("imported biom files are S4", {
+ expect_that(isS4(x1), is_true())
+ expect_that(isS4(x2), is_true())
+ expect_that(isS4(x3), is_true())
+ expect_that(isS4(x4), is_true())
+})
+
+test_that("show method output tests",{
+ expect_output(print(x1), "biom object. \ntype:")
+ expect_output(print(x4), "biom object. \ntype:")
+})
diff --git a/tests/testthat/test-accessors.R b/tests/testthat/test-accessors.R
new file mode 100644
index 0000000..d668ad9
--- /dev/null
+++ b/tests/testthat/test-accessors.R
@@ -0,0 +1,191 @@
+################################################################################
+# Use testthat to test data accessors
+################################################################################
+library("biomformat"); library("testthat")
+packageVersion("biomformat")
+# # # # TESTS!
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom", package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom", package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom", package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+min_sparse_hdf5 = system.file("extdata","min_sparse_otu_table_hdf5.biom",package = "biomformat")
+rich_sparse_hdf5 = system.file("extdata","rich_sparse_otu_table_hdf5.biom",package = "biomformat")
+
+
+# Test read biom
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+x7 = suppressWarnings(read_biom(min_sparse_hdf5))
+x8 = suppressWarnings(read_biom(rich_sparse_hdf5))
+
+
+# Test ncol, nrow, colnames, rownames
+test_that("Test that ncol, nrow, colnames, rownames, all work as expected", {
+ expect_equivalent(ncol(x1), 6L)
+ expect_equivalent(ncol(x2), 6L)
+ expect_equivalent(ncol(x3), 6L)
+ expect_equivalent(ncol(x4), 6L)
+ expect_equivalent(ncol(x5), 6L)
+ expect_equivalent(ncol(x6), 6L)
+ expect_equivalent(ncol(x7), 6L)
+ expect_equivalent(ncol(x8), 6L)
+
+ expect_equivalent(nrow(x1), 5L)
+ expect_equivalent(nrow(x2), 5L)
+ expect_equivalent(nrow(x3), 5L)
+ expect_equivalent(nrow(x4), 5L)
+ expect_equivalent(nrow(x5), 5L)
+ expect_equivalent(nrow(x6), 5L)
+ expect_equivalent(nrow(x7), 5L)
+ expect_equivalent(nrow(x8), 5L)
+
+ expect_equivalent(colnames(biom_data(x1)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x2)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x3)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x4)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x5)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x6)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x7)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+ expect_equivalent(colnames(biom_data(x8)), c("Sample1", "Sample2", "Sample3", "Sample4", "Sample5", "Sample6"))
+
+ expect_equivalent(rownames(biom_data(x1)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x2)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x3)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x4)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x5)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x6)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x7)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+ expect_equivalent(rownames(biom_data(x8)), c("GG_OTU_1", "GG_OTU_2", "GG_OTU_3", "GG_OTU_4", "GG_OTU_5"))
+
+})
+
+# Read tables
+T1 = biom_data(x1)
+T2 = biom_data(x2)
+T3 = biom_data(x3)
+T4 = biom_data(x4)
+T5 = biom_data(x5)
+T6 = biom_data(x6)
+T7 = biom_data(x7)
+T8 = biom_data(x8)
+
+# # # # TESTS!
+
+test_that("Test that the results of biom_data are matrix or dgeMatrix classes", {
+ expect_is(T1, "Matrix")
+ expect_is(T2, "Matrix")
+ expect_is(T3, "Matrix")
+ expect_is(T4, "Matrix")
+ expect_is(T5, "matrix")
+ expect_is(T6, "matrix")
+ expect_is(T7, "dgeMatrix")
+ expect_is(T8, "dgeMatrix")
+})
+
+test_that("Some arbitrary test values match expected", {
+ expect_equal(T1[5, 1], 0L)
+ expect_equal(T1[3, 4], 4L)
+ expect_equal(T2[3, 4], 4L)
+ expect_equal(T3[3, 4], 4L)
+ expect_equal(T4[3, 4], 4L)
+ expect_equal(T5[3, 4], "4")
+ expect_equal(T6[3, 4], "4")
+ expect_equal(T2[5, 1], 0L)
+ expect_equal(T3[4, 6], 1L)
+ expect_equal(T3[2, 3], 0L)
+ expect_equal(T4[4, 5], 0L)
+ expect_equal(T4[1, 3], 1L)
+ expect_equal(T5[1, 5], "clouds")
+ expect_equal(T5[5, 1], "0")
+ expect_equal(T5[3, 2], "lightning")
+ expect_equal(T6[3, 4], "4")
+ expect_equal(T6[2, 5], "bottle")
+ expect_equal(T6[4, 5], NA_character_)
+ expect_equal(T7[5, 1], 0L)
+ expect_equal(T7[3, 4], 4L)
+ expect_equal(T8[5, 1], 0L)
+ expect_equal(T8[3, 4], 4L)
+})
+
+
+test_that("Test pre-access biom_data subsetting", {
+ label = "multiple rows and multiple columns"
+ expect_equal(T1[1:3, 3:6], biom_data(x1, 1:3, 3:6), label=label)
+ expect_equal(T2[1:3, 3:6], biom_data(x2, 1:3, 3:6), label=label)
+ expect_equal(T3[1:3, 3:6], biom_data(x3, 1:3, 3:6), label=label)
+ expect_equal(T4[1:3, 3:6], biom_data(x4, 1:3, 3:6), label=label)
+ expect_equal(T5[1:3, 3:6], biom_data(x5, 1:3, 3:6), label=label)
+ expect_equal(T6[1:3, 3:6], biom_data(x6, 1:3, 3:6), label=label)
+ expect_equal(T7[1:3, 3:6], biom_data(x7, 1:3, 3:6), label=label)
+ expect_equal(T8[1:3, 3:6], biom_data(x8, 1:3, 3:6), label=label)
+
+ label = "single row and column (single value)"
+ expect_equivalent(T1[3, 4], biom_data(x1, 3, 4), label=label)
+ expect_equivalent(T2[3, 4], biom_data(x2, 3, 4), label=label)
+ expect_equivalent(T3[3, 4], biom_data(x3, 3, 4), label=label)
+ expect_equivalent(T4[3, 4], biom_data(x4, 3, 4), label=label)
+ expect_equivalent(T5[3, 4], biom_data(x5, 3, 4), label=label)
+ expect_equivalent(T6[3, 4], biom_data(x6, 3, 4), label=label)
+ expect_equivalent(T7[3, 4], biom_data(x7, 3, 4), label=label)
+ expect_equivalent(T8[3, 4], biom_data(x8, 3, 4), label=label)
+
+
+ label = "single rows and multiple cols"
+ expect_equal(T1[1, 3:6], biom_data(x1, 1, 3:6), label=label)
+ expect_equal(T2[1, 3:6], biom_data(x2, 1, 3:6), label=label)
+ expect_equal(T3[1, 3:6], biom_data(x3, 1, 3:6), label=label)
+ expect_equal(T4[1, 3:6], biom_data(x4, 1, 3:6), label=label)
+ expect_equal(T5[1, 3:6], biom_data(x5, 1, 3:6), label=label)
+ expect_equal(T6[1, 3:6], biom_data(x6, 1, 3:6), label=label)
+ expect_equal(T7[1, 3:6], biom_data(x7, 1, 3:6), label=label)
+ expect_equal(T8[1, 3:6], biom_data(x8, 1, 3:6), label=label)
+
+ label = "single column and multiple rows"
+ expect_equal(T1[2:5, 3], biom_data(x1, 2:5, 3), label=label)
+ expect_equal(T2[2:5, 3], biom_data(x2, 2:5, 3), label=label)
+ expect_equal(T3[2:5, 3], biom_data(x3, 2:5, 3), label=label)
+ expect_equal(T4[2:5, 3], biom_data(x4, 2:5, 3), label=label)
+ expect_equal(T5[2:5, 3], biom_data(x5, 2:5, 3), label=label)
+ expect_equal(T6[2:5, 3], biom_data(x6, 2:5, 3), label=label)
+ expect_equal(T7[2:5, 3], biom_data(x7, 2:5, 3), label=label)
+ expect_equal(T8[2:5, 3], biom_data(x8, 2:5, 3), label=label)
+})
+
+
+test_that("Test observation metadata extraction", {
+ expect_equal(as(observation_metadata(x3, 1)[1:3], "character"),
+ c("k__Bacteria", "p__Proteobacteria", "c__Gammaproteobacteria"))
+ expect_equal(as(observation_metadata(x3, 2)[3:5], "character"),
+ c("c__Nostocophycideae", "o__Nostocales", "f__Nostocaceae"))
+ expect_equal(as(observation_metadata(x4, 5)[4], "character"), "o__Enterobacteriales")
+})
+
+
+test_that("Test sample metadata extraction", {
+ expect_equal(sample_metadata(x3, 1)$Description, "human gut")
+ expect_equal(sample_metadata(x3, 2)$BODY_SITE, "gut")
+ expect_equal(sample_metadata(x3, 4)$BODY_SITE, "skin")
+ expect_equal(sample_metadata(x4, 4)$BODY_SITE, "skin")
+ expect_equal(sample_metadata(x8, 2)$BODY_SITE, "gut")
+ expect_equal(sample_metadata(x8, 4)$BODY_SITE, "skin")
+})
+
+
+test_that("Test metadata bad-index warnings", {
+ expect_warning(out<-sample_metadata(x3, 2:8))
+ label = "sample_metadata() output after corrected index has incorrect dimensions"
+ expect_equal(dim(out), c(5, 4), label=label)
+ expect_warning(out<-observation_metadata(x3, 2:8))
+ label = "observation_metadata() output after corrected index has incorrect dimensions"
+ expect_equal(dim(out), c(4, 7), label=label)
+ expect_warning(out<-observation_metadata(x3, 8:10))
+ expect_error(out<-observation_metadata(x3, c("non-id", "also-not-there")))
+ expect_error(out<-sample_metadata(x3, c("non-id", "also-not-there")))
+})
diff --git a/vignettes/biomformat.Rmd b/vignettes/biomformat.Rmd
new file mode 100644
index 0000000..d8cfbdb
--- /dev/null
+++ b/vignettes/biomformat.Rmd
@@ -0,0 +1,151 @@
+---
+title: "The biomformat package vignette"
+author: "Paul J. McMurdie"
+output:
+ BiocStyle::html_document:
+ fig_height: 7
+ fig_width: 10
+ toc: yes
+ toc_depth: 2
+ number_sections: true
+vignette: >
+ %\VignetteIndexEntry{The biomformat package Vignette}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+`r library("knitr")`
+`r opts_chunk$set(cache=FALSE, fig.width=9, message=FALSE, warning=FALSE)`
+
+## Paul J. McMurdie & Joseph N. Paulson
+
+If you find *biomformat* and/or its tutorials useful,
+please acknowledge and cite *biomformat* in your publications:
+
+Paul J. McMurdie and Joseph N Paulson (2015). *biomformat: An interface package for the BIOM file format.* R/Bioconductor package version 1.0.0.
+
+
+## [phyloseq Home Page](https://github.com/joey711/biomformat/)
+
+phyloseq has many more utilities for interacting
+with this kind of data than are provided in this I/O-oriented package.
+
+
+## Motivation for the biomformat package
+
+This is an [R Markdown document](http://www.rstudio.com/ide/docs/r_markdown). Markdown is a simple formatting syntax for authoring web pages. Further details on [R markdown here](http://www.rstudio.com/ide/docs/r_markdown).
+
+The BIOM file format (canonically pronounced "biome") is designed to be a general-use format for representing biological sample by observation contingency tables. BIOM is a recognized standard for [the Earth Microbiome Project](http://www.earthmicrobiome.org/) and is a [Genomics Standards Consortium](http://gensc.org/) candidate project. Please see [the biom-format home page](http://biom-format.org/) for more details.
+
+This demo is designed to provide an overview of the biom package to get you started using it quickly. The biom package itself is intended to be a utility package that will be depended-upon by other packages in the future. It provides I/O functionality, and functions to make it easier to with data from biom-format files. It does not (and probably should not) provide statistical analysis functions. However, it does provide tools to access data from BIOM format files in ways that are extrem [...]
+
+**Package versions** at the time (`r date()`) of this build:
+
+```{r packages}
+library("biomformat"); packageVersion("biomformat")
+```
+
+
+# Read BIOM format
+
+Here is an example importing BIOM formats of different types into R using the `read_biom` function. The resulting data objects in R are given names beginning with `x`.
+
+```{r read-biom-examples}
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom",
+ package = "biomformat")
+min_sparse_file = system.file("extdata", "min_sparse_otu_table.biom",
+ package = "biomformat")
+rich_dense_file = system.file("extdata", "rich_dense_otu_table.biom",
+ package = "biomformat")
+rich_sparse_file = system.file("extdata", "rich_sparse_otu_table.biom",
+ package = "biomformat")
+min_dense_file = system.file("extdata", "min_dense_otu_table.biom", package = "biomformat")
+rich_dense_char = system.file("extdata", "rich_dense_char.biom", package = "biomformat")
+rich_sparse_char = system.file("extdata", "rich_sparse_char.biom", package = "biomformat")
+x1 = read_biom(min_dense_file)
+x2 = read_biom(min_sparse_file)
+x3 = read_biom(rich_dense_file)
+x4 = read_biom(rich_sparse_file)
+x5 = read_biom(rich_dense_char)
+x6 = read_biom(rich_sparse_char)
+x1
+```
+
+It would be hard to interpret and wasteful of RAM to stream all the data from a BIOM format file to the standard out when printed with `print` or `show` methods. Instead, a brief summary of the contents BIOM data is shown.
+
+
+# Access BIOM data
+
+To get access to the data in a familiar form appropriate for many standard R functions, we will need to use accessor functions, also included in the biom package.
+
+### Core observation data
+
+The core "observation" data is stored in either sparse or dense matrices in the BIOM format file, and sparse matrix support is carried through on the R side via [the Matrix package](http://cran.r-project.org/web/packages/Matrix/index.html). The variables `x1` and `x2`, assigned above from BIOM files, have similar (but not identical) data. They are small enough to observe directly as tables in standard output in an R session:
+
+```{r accessor-examples-table}
+biom_data(x1)
+biom_data(x2)
+```
+
+As you can see above, `x1` and `x2` are represented in R by slightly different matrix classes, assigned automatically based on the data. However, most operations in R will understand this automatically and you should not have to worry about the precise matrix class. However, if the R function you are attempting to use is having a problem with these fancier classes, you can easily coerce the data to the simple, standard `"matrix"` class using the `as` function:
+
+```{r matrix-coercion}
+as(biom_data(x2), "matrix")
+```
+
+### Observation Metadata
+
+Observation metadata is metadata associated with the individual units being counted/recorded in a sample, as opposed to measurements of properties of the samples themselves. For microbiome census data, for instance, observation metadata is often a taxonomic classification and anything else that might be known about a particular OTU/species. For other types of data, it might be metadata known about a particular genome, gene family, pathway, etc. In this case, the observations are counts o [...]
+
+```{r observ-meta}
+observation_metadata(x1)
+observation_metadata(x2)
+observation_metadata(x3)
+observation_metadata(x4)[1:2, 1:3]
+class(observation_metadata(x4))
+```
+
+### Sample Metadata
+
+Similarly, we can access metadata -- if available -- that describe properties of the samples. We access this sample metadata using the `sample_metadata` function.
+
+```{r plot-examples}
+sample_metadata(x1)
+sample_metadata(x2)
+sample_metadata(x3)
+sample_metadata(x4)[1:2, 1:3]
+class(sample_metadata(x4))
+```
+
+
+### Plots
+
+The data really is accessible to other R functions.
+
+```{r plot}
+plot(biom_data(x4))
+boxplot(as(biom_data(x4), "vector"))
+heatmap(as(biom_data(x4), "matrix"))
+```
+
+
+# Write BIOM format
+
+The biom objects in R can be written to a file/connection using the `write_biom` function. If you modified the biom object, this may still work as well, but no guarantees about this as we are still working on internal checks. The following example writes `x4` to a temporary file, then reads it back using `read_biom` and stores it as variable `y`. The exact comparison of these two objects using the `identical` function shows that they are exactly the same in R.
+```{r write-biom-examples}
+outfile = tempfile()
+write_biom(x4, outfile)
+y = read_biom(outfile)
+identical(x4, y)
+```
+
+Furthermore, it is possible to invoke standard operating system commands through the R `system` function -- in this case to invoke the `diff` command available on Unix-like systems or the `FC` command on Windows -- in order to compare the original and temporary files directly. Note that this is shown here for convenience, but not automatically run with the rest of the script because of the OS-dependence. During development, though, this same command is tested privately and no differences [...]
+
+```{r compare-files-diff, eval=FALSE}
+# On Unix OSes
+system(paste0("diff ", rich_sparse_file, outfile))
+# On windows
+system(paste0("FC ", rich_sparse_file, outfile))
+```
+
+
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-bioc-biomformat.git
More information about the debian-med-commit
mailing list