---
layout: page
---

## Heatmap

**phyloFlash** runs from multiple libraries can be compared with a heatmap with the `phyloFlash_heatmap.R` script. New users are recommended not to use this script directly, but to use the wrapper `phyloFlash_compare.pl` (see [Utilities](utilities.html)). 

The comparison is based on the counts of how many reads map onto each reference sequence, and the taxonomic affiliation of the reference taken from the SILVA taxonomy string. These are the "NTUs" found under the heading "Read mapping based detected higher taxa" in the standard **phyloFlash** output.

Libraries will be clustered by their similarity in terms of taxonomic content. Taxa/NTUs will be clustered by their co-occurrence across samples.

## Quickstart:
```bash
phyloFlash_heatmap.R -h # Show help message
# Run from same folder as phyloFlash output
phyloFlash_heatmap.R -o heatmap.png *.csv
```

## 1. Requirements

Requires `R` and the following packages: `optparse`, `methods`, `grid`, `ggplot2`,
`reshape2`, `ggdendro`, `gtable`.

The script can also be run within the `R` environment with `source("/path/to/phyloFlash_heatmap.R")`. A short help message will appear when the script is loaded in the R environment.

## 2. Basic heatmap

The input to the `phyloFlash_heatmap.R` script are the .csv outputs from `phyloFlash.pl`. You will need the .csv files from at least two runs to perform the comparison. For simplicity, it is probably easier to copy all the .csv files that you need into a single folder to run the heatmap analysis.

```bash
phyloFlash_heatmap.R -o output.png *.csv
# Alternative: get library names from filenames
phyloFlash_heatmap.R -o output.png --library-name-from-file *.csv
```

Running this in the `test_files` folder will yield a heatmap like this:

![Demo heatmap from data in test_files folder](example_heatmap.png)

## 3. How to interpret the heatmap:

 - Rows represent taxa, columns represent samples.
 - The color scale indicates abundance of taxon by number of reads, scaled as percentages.
 - The heatmap is split by taxonomy into Eukaryota and non-Eukaryota.
 - Taxonomic diversity of the sample is reported as the Chao1 statistic
 - NTUs with counts < 50 are placed together in "Other" by default

## 4. Changing heatmap options

View the full list of options with the help flag

```bash
phyloFlash_heatmap.R -h
```

Here is an overview of the more commonly-used options

### 4.1. Changing output appearance

Changes to the appearance of the output figure can be made via the following options for the `phyloFlash_heatmap.R` script:

`-o FILENAME` or `--out=FILENAME` Choose output filename. Format is either PNG or PDF, specified by the output filename extensions.

`--colors=COLORS` Change colors used for heatmap. Options are `steelblue`, `indianred`, `green`, and `orange`.

`-s HEIGHTXWIDTH` or `--out-size=HEIGHTXWIDTH` Change output image size, the default is `autoXauto`

`-r ROWS` or `--rows=ROWS` Choose what elements to draw for each row, any combination of `tree`, `map`, `chao`, and `labels`, separated by commas

`-c COLS` or `--cols=COLS` Choose what elemnts to draw for each column, any combination of `labels`, `map`, `tree`, separated by commas

`-l` or `--long-taxnames` Do not shorten taxa names to only the last two fields of taxonomy string

### 4.2. Changing clustering parameters

Clustering parameters for either libraries or taxa can be modified.

`-a` or `--absolute` Use absolute values instead of percentages

`-n MIN-NTU-COUNT` or `--min-ntu-count=MIN-NTU-COUNT` Change the threshold of counts per NTU to be included in the category "Other" in the heatmap. Default: 50

`-m CLUSTER-SAMPLES` or `--cluster-samples=CLUSTER-SAMPLES` Change the clustering method used for samples, choose between choose between `alpha`, `ward`, `single`, `complete`, `average`, `mcquitty`, `median` or `centroid`. To turn off clustering and sort samples alphabetically, choose `alhpa`. Default: `ward.D`

`-M CLUSTER-TAXA` or `--cluster-taxa=CLUSTER-TAXA` Change the clustering method used for taxa, choose between choose between `alpha`, `ward`, `single`, `complete`, `average`, `mcquitty`, `median` or `centroid`. To turn off clustering and to sort taxa alphabetically, choose `alpha`. Default: `ward.D`

`--no-split` Do not split heatmap

`-t SPLIT-REGEX` or `--split-regex=SPLIT-REGEX` Split the heatmap by a regular expression applied to the taxonomy strings. Default: 'Eukaryota'

### 4.3. Further options and known issues

`--library-name-from-file` Get library/sample names for heatmap from filenames. Otherwise the script will look into the `*report.csv` files to find the corresponding library name

`-v` or `--verbose`; `-q` or `--quiet` Change the amount of detail in status/error messages.

`-d` or `--debug` Show debug messages - use this if there is a bug and you would like to submit an error report. The output will help us to diagnose the problem.

  - The clustering may fail if there is only one taxon
  - Running the comparison script will only give a first overview of your data - the output is dependent on the accuracy and consistency of the taxonomic annotation of the SILVA database.
  - Publication-ready figures will require additional curation, including in most cases a custom database for the organisms being targeted.
