.. _adding_metadata:

====================================================
Adding sample and observation metadata to biom files
====================================================

Frequently you'll have an existing BIOM file and want to add sample and/or observation metadata to it. For samples, metadata is frequently environmental or technical details about your samples: the subject that a sample was collected from, the pH of the sample, the PCR primers used to amplify DNA from the samples, etc. For observations, metadata is frequently a categorization of the observation: the taxonomy of an OTU, or the EC hierarchy of a gene. You can use the ``biom add-metadata`` command to add this information to an existing BIOM file.

To get help with ``add-metadata`` you can call::

	biom add-metadata -h

This command takes a BIOM file, and corresponding sample and/or observation mapping files. The following examples are used in the commands below. You can find these files in the ``biom-format/examples`` directory.

Your BIOM file might look like the following::

    {
        "id":null,
        "format": "Biological Observation Matrix 1.0.0-dev",
        "format_url": "http://biom-format.org",
        "type": "OTU table",
        "generated_by": "some software package",
        "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]
               ]
    }

A sample metadata mapping file could then look like the following. Notice that there is an extra sample in here with respect to the above BIOM table. Any samples in the mapping file that are not in the BIOM file are ignored.
::

	#SampleID	BarcodeSequence	DOB
	# Some optional
	# comment lines...
	Sample1	AGCACGAGCCTA	20060805
	Sample2	AACTCGTCGATG	20060216
	Sample3	ACAGACCACTCA	20060109
	Sample4	ACCAGCGACTAG	20070530
	Sample5	AGCAGCACTTGT	20070101
	Sample6	AGCAGCACAACT	20070716

An observation metadata mapping file might look like the following. Notice that there is an extra observation in here with respect to the above BIOM table. Any observations in the mapping file that are not in the BIOM file are ignored.
::

	#OTUID	taxonomy	confidence
	# Some optional
	# comment lines
	GG_OTU_0	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__	0.980
	GG_OTU_1	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	0.665
	GG_OTU_2	Root;k__Bacteria	0.980
	GG_OTU_3	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	1.000
	GG_OTU_4	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	0.842
	GG_OTU_5	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	1.000


Adding metadata
===============

To add sample metadata to a BIOM file, you can run the following::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_smd.biom --sample-metadata-fp sam_md.txt

To add observation metadata to a BIOM file, you can run the following::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_omd.biom --observation-metadata-fp obs_md.txt

You can also combine these in a single command to add both observation and sample metadata::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_md.biom --observation-metadata-fp obs_md.txt --sample-metadata-fp sam_md.txt

In the last case, the resulting BIOM file will look like the following::

	{
	    "columns": [
	        {
	            "id": "Sample1", 
	            "metadata": {
	                "BarcodeSequence": "AGCACGAGCCTA", 
	                "DOB": "20060805"
	            }
	        }, 
	        {
	            "id": "Sample2", 
	            "metadata": {
	                "BarcodeSequence": "AACTCGTCGATG", 
	                "DOB": "20060216"
	            }
	        }, 
	        {
	            "id": "Sample3", 
	            "metadata": {
	                "BarcodeSequence": "ACAGACCACTCA", 
	                "DOB": "20060109"
	            }
	        }, 
	        {
	            "id": "Sample4", 
	            "metadata": {
	                "BarcodeSequence": "ACCAGCGACTAG", 
	                "DOB": "20070530"
	            }
	        }, 
	        {
	            "id": "Sample5", 
	            "metadata": {
	                "BarcodeSequence": "AGCAGCACTTGT", 
	                "DOB": "20070101"
	            }
	        }, 
	        {
	            "id": "Sample6", 
	            "metadata": {
	                "BarcodeSequence": "AGCAGCACAACT", 
	                "DOB": "20070716"
	            }
	        }
	    ], 
	    "data": [
	        [0, 2, 1.0], 
	        [1, 0, 5.0], 
	        [1, 1, 1.0], 
	        [1, 3, 2.0], 
	        [1, 4, 3.0], 
	        [1, 5, 1.0], 
	        [2, 2, 1.0], 
	        [2, 3, 4.0], 
	        [2, 5, 2.0], 
	        [3, 0, 2.0], 
	        [3, 1, 1.0], 
	        [3, 2, 1.0], 
	        [3, 5, 1.0], 
	        [4, 1, 1.0], 
	        [4, 2, 1.0]
	    ], 
	    "date": "2012-12-11T07:36:15.467843", 
	    "format": "Biological Observation Matrix 1.0.0", 
	    "format_url": "http://biom-format.org", 
	    "generated_by": "some software package", 
	    "id": null, 
	    "matrix_element_type": "float", 
	    "matrix_type": "sparse", 
	    "rows": [
	        {
	            "id": "GG_OTU_1", 
	            "metadata": {
	                "confidence": "0.665", 
	                "taxonomy": "Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae"
	            }
	        }, 
	        {
	            "id": "GG_OTU_2", 
	            "metadata": {
	                "confidence": "0.980", 
	                "taxonomy": "Root;k__Bacteria"
	            }
	        }, 
	        {
	            "id": "GG_OTU_3", 
	            "metadata": {
	                "confidence": "1.000", 
	                "taxonomy": "Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae"
	            }
	        }, 
	        {
	            "id": "GG_OTU_4", 
	            "metadata": {
	                "confidence": "0.842", 
	                "taxonomy": "Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae"
	            }
	        }, 
	        {
	            "id": "GG_OTU_5", 
	            "metadata": {
	                "confidence": "1.000", 
	                "taxonomy": "Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae"
	            }
	        }
	    ], 
	    "shape": [5, 6], 
	    "type": "OTU table"
	}


Processing metadata while adding
================================

There are some additional parameters you can pass to this command for more complex processing. 

You can tell the command to process certain metadata column values as integers (``--int-fields``), floating point (i.e., decimal or real) numbers (``--float-fields``), or as hierarchical semicolon-delimited data (``--sc-separated``).

::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_md.biom --observation-metadata-fp obs_md.txt --sample-metadata-fp sam_md.txt --int-fields DOB --sc-separated taxonomy --float-fields confidence

Here your resulting BIOM file will look like the following, where ``DOB`` values are now integers (compare to the above: they're not quoted now), ``confidence`` values are now floating point numbers (again, not quoted now), and ``taxonomy`` values are now lists where each entry is a taxonomy level, opposed to above where they appear as a single semi-colon-separated string.
::

	{
	    "columns": [
	        {
	            "id": "Sample1", 
	            "metadata": {
	                "BarcodeSequence": "AGCACGAGCCTA", 
	                "DOB": 20060805
	            }
	        }, 
	        {
	            "id": "Sample2", 
	            "metadata": {
	                "BarcodeSequence": "AACTCGTCGATG", 
	                "DOB": 20060216
	            }
	        }, 
	        {
	            "id": "Sample3", 
	            "metadata": {
	                "BarcodeSequence": "ACAGACCACTCA", 
	                "DOB": 20060109
	            }
	        }, 
	        {
	            "id": "Sample4", 
	            "metadata": {
	                "BarcodeSequence": "ACCAGCGACTAG", 
	                "DOB": 20070530
	            }
	        }, 
	        {
	            "id": "Sample5", 
	            "metadata": {
	                "BarcodeSequence": "AGCAGCACTTGT", 
	                "DOB": 20070101
	            }
	        }, 
	        {
	            "id": "Sample6", 
	            "metadata": {
	                "BarcodeSequence": "AGCAGCACAACT", 
	                "DOB": 20070716
	            }
	        }
	    ], 
	    "data": [
	        [0, 2, 1.0], 
	        [1, 0, 5.0], 
	        [1, 1, 1.0], 
	        [1, 3, 2.0], 
	        [1, 4, 3.0], 
	        [1, 5, 1.0], 
	        [2, 2, 1.0], 
	        [2, 3, 4.0], 
	        [2, 5, 2.0], 
	        [3, 0, 2.0], 
	        [3, 1, 1.0], 
	        [3, 2, 1.0], 
	        [3, 5, 1.0], 
	        [4, 1, 1.0], 
	        [4, 2, 1.0]
	    ], 
	    "date": "2012-12-11T07:30:29.870689", 
	    "format": "Biological Observation Matrix 1.0.0", 
	    "format_url": "http://biom-format.org", 
	    "generated_by": "some software package", 
	    "id": null, 
	    "matrix_element_type": "float", 
	    "matrix_type": "sparse", 
	    "rows": [
	        {
	            "id": "GG_OTU_1", 
	            "metadata": {
	                "confidence": 0.665, 
	                "taxonomy": ["Root", "k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Clostridiales", "f__Lachnospiraceae"]
	            }
	        }, 
	        {
	            "id": "GG_OTU_2", 
	            "metadata": {
	                "confidence": 0.98, 
	                "taxonomy": ["Root", "k__Bacteria"]
	            }
	        }, 
	        {
	            "id": "GG_OTU_3", 
	            "metadata": {
	                "confidence": 1.0, 
	                "taxonomy": ["Root", "k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Clostridiales", "f__Lachnospiraceae"]
	            }
	        }, 
	        {
	            "id": "GG_OTU_4", 
	            "metadata": {
	                "confidence": 0.842, 
	                "taxonomy": ["Root", "k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Clostridiales", "f__Lachnospiraceae"]
	            }
	        }, 
	        {
	            "id": "GG_OTU_5", 
	            "metadata": {
	                "confidence": 1.0, 
	                "taxonomy": ["Root", "k__Bacteria", "p__Firmicutes", "c__Clostridia", "o__Clostridiales", "f__Lachnospiraceae"]
	            }
	        }
	    ], 
	    "shape": [5, 6], 
	    "type": "OTU table"
	}

If you have multiple fields that you'd like processed in one of these ways, you can pass a comma-separated list of field names (e.g., ``--float-fields confidence,pH``).

Renaming (or naming) metadata columns while adding
==================================================

You can also override the names of the metadata fields provided in the mapping files with the ``--observation-header`` and ``--sample-header`` parameters. This is useful if you want to rename metadata columns, or if metadata column headers aren't present in your metadata mapping file. If you pass either of these parameters, you must name all columns in order. If there are more columns in the metadata mapping file then there are headers, extra columns will be ignored (so this is also a useful way to select only the first n columns from your mapping file). For example, if you want to rename the ``DOB`` column in the sample metadata mapping you could do the following::
	
	biom add-metadata -i min_sparse_otu_table.biom -o table.w_smd.biom --sample-metadata-fp sam_md.txt --sample-header SampleID,BarcodeSequence,DateOfBirth

If you have a mapping file without headers such as the following::

	GG_OTU_0	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__	0.980
	GG_OTU_1	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	0.665
	GG_OTU_2	Root;k__Bacteria	0.980
	GG_OTU_3	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	1.000
	GG_OTU_4	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	0.842
	GG_OTU_5	Root;k__Bacteria;p__Firmicutes;c__Clostridia;o__Clostridiales;f__Lachnospiraceae	1.000

you could name these while adding them as follows::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_omd.biom --observation-metadata-fp obs_md.txt --observation-header OTUID,taxonomy,confidence

As a variation on the last command, if you only want to include the ``taxonomy`` column and exclude the ``confidence`` column, you could run::

	biom add-metadata -i min_sparse_otu_table.biom -o table.w_omd.biom --observation-metadata-fp obs_md.txt --observation-header OTUID,taxonomy

