qiime/qiime — pull request #1070 by jrrideout (2013-07-24 18:36:15+00:00)
Title: Support for one-to-many metadata relationship (issue #998)

**Please do not merge this pull request yet. It will fail the automated tests because it relies on changes in this [biom-format pull request](https://github.com/biom-format/biom-format/pull/150). There will need to be a new biom-format release before this pull request can be merged.**

This pull request fixes #998 by adding partial support for one-to-many metadata relationships. Includes the following changes:

Extensive refactoring of summarize_taxa.py to use the biom-format API.

summarize_taxa.py's ```-l```/```-u``` options are now supported together (previously only one could be invoked at a time). These options previously filtered out taxa that didn't meet the specified threshold *after* relative abundance was calculated, which could result in a relative abundance table that didn't have abundances adding up to exactly 1.0 (100%). These options now perform the filtering on the absolute abundance input table *before* converting to relative abundances.

Added partial support for one-to-many relationships between observations (e.g., OTUs) and metadata (e.g., taxonomy). map_reads_to_reference.py/parallel_map_reads_to_reference.py now include multiple metadata entries (e.g., pathways) in the BIOM table as a nested structure (a list of lists of strings). summarize_taxa.py provides various ways of handling this one-to-many metadata via the new option ```-M```/```--one_to_many```.

All other scripts that operate on a BIOM table's metadata will ignore any metadata entry but the first one. The affected scripts have had their documentation updated to explain this. Tables containing one-to-one relationships (previously the only type generated by QIIME) and one-to-many relationships will both work with QIIME.