MetaTreeMap - User Guide

MetaTreeMap (MTM) is a JavaScript library for visualizing phylogenic trees with a quantity assigned to the nodes. The hierarchy is represented by nested rectangles where the area of each rectangle is proportional to the quantity assigned to each taxon.

Reference: "MetaTreeMap: an alternative visualization method for displaying metagenomic phylogenic trees." Hebrard M, Taylor TD. PLOS One 11(6):e0158261. (June 23, 2016) PMID 27336370.

Example files: This documentation use the samples F1-S and F1-U from the article:
"Comparative metagenomics revealed commonly enriched gene sets in human gut microbiomes." Kurokawa et al. DNA res 14(4):169-181. (August 31, 2007) PMID 17916580.
The data are accessible on MG-RAST. They were analysed with MetaBin, to obtain two data files: HuFS.json and HuFU.json.

Thumbnail: If you need a thumbnail, please use [This]. Or if you need a miniature, please use [This]

thumbnail

MTM thumbnail

JSON

MTM miniature

Quick Start

Import your data

See section Input format for more information

Your data should now be loaded and visualized.

In the menu bar, clicking on the displays a list of the currently loaded samples.

Import

In the menu bar, click on the Import menu

Browse...

Click on the Data File (JSON): Browse... button

Select

Select one or more files

Open

Open the selected files

Load

Click on the Load button

Loaded

Data are now loaded and visualized

Loaded

In the menu bar, click on the

Loaded

A list of the currently loaded samples is now displayed

View taxon information

A tooltip appears that displays taxon name, sample ID, NCBI taxonomy ID, phylogenic rank, number of hits, percentage of hits according to the sample and percentage of hits according to the current view.

treemap-info

In the treemap view, mouse over a rectangle

tale-info

In the table view, mouse over a line

Navigate through the tree

Zoom in

The treemap zooms in on the node. The full treemap now represents this node and displays its sub-branch.

If the node is a leaf, the treemap view zooms in on its parent.

treemap-zoomin

In the treemap view, click on a rectangle

tale-zoomin

In the table view, click on a taxon name

treemap-zoomed

The treemap now represents the sub-branch

Zoom out

The treemap zooms out, step-by-step, to the parent of the current node.

In the menu bar, the Root button zooms all the way out, back to the root node.

treemap-zoomout

In the treemap view, click on the header

option-zoomout

In the menu bar, click on the Parent button

option-zoomedout

The treemap now represents the parent node

option-toroot

In the menu bar, click on the Root button to zoom out to the root node

option-zoomroot

The treemap now represents the root node

The treemap zooms in on the node. The full treemap now represents this node and displays its sub-branch.

option-search

In the menu bar, click on the Search... button

search-write

Start typing in the taxon name

search-select

Click on the desired taxon name

search-selected

The treemap now represents this node

View by specific phylogenic rank

Modifying the colors

The descendants of the nodes at the specified rank are colored according to these nodes.

The option Upper Ranks, under the Colors menu, can be set to grayed. If so, the ascendants of the nodes at the specified rank are grayed out.

rank-colors

In the menu bar, click on the Colors menu

rank-by

Select the Color by Rank option

rank-select

Select the desired rank in the Phylogenic Rank field

rank-colored

The descendants of the nodes at the specified rank are now colored according to these nodes

rank-grayed

The option Upper Ranks, under the Colors menu, can be set to grayed

rank-grayedout

The ascendants of the nodes at the specified rank are now grayed out

Modifying the labels

The labels of the nodes at the specified rank are displayed.

The option Background, under the Colors menu, can be set to white. If so, the rectangle borders become white making the labels more legible.

rank-labels

In the menu bar, click on the Labels menu

rank-by

Select the Label by Rank option

rank-select

Select the desired rank in the Phylogenic Rank field

rank-labelled

The labels of the nodes at the specified rank are displayed

rank-bg

The option Background, under the Colors menu, can be set to white

rank-white

The rectangle borders are now in white

Save your results

The file is now saved on your computer.

save-menu

In the menu bar, click on the Export menu

save-file

Select the desired file

save-save

Select the Save File option

save-ok

Click on the OK button

Import

Data file

The data inputted in MTM should be a hierarchy of taxa with a value assigned to (at least some) taxa. The standard file format used by MTM is a JSON file with specific fields as described below.

A properly formatted JSON file can be obtained by analyzing metagenomic sequencing data with MetaBin program.

Example of minimal tree:

{"name":"root","children":[
 {"name":"Bacteria","children":[],"data":{"assigned":"42","sum":"42","rank":"superkingdom"},"id":"2"}
],"data":{"assigned":"0","sum":"42","rank":"no rank"},"id":"1"}

The root not of the tree must have id="1".

Import data file

See section Import your data

Export data file

In the case of multiple datasets inputted, a unique datafile is exported with the values summed for each taxon.

The file is now saved on your computer.

Export

In the menu bar, click on the Export menu

JSON

Click on Data File in JSON format

Save

Select the Save File option

OK

Click on the OK button

Configuration file

The options of MTM can be pre-set or saved using a configuration file. This file is in JSON format with specific fields as described below.

Default configuration:

{
"treemap": {"display":true, "width":700, "height":500},
"table": {"display":true, "width":700, "height":500},
"options": {
	"hierarchy":"rugged",
	"zoom":"fluid",
	"proportion":"sample",
	"cutoff_rank":"genus",
	"colored":"taxon",
	"colored_rank":"init",
	"upper":"colored",
	"palette":"brewer",
	"background":"black",
	"labelled":"taxon",
	"labelled_rank":"init",	
	"pattern":"#N",
	"font":14
	}
}

Import configuration file

Your data should be visualized with the expected configuration.

Import

In the menu bar, click on the Import menu

JSON

Click on the Configuration File (JSON) Browse... button

Select

Select one file

Open

Open the selected file

Load

Click on the Load button

Export configuration file

The file is now saved on your computer.

Export

In the menu bar, click on the Export menu

JSON

Click on Configuration file in JSON format

Save

Select the Save File option

OK

Click on the OK button

Convert Data file

MTM can convert data files to the properly formatted JSON file.

Convert JSON file

The file in proper format is now saved on your computer.

Import

In the menu bar, click on the Import menu

Convert

Click on the Convert Data File Format... button

Browse

Click on the Data File Browse... button

Select

Select one file

Open

Open the selected file

Format

Select the Format Other JSON option

Fields

Fill the fields with the corresponding names in your file

Convert

Click on the Convert button

Save

Select the Save File option

OK

Click on the OK button

Convert tabular file

The file in proper format is now saved on your computer.

Import

In the menu bar, click on the Import menu

Convert

Click on the Convert Data File Format... button

Browse

Click on the Data File Browse... button

Select

Select one file

Open

Open the selected file

Format

Select the Format Tabular (TSV) option

Fields

Fill the fields with the corresponding column index in your file

Convert

Check the box Ignore 1st Line

Convert

Click on the Convert button

Save

Select the Save File option

OK

Click on the OK button

Colors

Color by taxon

A color is assigned to each taxon name.

colors

In the menu bar, click on the Colors menu

by taxon

Select the Color by Taxon option

colored

A color is assigned to each taxon name

Color by phylogenic rank

The descendants of the nodes at the specified rank are colored according to these nodes.

The option Upper Ranks, under the Colors menu, can be set to grayed. If so, the ascendants of the nodes at the specified rank are grayed out.

colors

In the menu bar, click on the Colors menu

by rank

Select the Color by Rank option

select

Select the desired rank in the Phylogenic Rank field

colored

The descendants of the nodes at the specified rank are now colored according to these nodes

grayed

The option Upper Ranks, under the Colors menu, can be set to grayed

grayedout

The ascendants of the nodes at the specified rank are now grayed out

Color by sample

Nodes are colored according to their sample number.

colors

In the menu bar, click on the Colors menu

by sample

Select the Color by Sample option

colored

Nodes are colored according to their sample number.

Color by majority

Nodes are colored according to the number of the sample with the higher value among the siblings.

colors

In the menu bar, click on the Colors menu

by majority

Select the Color by Majority option

colored

Nodes are colored according to the number of the sample with the higher value among the siblings.

Palette

Brewer uses 18 pastel colors. D3 uses 20 dark colors.

Brewer: #8dd3c7, #ffffb3, #bebada, #fb8072, #80b1d3, #fdb462, #b3de69, #fccde5, #d9d9d9, #bc80bd, #ccebc5, #ffed6f

D3: #1f77b4, #aec7e8, #ff7f0e, #ffbb78, #2ca02c, #98df8a, #d62728, #ff9896, #9467bd, #c5b0d5, #8c564b, #c49c94, #e377c2, #f7b6d2, #7f7f7f, #c7c7c7, #bcbd22, #dbdb8d, #17becf, #9edae5

colors

In the menu bar, click on the Colors menu

palette

Select the Palette you want to use

brewer

Brewer uses 18 pastel colors

d3

D3 uses 20 dark colors

Background

The background can be set to two colors:

The background is updated.

colors

In the menu bar, click on the Colors menu

background

Toggle the background color

black

The background is black

white

The background is white

Labels

Label by taxon

All rectangles of the treemap are labelled.

labels

In the menu bar, click on the Labels menu

by taxon

Select the Label by Taxon option

labelled

All rectangles of the treemap are labelled

Label by phylogenic rank

The nodes at the specified rank are labelled on the treemap.

See section View by specific phylogenic rank for more options.

labels

In the menu bar, click on the Labels menu

by rank

Select the Label by Rank option

select

Select the desired rank in the Phylogenic Rank field

labelled

The nodes at the specified rank are labelled

No label

Labels are hidden

labels

In the menu bar, click on the Labels menu

no

Select the Label by No Label option

hidden

Labels are hidden

Label format

The label format option is used to customize the labels in the treemap. Users can specify what information appears on the label. Hashtags can be used to set the pattern that will be used to specify data elements.

Hashtags list:

The labels are modified.

labels

In the menu bar, click on the Labels menu

format

Fill the Label Format field with a Pattern

formated

Press enter key, the labels are modified (pattern: #N \\ #V% \\ #H hits)

Font size

The font size of the treemap labels, tooltips and table is modified.

labels

In the menu bar, click on the Labels menu

font

Select the desired Font Size

formated

The font size of the treemap labels, tooltips and table is modified (font size = 20)

Treemap

Hierarchy

Hierarchy can be displayed in two modes:

The treemap hierarchy is updated.

treemap

In the menu bar, click on the Treemap menu

hierarchy

Toggle the hierarchy mode

rugged

Rugged : each taxon is represented as a rectangle

flat

Flat : only the leaf nodes appear on the treemap

Zoom transition

Zoom transition can be set to two modes:

The zoom feature is updated.

treemap

In the menu bar, click on the Treemap menu

zoom

Toggle the hierarchy mode

fluid

Fluid : the rectangles are moved to optimize the treemap.

sticky

Sticky : the relative positions of the rectangles are fixed.

Proportion by sample

The area of the rectangles are proportional to the percentage of hits in the sample.

treemap

In the menu bar, click on the Treemap menu

select

Select the Proportion by Sample option

by sample

The area of the rectangles are proportional to the percentage of hits in the sample

Proportion by hit

The area of the rectangles are proportional to the number of hits.

treemap

In the menu bar, click on the Treemap menu

select

Select the Proportion by Hits option

by hits

The area of the rectangles are proportional to the number of hits.

Proportion by taxon

The area of each rectangle is the same.

treemap

In the menu bar, click on the Treemap menu

select

Select the Proportion by Sample option

by taxon

The area of each rectangle is the same.

Rank cutoff

The descendants of the nodes at the specified rank are hidden.

treemap

In the menu bar, click on the Treemap menu

select

Select the desired rank in the Rank Cutoff field

cutoff

The descendants of the nodes at the specified rank are hidden (cutoff: order)

Go to

See section Navigate through the tree.

Layout

Hide treemap

The treemap is hidden.

layout

In the menu bar, click on the Layout menu

hide

Toggle the Treemap option

load

Click on the Load button

hidden

The treemap is hidden

Display treemap

The treemap is displayed with the specified dimensions.

layout

In the menu bar, click on the Layout menu

display

Toggle the Treemap option

width

Fill in the Width field with the desired number of pixels

height

Fill in the Height field with the desired number of pixels

load

Click on the Load button

displayed

The treemap is displayed with the specified dimensions.

Hide table

The table is hidden.

layout

In the menu bar, click on the Layout menu

hide

Toggle the Table option

load

Click on the Load button

hidden

The table is hidden

Display table

The table is displayed with the specified dimensions.

layout

In the menu bar, click on the Layout menu

display

Toggle the Table option

width

Fill in the Width field with the desired number of pixels

height

Fill in the Height field with the desired number of pixels

load

Click on the Load button

displayed

The table is displayed with the specified dimensions.

Export

The data can be saved in various formats:

See section Save your results, the same procedure is used for each type of file.