NAME
heatmapper - Make heatmaps of biological communities
VERSION
This document refers to heatmapper version 0.9
SYNOPSIS
heatmapper -i otu_table.txt
DESCRIPTION
Heatmapper runs heatmap.2 in R to generate a heatmap. This script
automates the process and add options to add taxonomic labels, color by
taxon taxon, have a logarithmic scale and use color palettes with
multiple colors.
REQUIRED ARGUMENTS
-i <input_file>
A tab-separated community table in site-by-species matrix format.
Rows represent different species while columns are the different
sites (or samples). Row and column names (headers) are expected, and
although it is not enforced, the sum of all species is expected to
add up to 100. Taxonomic assignments should be semi- colon
delimited, such as in the Greengenes or Silva formats, e.g.:
k__Archaea;p__Euryarchaeota;c__Thermoplasmata;o__E2;f__MarinegroupII;g__
Archaea;Euryarchaeota;Thermoplasmata;E2;MarinegroupII;Other
OPTIONAL ARGUMENTS
-m <matrix_file>
Instead of performing the hierarchical clustering of the communities
based on their euclidean distance, you can provide a tab-delimited
matrix containing the distance of your choice (e.g. Unifrac
distance).
-t <taxonomy_level>
Specify at which taxonomy level to colorize: 'k'ingdom, 'p'hylum,
'c'lass, 'o'rder, 'f'amily, 'g'enus or 's'pecies. Default: k
-l <legend_taxonomy>
Specify how to display the taxonomy on the heatmap:
full: the entire taxonomy string (e.g.
k__Archaea;p__Euryarchaeota;c__Thermoplasmata;o__E2;f__MarinegroupII
),
local: the taxonomic group specified with the -t option (e.g.
p__Euryarchaeota) only,
auto: everything that comes after 'local' (e.g.
p__Euryarchaeota;c__Thermoplasmata;o__E2;f__MarinegroupII),
first: the first element of the taxonomy (e.g. k__Archaea),
last: the last element of the taxonomy (e.g. f__MarinegroupII).
Default: auto
-p <palette_col>
Palette of colors to use: * Jet : a 32-color palette going from blue
to green to red * Jet2: another 32-color jet palette that starts
with darker blue, has less cyan in the middle, and ends with lighter
red. * any sequential RColorBrewer
<http://svitsrv25.epfl.ch/R-doc/library/RColorBrewer/html/ColorBrewe
r.html> color palette (8-colors): Blues BuGn BuPu GnBu Greens Greys
Oranges OrRd PuBu PuBuGn PuRd Purples RdPu Reds YlGn YlGnBu YlOrBr
YlOrRd Default: Jet
-n <na_col>
For species with an abundance of zero, instead of using the color
specified by <palette_col>, use the plot background color. This
makes it easier to distinguish between species that were present at
low abundance and species that were not observed at all. Default: 0
-h <hierarch_clust>
Whether or not to cluster the samples hierarchically and display a
dendrogram (0: no, 1: yes). Note: Do not use if you have grouped
low-abundance OTUs or species into an "Other" category. Default: 0
-o <output_name>
File path where to create the output graph. Note that the file
extension specifies which graphic format to use: SVG, PDF, PNG, etc.
Default: heatmapper.svg
-s <width>x<height>
Size (width and height) of the output image, in pixels. If you get
an error message about margins being too large, you might have to
increase the weight or height. Default: 20x20
EXAMPLES
* SVG output with phylum-level colors
heatmapper -i otu_table.txt -s 30x5
* PNG output, coloring at the order taxonomic level
heatmapper -i otu_table.txt -t o -s 5000x1000 -o heatmap.png
INSTALLATION
Dependencies
You need to install these dependencies first:
* Perl
<http://www.perl.com/download.csp>
* make
Many systems have make installed by default. If your system does
not, you should install the implementation of make of your choice,
e.g. GNU make: <http://www.gnu.org/s/make/>
* R
<http://www.r-project.org>
You also need these two R libraries: gplots, RColorBrewer
The following CPAN Perl modules are dependencies that will be installed
automatically for you:
* Getopt::Euclid (>= 0.3.4)
* Statistics::R
Procedure
To install HeatMapper globally on your system, run the following
commands in a terminal or command prompt:
On Linux, Unix, MacOS:
perl Makefile.PL
make
And finally, with administrator privileges:
make install
On Windows, run the same commands but with nmake instead of make.
No administrator privileges?
If you do not have administrator privileges, HeatMapper needs to be
installed in your home directory.
First, follow the instructions to install local::lib at
<http://search.cpan.org/~apeiron/local-lib-1.008004/lib/local/lib.pm#The
_bootstrapping_technique>. After local::lib is installed, every Perl
module that you install manually or through the CPAN command-line
application will be installed in your home directory.
Then, install HeatMapper by following the instructions detailed in the
"Procedure" section.
AUTHOR
Florent Angly <florent.angly@gmail.com>
ACKNOWLEDGEMENTS
Credits go to Dana Willner for showing me R's heatmap.2 and for writing
the initial code for coloring taxa. Heatmapper was built on top of these
foundations.
BUGS
There are undoubtedly serious bugs lurking somewhere in this code. Bug
reports and other feedback are most welcome:
<http://github.com/fangly/heatmapper/issues>
COPYRIGHT
Copyright 2012, Florent Angly
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.