News and Announcements » – Make distance histograms


To visualize the distance between samples and/or categories in the metadata mapping file, the user can generate histograms to represent the distances between samples. This script generates an HTML file, where the user can compare the distances between samples based on the different categories associated to each sample in the metadata mapping file.

Distance histograms provide a way to compare different categories and see which tend to have larger/smaller distances than others. For example, in a hand study, you may want to compare the distances between hands to the distances between individuals (with the file “hand_distances.txt” using the parameter -d hand_distances.txt). The categories are defined in the metadata mapping file (specified using the parameter -m hand_map.txt). If you want to look at the distances between hands and individuals, choose the “Hand” field and “Individual” field (using the parameter –fields Hand,Individual (notice the fields are comma-delimited)). For each of these groups of distances a histogram is made. The output is an HTML file which is created in the “Distance_Histograms” directory (using the parameter -o Distance_Histograms to specify output directory) where you can look at all the distance histograms individually, and compare them between each other.

Usage: [options]

Input Arguments:



-d, --distance_matrix_file
Input distance matrix filepath (i.e. the result of WARNING: Only symmetric, hollow distance matrices may be used as input. Asymmetric distance matrices, such as those obtained by the UniFrac Gain metric (i.e. -m unifrac_g), should not be used as input
-m, --map_fname
Input metadata mapping filepath.


-p, --prefs_path
Input user-generated preferences filepath. NOTE: This is a file with a dictionary containing preferences for the analysis. This dictionary must have a “Fields” key mapping to a list of desired fields. [default: None]
-o, --dir_path
Output directory. [default: ./]
-k, --background_color
Background color for use in the plots (black or white) [default: white]
Deprecated: pass –monte_carlo_iters > 0 to enable
Suppress HTML output. [default: False]
-f, --fields
Comma-separated list of fields to compare, where the list of fields should be in quotes (e.g. “Field1,Field2,Field3”). Note: if this option is passed on the command-line, it will overwrite the fields in prefs file. [default: first field in mapping file is used]
Number of iterations to perform for Monte Carlo analysis. [default: 0; No monte carlo simulation performed]


The result of this script will be a folder containing images and/or an HTML file (with appropriate javascript files), depending on the user-defined parameters.

Distance histograms example:

In the following command, the user supplies a distance matrix (i.e. the resulting file from, the user-generated metadata mapping file and one category “Treatment” to generate distance histograms. -d unweighted_unifrac_dm.txt -m Fasting_Map.txt --fields Treatment -o example1

Multiple categories:

For comparison of multiple categories (e.g. Treatment, DOB), you can use the following command (separating each category with a comma). -d unweighted_unifrac_dm.txt -m Fasting_Map.txt --fields Treatment,DOB -o example2

Suppress HTML output:

By default, HTML output is automatically generated. If the user would like to suppress the HTML output, you can use the following command. -d unweighted_unifrac_dm.txt -m Fasting_Map.txt --fields Treatment --suppress_html_output -o example3

Preferences file:

You can provide your own preferences file (prefs.txt) with the following command. If a preferences file is supplied, you do not need to supply fields on the command-line. -d unweighted_unifrac_dm.txt -m Fasting_Map.txt -p prefs.txt -o example4

Site index