News and Announcements » – Make 3D PCoA plots


This script automates the construction of 3D plots (kinemage format) from the PCoA output file generated by (e.g. P1 vs. P2 vs. P3, P2 vs. P3 vs. P4, etc., where P1 is the first component).

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]
-s, --scaling_method
Comma-separated list of scaling methods (i.e. scaled or unscaled) [default=unscaled]
-a, --custom_axes
This is the category from the metadata mapping file to use as a custom axis in the plot. For instance, if there is a pH category and you would like to see the samples plotted on that axis instead of PC1, PC2, etc., one can use this option. It is also useful for plotting time-series data. Note: if there is any non-numeric data in the column, it will not be plotted [default: None]
-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: black]
Used only when plotting ellipsoids for jackknifed beta diversity (i.e. using a directory of coord files instead of a single coord file). Valid choices are 0-3. A value of 0 produces very coarse “ellipsoids” but is fast to render. If you encounter a memory error when generating or displaying the plots, try including just one metadata column in your plot. If you still have trouble, reduce the smoothness level to 0. [default: 1]
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]
-t, --taxa_fname
Used only when generating BiPlots. Input summarized taxa filepath (i.e., from Taxa will be plotted with the samples. [default=None]
Used only when generating BiPlots. This is the number of taxa to display. Use -1 to display all. [default: 10]
Used only when generating BiPlots. Output coordinates filepath when generating a biplot. [default: None]
Output format. If this option is set to invue you will need to also use the option -b to define which column(s) from the metadata file the script should use when writing an output file. [default: king]
-n, --interpolation_points
Used only when generating inVUE plots. Number of points between samples for interpolatation. [default: 0]
Used only when generating inVUE plots. The number of points to be generated when creating a frame around the PCoA plots. [default: 4]
Used only when generating inVUE plots. The offset to be added to each point created when using the –polyhedron_points option. This is only used when using the invue output_format. [default: 1.5]
Create vectors based on a column of the mapping file. This parameter accepts up to 2 columns: (1) create the vectors, (2) sort them. If you wanted to group by Species and order by SampleID you will pass –add_vectors=Species but if you wanted to group by Species but order by DOB you will pass –add_vectors=Species,DOB; this is useful when you use –custom_axes param [default: None]
The algorithm used to create the vectors. The method used can be RMS (either using ‘avg’ or ‘trajectory’); or the first difference (using ‘diff’), or ‘wdiff’ for a modified first difference algorithm (see –window_size) the aforementioned use all the dimensions and weights them using their percentage explained; returns the norm of the created vectors; and their confidence using ANOVA. The Vectors are created as follows: for ‘avg’ it calculates the average at each timepoint (averaging within a group), then calculates the norm of each point; for ‘trajectory’ calculates the norm for the 1st-2nd, 2nd-3rd, etc.; for ‘diff’, it calculates the norm for all the time-points and then calculates the first difference for each resulting point; for for ‘wdiff’ it uses the same procedure as the previous method but the subtraction will be between the mean of the next number of elements specified in –window_size and the current element, both methods (‘wdiff’ and ‘diff’) will also include the mean and the standard deviation of the calculations [defautl: None]
The number of axes to account while doing the vector specificcalculations. We suggest using 3 because those are the ones being displayed in the plots but you could use any number between 1 and number of samples- 1. To use all of them pass 0. [default: 3]
Name of the file to save the first difference, or the root mean square (RMS) of the vectors grouped by the column used with the –add_vectors function. Note that this option only works with –add_vectors. The file is going to be created inside the output_dir and its name will start with the word ‘Vectors’.[default: vectors_output.txt]
-w, --weight_by_vector
Use -w when you want the output created in the –vectors_path to be weighted by the space between samples in the –add_vectors, sorting column, i. e. days between samples [default: False]
Use –window_size, when selecting the modified first difference (‘wdiff’) option for –vectors_algorithm. This integer determines the number of elements to be averaged per element subtraction, the resulting vector. [default: None]
-o, --output_dir
Path to the output directory


By default, the script will plot the first three dimensions in your file. Other combinations can be viewed using the “Views:Choose viewing axes” option in the KiNG viewer (Chen, Davis, & Richardson, 2009), which may require the installation of kinemage software. The first 10 components can be viewed using “Views:Paralled coordinates” option or typing “/”. The mouse can be used to modify display parameters, to click and rotate the viewing axes, to select specific points (clicking on a point shows the sample identity in the low left corner), or to select different analyses (upper right window). Although samples are most easily viewed in 2D, the third dimension is indicated by coloring each sample (dot/label) along a gradient corresponding to the depth along the third component (bright colors indicate points close to the viewer).

Default Usage:

If you just want to use the default output, you can supply the principal coordinates file (i.e., resulting file from and a user-generated mapping file, where the default coloring will be based on the SampleID as follows: -i unweighted_unifrac_pc.txt -m Fasting_Map.txt

Mapping File Usage by Category:

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’. -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -b 'Treatment&&DOB'

Color All Categories:

If the user would like to color all categories in their metadata mapping file they should not pass -b (default is color by all categories) -i unweighted_unifrac_pc.txt -m Fasting_Map.txt

Prefs File Example:

As an alternative, the user can supply a preferences (prefs) file, using the -p option. The prefs file allows the user to give specific samples their own columns within a given mapping column. This file also allows the user to perform a color gradient, given a specific mapping column.If the user wants to color by using the prefs file (e.g. prefs.txt), they can use the following code: -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -p prefs.txt

Output Directory:

If you want to give an specific output directory (e.g. ‘3d_plots’), use the following code: -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -o 3d_plots

Background Color Example:

If the user would like to color the background white they can use the ‘-k’ option as follows: -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -k white

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


If the user would like to see which taxa are more prevalent in different areas of the PCoA plot, they can generate Bi-Plots, by passing a principal coordinates file or folder ‘-i’, a mapping file ‘-m’, and a summarized taxa file ‘-t’ from Can be combined with jacknifed principal coordinates. -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -t otu_table_L3.txt

Site index