make_2d_plots.py – Make 2D PCoA Plots

Description:

This script generates 2D PCoA plots using the principal coordinates file generated by performing beta diversity measures of an OTU table.

Usage: make_2d_plots.py [options]

Input Arguments:

Note

[REQUIRED]

-i, --coord_fname

Input principal coordinates filepath (i.e., resulting file from principal_coordinates.py). Alternatively, a directory containing multiple principal coordinates files for jackknifed PCoA results.

-m, --map_fname

Input metadata mapping filepath

[OPTIONAL]

-b, --colorby

Comma-separated list categories metadata categories (column headers) to color by in the plots. The categories must match the name of a column header in the mapping file exactly. Multiple categories can be list by comma separating them without spaces. The user can also combine columns in the mapping file by separating the categories by “&&” without spaces. [default=color by all]

-p, --prefs_path

Input user-generated preferences filepath. NOTE: This is a file with a dictionary containing preferences for the analysis. [default: None]

-k, --background_color

Background color to use in the plots. [default: white]

--ellipsoid_opacity

Used only when plotting ellipsoids for jackknifed beta diversity (i.e. using a directory of coord files instead of a single coord file). The valid range is between 0-1. 0 produces completely transparent (invisible) ellipsoids and 1 produces completely opaque ellipsoids. [default=0.33]

--ellipsoid_method

Used only when plotting ellipsoids for jackknifed beta diversity (i.e. using a directory of coord files instead of a single coord file). Valid values are “IQR” and “sdev”. [default=IQR]

--master_pcoa

Used only when plotting ellipsoids for jackknifed beta diversity (i.e. using a directory of coord files instead of a single coord file). These coordinates will be the center of each ellipisoid. [default: None; arbitrarily chosen PC matrix will define the center point]

--scree

Generate the scree plot [default: False]

--pct_variation_below_one

Allow the percent variation explained by the axes to be below one. The default behaivor is to multiply by 100 all values if PC1 is < 1.0 [default: False]

-o, --output_dir

Path to the output directory

Output:

This script generates an output folder, which contains several files. To best view the 2D plots, it is recommended that the user views the _pcoa_2D.html file.

Default Example:

If you just want to use the default output, you can supply the principal coordinates file (i.e., resulting file from principal_coordinates.py), where the default coloring will be based on the SampleID as follows:

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt

Output Directory Usage:

If you want to give an specific output directory (e.g. “2d_plots”), use the following code.

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -o 2d_plots/

Mapping File Usage:

Additionally, the user can supply their mapping file (‘-m’) and a specific category to color by (‘-b’) or any combination of categories. When using the -b option, the user can specify the coloring for multiple mapping labels, where each mapping label is separated by a comma, for example: -b ‘mapping_column1,mapping_column2’. The user can also combine mapping labels and color by the combined label that is created by inserting an ‘&&’ between the input columns, for example: -b ‘mapping_column1&&mapping_column2’.If the user wants to color by specific mapping labels, they can use the following code:

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -b 'Treatment'

Scree plot Usage:

A scree plot can tell you how many axes are likely to be important and help determine how many ‘real’ underlying gradients there might be in your data as well as their relative ‘strength’. If you want to generate a scree plot, use the following code.

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt --scree

Color by all categories:

If the user would like to color all categories in their metadata mapping file, they should not pass -b. Color by all is the default behavior.

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt

Prefs File:

The user can supply a prefs file to color by, as follows:

make_2d_plots.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -p prefs.txt

Jackknifed Principal Coordinates (w/ confidence intervals):

If you have created jackknifed PCoA files, you can pass the folder containing those files, instead of a single file. The user can also specify the opacity of the ellipses around each point ‘–ellipsoid_opacity’, which is a value from 0-1. Currently there are two metrics ‘–ellipsoid_method’ that can be used for generating the ellipsoids, which are ‘IQR’ and ‘sdev’. The user can specify all of these options as follows:

make_2d_plots.py -i pcoa/ -m Fasting_Map.txt -b 'Treatment&&DOB' --ellipsoid_opacity=0.5 --ellipsoid_method=IQR