make_distance_histograms.py – Make distance histograms

Description:

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.

Usage: make_distance_histograms.py [options]

Input Arguments:

Note

[REQUIRED]

-d, --distance_matrix_file

Input distance matrix filepath (i.e. the result of beta_diversity.py).

-m, --map_fname

Input metadata mapping filepath.

[OPTIONAL]

-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]

--monte_carlo

Deprecated: pass –monte_carlo_iters > 0 to enable

--suppress_html_output

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:None; first field in mapping file is used]

--monte_carlo_iters

Number of iterations to perform for Monte Carlo analysis. [default: 0; No monte carlo simulation performed]

Output:

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.

Examples:

Distance Histograms are a way to compare different categories and see which tend to have larger/smaller distances than others. For example, in the 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 a 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.

In the following command, the user only supplies a distance matrix (i.e. resulting file from beta_diversity.py), the user-generated metadata mapping file and one category (e.g. pH):

make_distance_histograms.py -d beta_div.txt -m Mapping_file.txt --fields pH

For comparison of multiple categories (e.g. pH, salinity), you can use the following command:

make_distance_histograms.py -d beta_div.txt -m Mapping_file.txt --fields pH,salinity

HTML output is automatically generated. If the user would like to suppress the HTML output, you can use the following command:

make_distance_histograms.py -d beta_div.txt -m Mapping_file.txt --fields pH --suppress_html_output

In the case that the user generates their own preferences file (prefs.txt), they can use the following command:

make_distance_histograms.py -d beta_div.txt -m Mapping_file.txt -p prefs.txt

Note: In the case that a preferences file is passed, the user does not need to supply fields in the command-line.