PCoA_bubble.py
===============

Create a series of Principle Coordinate plots for each OTU in an input list
where the plot points are varied in size by the relative abundance of the OTU
(relative to either Sample or the total contribution of the OTU to the data
set.

.. code-block:: bash

    usage: PCoA_bubble.py [-h] -i OTU_TABLE -u UNIFRAC -d NAMES_COLORS_IDS_FN -m MAPPING -c MAP_CATEGORY [-o OUTPUT_DIR] [--scaling_factor SCALING_FACTOR] [-v]

Required Arguments
-------------------

.. cmdoption:: -i OTU_TABLE, --otu_table OTU_TABLE

    The biom-format file with OTU-Sample abundance data.

.. cmdoption:: -u UNIFRAC, --unifrac UNIFRAC

    Principle coordinates analysis file. Eg. unweighted_unifrac_pc.txt

.. cmdoption:: -d NAMES_COLORS_IDS_FN, --names_colors_ids_fn NAMES_COLORS_IDS_FN

    The name of an input data file containing three items:
    Line 1: a tab-separated list of display names for the different types in
    the specified mapping category (--mapping_category), Line 2: a matching
    tab-separated list of hexadecimal colors for each of the category types,
    Lines 3-end: a tab-separated pair specifying OTU ID and OTU Name. Each
    entry will get a separate PCoA plot under a file with the name of the OTU.

.. cmdoption:: -m MAPPING, --mapping MAPPING

    The mapping file specifying group information for each sample.

.. cmdoption:: -c MAP_CATEGORY, --map_category MAP_CATEGORY

    Any mapping category, such as treatment type, that will be used to group
    the data in the output plots. For example, one category with three types
    will result in three different point sets in the final output.

Optional Arguments
------------------

.. cmdoption:: -o OUTPUT_DIR, --output_dir OUTPUT_DIR

    The directory to output the PCoA plots to.

.. cmdoption:: --scaling_factor SCALING_FACTOR

    Species relative abundance is multiplied by this factor in order to make
    appropriate visible bubbles in the output plots. Default is 10000.

.. cmdoption:: -v, --verbose

    Displays species name as each is being plotted and stored to disk.

.. cmdoption:: -h, --help

    Show this help message and exit

Example plot
--------------

PCoA bubble plots of subgingival microbiome pathogens of smokers [1]_.

.. image:: PCoA/PCoA_bubble_example_smokers_pathogens.png
   :scale: 50%
   :align: center

Citation:

.. [1] **The Subgingival Microbiome of Clinically Healthy Current and Never Smokers**. Matthew R Mason, Philip M Preshaw, Haikady N Nagaraja, Shareef M Dabdoub, Anis Rahman and Purnima S Kumar; doi: `10.1038/ismej.2014.114 <http://dx.doi.org/10.1038/ismej.2014.114>`_