Export2graphlan - how to incorporate metadata as ring annotations?

Thank you for providing and maintaining this great suite of tools.

I have been following the guide here to create hclust2 heatmaps and GraPhlAn cladograms for visualization of MetaPhlAn2 profiles.

My GraPhlAn workflow is as follows:

  1. Generate MetaPhlAn2 abundance profiles for individual fastq files β†’ sampleA_profile.txt, sampleB_profile.txt, sampleC_profile.txt, etc.
  2. Merge abundance profiles using merge_metaphlan_tables.py β†’ merged_abundance_table.txt
  3. Create tree and annotation files using export2graphlan.py β†’ merged_abundance.annot.txt and merged_abundance.tree.txt
  4. Create xml file using graphlan_annotate.py β†’ merged_abundance.xml
  5. Generate cladogram and legends using graphlan.py β†’ merged_abundance.png, merged_abundance_legend.png, and merged_abundance_annot.png

This produces a cladogram similar to the example provided in the demo linked above. However, I would like to make a cladogram that looks like the cladogram for the human microbiome project, where the rings surrounding the tree are a heatmap showing relative abundances of each species in each sample.

I have been playing around with the options for export2graphlan (e.g. --metadata_rows), but I can’t seem to generate an annotation file that preserves the sample information of my merged abundance table.

My tab-delimited merged_abundance_table.txt file has the following structure:

 ID      sampleA   sampleB   sampleC ...
 #SampleID       Metaphlan2_Analysis     Metaphlan2_Analysis     Metaphlan2_Analysis ...
 k__Bacteria     100.0     63.78929     75.19684 ...
 k__Bacteria|p__Actinobacteria     1.50648     0.0     0.0 ...     
 k__Bacteria|p__Actinobacteria|c__Actinobacteria     1.50648     0.0     0.0 ...

In short, what options can I use in my call of export2graphlan.py to create an annotation file that will encode the sample names and values found in merged_abundance_table.txt, such that graphlan_annotate.py adds the desired heatmap rings annotation to the xml? The biobakery github page does a great job explaining the ring options, but does not explicate how one is meant to programmatically incorporate ring annotations.


I’m using GraPhlAn version 1.1.3 and MetaPhlAn version 2.5.0.

Hi @acvill,

First, apologies for this very delayed response. To me, you are at the hardest part of using GraPhlAn and that is the creation of the annotation file specific to your project. I complete the project-specific parts (e.g. curating which taxa I want to label etc.) in R but it can certainly be done in other languages or even just in excel. From there you can add what labels you want to add, and which colors you want. The best example file/tutorial is here for how to use GraPhlAn. The best example annotation file is the annot_3.txt file. All specific options to pass to GraPhlAn can be found in its user manual which can also be a very useful resource.

Once you have externally created the annotation file then you can re-run the GraPhlAn annotate command as outlined either in the GraPhlAn tutorial above or here

I hope this helps! If you still have questions please let us know.

And sorry for the delayed response to your response. Yes, this was very helpful. Thank you.

1 Like