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

This is the path to the principal coordinates file (i.e., resulting file from principal_coordinates.py). Alternatively, the user can supply a directory containing multiple principal coordinates files.

-m, --map_fname

This is the metadata mapping file [default=None]

[OPTIONAL]

-b, --colorby

This is the categories to color by in the plots from the user-generated mapping file. The categories must match the name of a column header in the mapping file exactly and 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=None]

-p, --prefs_path

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

-k, --background_color

This is the background color to use in the plots. [default: None]

--ellipsoid_opacity

Used when plotting ellipsoids for a summary plot (i.e. using a directory of coord files instead of a single coordfile). Valid range is 0-1. A value of 0 produces completely transparent (invisible) ellipsoids. A value of 1 produces completely opaque ellipsoids.

--ellipsoid_method

Used when plotting ellipsoids for a summary plot (i.e. using a directory of coord files instead of a single coord file). Valid values are “IQR” and “sdev”.

--master_pcoa

If performing averaging on multiple coord files, the other coord files will be aligned to this one through procrustes analysis. This master file will not be included in the averaging. If this master coord file is not provided, one of the other coord files will be chosen arbitrarily as the target alignment. [default: None]

-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 _pca_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 beta_div_coords.txt -m Mapping_file.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 beta_div_coords.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 beta_div_coords.txt -m Mapping_file.txt -b 'mapping_column'

If the user would like to color all categories in their metadata mapping file, they can pass ‘ALL’ to the ‘-b’ option, as follows:

make_2d_plots.py -i beta_div_coords.txt -m Mapping_file.txt -b ALL

Prefs File:

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

make_2d_plots.py -i beta_div_coords.txt -m Mapping_file.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 jackknifed_pcoas/ -m Mapping_file.txt -b 'mapping_column1,mapping_column1&&mapping_column2' --ellipsoid_opacity=0.5 --ellipsoid_method=IQR