This script automates the creation of three-dimensional PCoA plots to be visualized with Emperor using Google Chrome.
This script creates an output directory with an HTML formated file named ‘index.html’ and a complementary folder named ‘emperor_required_resources’. Opening index.html with Google’s Chrome web browser will display a three dimensional visualization of the processed PCoA data file and the corresponding metadata mapping file.
Plot PCoA data:
Visualize the a PCoA file colored using a corresponding mapping file:
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -o emperor_output
Plot data generated from non-phylogenetic distance matrices:
Visualize a PCoA file where the data was computed with a non-phylogenetic distance metric (Euclidian, Bray-Curtis, etc.)
make_emperor.py -i euclidian_pc.txt -m Fasting_Map.txt -o euclidian
Coloring by metadata mapping file:
Additionally, using the supplied mapping file and a specific category or any combination of the available categories. When using the -b option, the user can specify the coloring for multiple header names, where each header is separated by a comma. The user can also combine mapping headers and color by the combined headers that are created by inserting an ‘&&’ between the input header names. Color by ‘Treatment’ and by the result of concatenating the ‘DOB’ category and the ‘Treatment’ category:
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -b 'Treatment&&DOB,Treatment' -o emperor_colored_by
PCoA plot with an explicit axis:
Create a PCoA plot with an axis of the plot representing the ‘DOB’ of the samples. This option is useful when presenting a gradient from your metadata e. g. ‘Time’ or ‘pH’:
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -a DOB -o pcoa_dob
PCoA plot with an explicit axis and using –missing_custom_axes_values:
Create a PCoA plot with an axis of the plot representing the ‘DOB’ of the samples and define the position over the gradient of those samples missing a numeric value; in this case we are going to plot the samples in the value 20060000. You can select for each explicit axis which value you want to use for the missing values:
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map_modified.txt -a DOB -o pcoa_dob_with_missing_custom_axes_values -x 'DOB:20060000'
PCoA plot with an explicit axis and using –missing_custom_axes_values but setting different values based on another column:
Create a PCoA plot with an axis of the plot representing the ‘DOB’ of the samples and defining the position over the gradient of those samples missing a numeric value but using as reference another column of the mapping file. In this case we are going to plot the samples that are Control on the Treatment column on 20080220 and on 20080240 those that are Fast:
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map_modified.txt -a DOB -o pcoa_dob_with_missing_custom_axes_with_multiple_values -x 'DOB:Treatment==Control=20080220' -x 'DOB:Treatment==Fast=20080240'
Jackknifed principal coordinates analysis plot:
Create a jackknifed PCoA plot (with confidence intervals for each sample) passing as the input a directory of coordinates files (where each file corresponds to a different OTU table) and use the standard deviation method to compute the dimensions of the ellipsoids surrounding each sample:
make_emperor.py -i unweighted_unifrac_pc -m Fasting_Map.txt -o jackknifed_pcoa -e sdev
Jackknifed PCoA plot with a master coordinates file:
Passing a master coordinates file (–master_pcoa) will display the ellipsoids centered by the samples in this file:
make_emperor.py -i unweighted_unifrac_pc -s unweighted_unifrac_pc/pcoa_unweighted_unifrac_rarefaction_110_5.txt -m Fasting_Map.txt -o jackknifed_with_master
Create a distance biplot to visualize where samples and taxa are in PCoA space. The cosine of the angle between taxanomic vectors approximates the correlation of those two taxa. The length of each of the taxonomic vectors approximates the variance of each taxa throughout all of the samples. The direction of the taxanomic vector explains the variance of all of the samples along that direction. To see which taxa are the ten more prevalent in the different areas of the PCoA plot, you need to pass a summarized taxa file i.e. the output of summarize_taxa.py. Note that if the the ‘–taxa_fp’ has fewer than 10 taxa, the script will default to use all.
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -t otu_table_L3.txt -o biplot
BiPlots with extra options:
To see which are the three most prevalent taxa and save the coordinates where these taxa are centered, you can use the -n (number of taxa to keep) and the –biplot_fp (output biplot file path) options.
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -t otu_table_L3.txt -o biplot_options -n 3 --biplot_fp biplot.txt
Drawing connecting lines between samples:
Tao draw lines betwen samples within a category use the ‘–add_vectors’ option. For example to connect the lines by the ‘Treatment’ category.
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt -o vectors --add_vectors Treatment
Drawing connecting lines between samples with an explicit axis:
To draw lines between samples within a category of the mapping file and have them sorted by a category that’s explicitly represented in the 3D plot use the ‘–add_vectors’ and the ‘-a’ option.
make_emperor.py -i unweighted_unifrac_pc.txt -m Fasting_Map.txt --add_vectors Treatment,DOB -a DOB -o sorted_by_DOB
Compare two coordinate files:
To draw replicates of the same samples like for a procustes plot.
make_emperor.py -i compare -m Fasting_Map.txt --compare_plots -o comparison