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]
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.
View taxon information
In the treemap view, mouse over a rectangle
In the table view, mouse over a line
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.
Navigate through the tree
Zoom in
In the treemap view, click on a rectangle
In the table view, click on a taxon name
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.
Zoom out
In the treemap view, click on the header
In the menu bar, click on the Parent button
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.
Search for a taxon
In the menu bar, click on the Search... button
Start typing in the taxon name
Click on the desired taxon name
The treemap zooms in on the node. The full treemap now represents this node and displays its sub-branch.
View by specific phylogenic rank
Modifying the colors
In the menu bar, click on the Colors menu
Select the Color by Rank option
Select the desired rank in the Phylogenic Rank field
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.
Modifying the labels
In the menu bar, click on the Labels menu
Select the Label by Rank option
Select the desired rank in the Phylogenic Rank field
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.
Save your results
In the menu bar, click on the Export menu
Select the desired file
Select the Save File option
Click on the OK button
The file is now saved on your computer.
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".
name: Taxon name
children: List of children (taxa)
assigned: Value assigned to the taxon (number of reads)
sum: Cumulative values of the sub-branch starting at the current taxon (number of reads)
rank: Phylogenic rank name (cf. NCBI Taxonomy)
id: Taxon ID (cf. NCBI Taxonomy)
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.
In the menu bar, click on the Export menu
Click on Data File in JSON format
Select the Save File option
Click on the OK button
The file is now saved on your computer.
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
}
}
treemap: options affecting the treemap view.
display:
true : show the treemap view.
false : hide the treemap view.
width: #number : width of the treemap view in pixels
height: #number : height of the treemap view in pixels
table: options affecting the table view.
display:
true : show the table view.
false : hide the table view.
width: #number : width of the table view in pixels
height: #number : height of the table view in pixels
options: options affecting both views.
hierarchy:
rugged : show the ancestor nodes in the treemap view.
flat : show only the leaf nodes in the treemap view.
zoom:
fluid : during zoom events, move rectangles in the treemap view to optimise the space.
sticky : during zoom events, keep the relative positions of the rectangles in the treemap view.
proportion:
sample: values are normalized according to the samples, each sample represents the same area.
hits: values are not normalized, each hit represents the same area.
taxon: Each taxon represents the same area, whatever the associated value is.
cutoff_rank: [rank] : nodes at phylogenic ranks lower than [rank] are not displayed.
colored:
taxon: the nodes are colored according to taxon name.
rank: the nodes of a sub-branch starting at the specified rank are colored according to their root.
sample: The nodes are colored according to sample ID
majority: The nodes are colored according to the sample ID with the higher value in siblings.
colored_rank: [rank] : the nodes of a sub-branch starting at [rank] are colored according to their root.
upper:
colored: nodes at phylogenic ranks higher than the specified rank are colored according to taxon name.
grayed: nodes at phylogenic ranks higher than the specified rank are grayed out.
palette:
brewer: list of 12 pastel colors.
#8dd3c7, #ffffb3, #bebada, #fb8072, #80b1d3, #fdb462, #b3de69, #fccde5, #d9d9d9, #bc80bd, #ccebc5, #ffed6f
d3: list of 20 dark colors.
#1f77b4, #aec7e8, #ff7f0e, #ffbb78, #2ca02c, #98df8a, #d62728, #ff9896, #9467bd, #c5b0d5, #8c564b, #c49c94, #e377c2, #f7b6d2, #7f7f7f, #c7c7c7, #bcbd22, #dbdb8d, #17becf, #9edae5
background:
black: the background and the borders are colored in black
white: the background and the borders are colored in white
labelled:
taxon: Each leaf is labelled.
rank: The nodes at the specified rank are labelled.
no: Labels are not displayed
labelled_rank: [rank] : the nodes at [rank] are labelled.
pattern: [string] : pattern that sets the node labels.
font: #number : font size in pixels.
Import configuration file
In the menu bar, click on the Import menu
Click on the Configuration File (JSON) Browse... button
Select one file
Open the selected file
Click on the Load button
Your data should be visualized with the expected configuration.
Export configuration file
In the menu bar, click on the Export menu
Click on Configuration file in JSON format
Select the Save File option
Click on the OK button
The file is now saved on your computer.
Convert Data file
MTM can convert data files to the properly formatted JSON file.
Convert JSON file
{"taxon":{"label":Bacteria","id":"2","rank":"superkingdom"},children":[],"value":"21"}
Click on the Convert button
Select the Save File option
Click on the OK button
The file in proper format is now saved on your computer.
Convert tabular file
In the menu bar, click on the Import menu
Click on the Convert Data File Format... button
Click on the Data File Browse... button
Select one file
Open the selected file
Select the Format Tabular (TSV) option
Fill the fields with the corresponding column index in your file
Example of Tabular file:
ID Taxon Hits
2 Bacteria 21
If the file has a header (as in the example) please check the box Ignore 1st Line
Click on the Convert button
Select the Save File option
Click on the OK button
The file in proper format is now saved on your computer.
Color by taxon
In the menu bar, click on the Colors menu
Select the Color by Taxon option
A color is assigned to each taxon name.
Color by phylogenic rank
In the menu bar, click on the Colors menu
Select the Color by Rank option
Select the desired rank in the Phylogenic Rank field
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.
Color by sample
In the menu bar, click on the Colors menu
Select the Color by Sample option
Nodes are colored according to their sample number.
Color by majority
In the menu bar, click on the Colors menu
Select the Color by Majority option
Nodes are colored according to the number of the sample with the higher value among the siblings.
Palette
In the menu bar, click on the Colors menu
Select the Palette you want to use
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
Background
The background can be set to two colors:
In the menu bar, click on the Colors menu
Click on the Background toggle to set the background color
The background is updated.
Label by taxon
In the menu bar, click on the Labels menu
Select the Label by Taxon option
All rectangles of the treemap are labelled.
Label by phylogenic rank
In the menu bar, click on the Labels menu
Select the Label by Rank option
Select the desired rank in the Phylogenic Rank field
The nodes at the specified rank are labelled on the treemap.
See section View by specific phylogenic rank for more options.
No label
In the menu bar, click on the Labels menu
Select the Label by No Label option
Labels are hidden
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:
#N: Taxon Name
#I: NCBI Taxonomy ID
#H: Number Of Hits
#R: Phylogenic Rank
#S: Sample Number
#P: % By Sample
#V: % By View
\\: Break line
In the menu bar, click on the Labels menu
Fill the Label Format field with a Pattern
Press enter key to validate
The labels are modified.
Font size
In the menu bar, click on the Labels menu
Select the desired Font Size
The font size of the treemap labels, tooltips and table is modified.
Hierarchy
Hierarchy can be displayed in two modes:
rugged : each taxon is represented as a rectangle. The parent nodes appear as a border encapsulating their children.
flat : only the leaf nodes appear on the treemap. The parent nodes are not represented.
In the menu bar, click on the Treemap menu
Click on the Hierarchy toggle to set its mode
The treemap hierarchy is updated.
Zoom transition
Zoom transition can be set to two modes:
fluid : the rectangles are moved to optimize the treemap.
sticky : the relative positions of the rectangles are fixed.
In the menu bar, click on the Treemap menu
Click on the Zoom Transition toggle to set its mode
The zoom feature is updated.
Proportion by sample
In the menu bar, click on the Treemap menu
Select the Proportion by Sample option
The area of the rectangles are proportional to the percentage of hits in the sample.
Proportion by hit
In the menu bar, click on the Treemap menu
Select the Proportion by Hits option
The area of the rectangles are proportional to the number of hits.
Proportion by taxon
In the menu bar, click on the Treemap menu
Select the Proportion by Sample option
The area of each rectangle is the same.
Rank cutoff
In the menu bar, click on the Treemap menu
Select the desired rank in the Rank Cutoff field
The descendants of the nodes at the specified rank are hidden .
Hide treemap
In the menu bar, click on the Layout menu
Click on the Treemap toggle to set it to hide
Click on the Load button
The treemap is hidden.
Display treemap
In the menu bar, click on the Layout menu
Click on the Treemap toggle to set it to display
Fill in the Width field with the desired number of pixels
Fill in the Height field with the desired number of pixels
Click on the Load button
The treemap is displayed with the specified dimensions.
Hide table
In the menu bar, click on the Layout menu
Click on the Table toggle to set it to hide
Click on the Load button
The table is hidden.
Display table
In the menu bar, click on the Layout menu
Click on the Table toggle to set it to display
Fill in the Width field with the desired number of pixels
Fill in the Height field with the desired number of pixels
Click on the Load button
The table is displayed with the specified dimensions.
The data can be saved in various formats:
Data file in JSON format (text)
Treemap image in SVG format (vectorial)
Treemap image in PNG format (bitmap)
Table data in TSV format (table)
Configuration file in JSON format (text)
See section Save your results , the same procedure is used for each type of file.