News and Announcements » – Generate Rarefaction Plots


Once the batch alpha diversity files have been collated, you may want to compare the diversity using plots. Using the results from, you can plot the samples and or by category in the mapping file using this script.

This script creates an html file of rarefaction plots based on the supplied collated alpha-diversity files in a folder or a comma-separated list of files, by passing the “-i” option. Be aware that this script produces many images for the interactive html pages, so you may choose to not create these pages. The user may also supply optional arguments like an image type (-g), and a resolution (-d).

Usage: [options]

Input Arguments:



-i, --input_dir
Input directory containing results from [REQUIRED]
-m, --map_fname
Input metadata mapping filepath. [REQUIRED]


-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]
-g, --imagetype
Type of image to produce (i.e. png, svg, pdf). WARNING: Some formats may not properly open in your browser! [default: png]
-d, --resolution
Resolution of the plot. [default: 75]
-y, --ymax
Maximum y-value to be used for the plots. Allows for directly comparable rarefaction plots between analyses [default: None]
-w, --webpage
DEPRECATED: Suppress HTML output. [default: True]
-s, --suppress_html_output
Suppress HTML output. [default: False]
-e, --std_type
Calculation to perform for generating error bars. Options are standard deviation (stddev) or standard error (stderr). [default: stddev]
-o, --output_dir
Path to the output directory
Write the HTML output as one file, images embedded, or several. Options are “file_creation” and “memory”. [default: file_creation]
Generate per sample plots for each of the metadata categories. This will allow you to show/hide samples from the plots but will require a longer processing time. In general, this option is useful only for small datasets. [default: False]
Generate average tables of results. A summary of the metrics and alpha diversity measurements. [default: False]


The result of this script produces a folder and within that folder there is a sub-folder containing image files. Within the main folder, there is an html file.

Default Example:

For generated rarefaction plots using the default parameters, including the mapping file and one rarefaction file, you can use the following command: -i alpha_div_collated/ -m Fasting_Map.txt

Specify Image Type and Resolution:

Optionally, you can change the resolution (‘-d’) and the type of image created (‘-i’), by using the following command: -i alpha_div_collated/ -m Fasting_Map.txt -d 180 -g pdf

Use Prefs File:

You can also supply a preferences file ‘-p’, as follows -i alpha_div_collated/ -m Fasting_Map.txt -d 180 -p prefs.txt

Set Background Color:

Alternatively, you can set the plot background ‘-k’ -i alpha_div_collated/ -m Fasting_Map.txt -k black

Generate raw data without interactive webpages:

The user can choose to not create an interactive webpage (‘-w’ option). This is for the case, where the user just wants the average plots and the raw average data. -i alpha_div_collated/ -m Fasting_Map.txt -w

Generate average tables and per-sample plots:

Pass –generate_average_tables and –generate_per_sample_plots to generate average tables of results as tab-separated text and per-sample plots for each of the metadata categories -i alpha_div_collated/ -m Fasting_Map.txt --generate_average_tables --generate_per_sample_plots

Site index

Previous topic – Create python file

Next topic – Makes TopiaryExplorer project file