News and Announcements » – Make 2D PCoA Plots


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

Usage: [options]

Input Arguments:



-i, --coord_fname
Input principal coordinates filepath (i.e., resulting file from Alternatively, a directory containing multiple principal coordinates files for jackknifed PCoA results.
-m, --map_fname
Input metadata mapping filepath


-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]
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]
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]
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]
Generate the scree plot [default: False]
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


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, where the default coloring will be based on the SampleID as follows: -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. -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: -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. -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. -i unweighted_unifrac_pc.txt -m Fasting_Map.txt

Prefs File:

The user can supply a prefs file to color by, as follows: -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: -i pcoa/ -m Fasting_Map.txt -b 'Treatment&&DOB' --ellipsoid_opacity=0.5 --ellipsoid_method=IQR