Drawing taxon images - arklumpus/TreeViewer GitHub Wiki

This guide will provide instructions on how to draw a phylogenetic tree that includes images that give the reader an idea of what is represented in the tree.

The tree file Fish.tre contains a phylogenetic tree of 10 species of fishes from the order Cyprinodontiformes, adapted from Rabosky et al. (2018). This is a clock-like tree, i.e. it is rooted and the branch lengths are expressed in units of millions of years ago (Mya).

When the tree file is opened in TreeViewer, it should look similar to the following figure:

We would like to add some pictures of the fish species that are included in this tree, so that the reader can get an idea of what they look like. The Fish.zip file contains 10 SVG files (one for each species):

Poecilia reticulata: adapted from an original image © Vincent Eisfeld / nordhausen-wiki.de / CC-BY-SA-4.0
Poecilia sphenops: adapted from an original photo by Hugo Torres / CC-BY-2.5-ES
All other images adapted with permission from original photos by Rudolf Pohlmann

You can directly add the Fish.zip file as an Attachment to the tree, by clicking on the Add attachment button in the Attachments tab. This will embed the archive with the tree file (you can leave the attachment name to its default Fish).

To actually draw the images, we need to use the Node images plot action module. Open the modules panel by clicking on the Plot actions button in the Modules tab. You can then enable this module by clicking on the Add module button under the Plot elements. Once you have added the module, you need to set the Attachment parameter so that it points to the ZIP file we have attached (i.e., Fish).

This will immediately draw all the fish images on the plot. Each image is centred on the corresponding tip of the tree, which results in a rather messy figure because of the limited vertical space:

To prevent the images from overlapping, we can increase the vertical spacing of the tips of the tree. To do this, expand the options for the Coordinates module, and set the Height to 500, then click Apply. The tree should now look similar to this figure:

The fish images are however still too big, and they also overlap with the taxon names. To solve these issues, within the options for the Node images module (in the Plot actions), you can change the X value of the Position shift to 180, as well as setting both the Width and Height parameters to 80. This will move the fish images to the right and resize each of them to 80% of the original size:

This tree is a clock-like tree: therefore, rather than showing the branch lengths, we want to show a scale axis that shows the time at which the various nodes in the tree originated.

To do this, first of all the second Labels module (which shows the branch lengths) can be removed from the plot by clicking on the × button next to it. Then, you should enable the Scale axis Plot action module, by clicking on the + button under the Plot elements and selecting the module. This will cause a scale axis to be drawn on the tree, which should look similar to the following image:

To make the labels on the scale axis look nicer, you can expand the options for this module and set the End parameter to 100. Then, you can increase the Tick spacing to 10 and set the Digits to 0 (which will remove the decimal digits from the scale axis).

The tree should now look similar to the following image:

This tree contains fishes from four different families within the order Cyprinodontiformes. It would be a good idea to show the names of the fish families on the tree, so that they can be easily distinguished. We can do this by using the Group labels module.

We can start by adding the names of the families to the tree. To do this, select the branch corresponding to the common ancestor of Poecilia sphenops and Poecilia reticulata; this will cause the Selection panel to open on the right. Here, click on the "tag" button to view the attributes for this node, and click on the Add attribute button to add a new attribute. A new window will open, in which you can set the Attribute name to Group, and the Attribute value to Poecilidae. This will add a new Add attribute Further transformation module to the plot, which adds the attribute to the selected node.

You should then repeat these steps to add a new Group attribute with value Cyprinodontidae to the ancestor of Cyprinodon nevadensis, Cyprinodon fontinalis and Aphaniops dispar. The ancestor of Austrofundulus leohoignei and Laimosemion xiphidus should be assigned a Group of Rivulidae, while the ancestor of Nothobranchius rachovii, Nothobranchius korthausae and Fundulopanchax deltaensis should have a Group of Nothobranchiidae. Finally, select the root node and add a Group attribute with value Cyprinodontiformes to it.

To draw the group names, you need to enable the Group labels module by clicking on the Add module button under the Plot elements. Then, expand the options for this module and set the Attribute to Group. This will cause the group labels to appear in the middle of the tree, which should look similar to the following image:

To move the group labels to the right, you should increase the Distance to 430. Then, you can increase the Height to 40 and the Margin to 20. Now, click on the button to change the Font parameter, and increase the font size to 15. Finally, set the Fill colour to something like a dark blue and the text Colour to white.

The tree should now look similar to the following image:

It would be nice to assign a different colour to each of the various families, so that they stand up a bit more. We achieve this by adding a new attribute containing the colour to the same nodes to which we added the family names. Select the ancestor of Poecilia sphenops and Poecilia reticulata and add a new attribute called LabelFillColour; leave the Attribute value empty for now. This will add a new Add attribute Further transformation module to the plot; select the Further transformations section in the modules panel and expand the options for this module, then click on the New value text box (as if you wanted to enter some text in it), then press CTRL+SHIFT+C (on Windows and Linux, or CMD+SHIFT+C on macOS). This will open a color picker window that you can use to specify a new colour. Select a light orange hue and click on the OK button: TreeViewer will automatically place the RGB Hex string corresponding to the selected colour in the text box. Now click on Apply and the colour of the Poecilidae label should change to the colour you selected.

Repeat these steps to add a light blue colour to the Cyprinodontidae, a green colour to the Rivulidae and a dark orange colour to the Nothobranchiidae (you can leave the colour for Cyprinodontiformes unchanged). The tree should now look similar to the following image:

Finally, since the tip labels of the tree show the names of the various fish species, it would be appropriate for them to be in italics. To achieve this, expand the options for the Labels module and click on the button to edit the Font; in the window that opens, select an Italic font style. The final tree figure should be similar to the following:

You can now save the tree file or the plot as a PDF or SVG file using the items from the File menu. You can also download the Fish.tbi tree file, which contains the tree along with all the modules.

The Examples section of TreeViewer's welcome page (in the File page) contains a very similar example, created following a previous version of this tutorial in which each fish image was added as a separate file.

• The archive file containing the images can be in ZIP, TAR, or TAR.GZ format.

• In this tutorial, the images contained in the archive file had exactly the same name as the taxa in the tree (except for the .svg extension). If this is not the case, you can use an additional attribute on the relevant nodes to specify which image should be used, and select it as the Image name in the options for the Node images module.

  • Including the file extension is optional, as long as the file extension is exactly the same as the selected Image format (case insensitive). For example, if the Image format is JPEG, then the attribute taxon will match a file called taxon (no extension) or taxon.jpeg, but it will not match taxon.jpg.

• The images within the archive file can be organised in subfolders: if this is the case, you then just need to ensure that the attribute that is used to retrieve the images also matches the subfolder structure, with / as the directory separator.

  • For example, if the archive contains a folder called images, which contains a file called taxon.svg, the attribute value should be images/taxon.svg or images/taxon.

• TreeViewer can draw images in multiple formats, including SVG, PDF, PNG, JPEG, GIF, and more.

• SVG images, being in a vector format, offer the best results for publication-quality figures. However, not all features of SVG are completely supported by TreeViewer. If these features are used by the image (or if for some reason the embedded image shows some artifacts), it might be necessary to use a different format.

  • There have been some improvements in the handling of SVG files that will be included in a future version of TreeViewer. If you have issues with SVG images (e.g., gradients not showing up correctly), you can try one of the following options:

    • If you are on Windows or Linux, you can download the file VectSharp.SVG.dll and use it to replace the version that comes with TreeViewer (by default, you will find this in C:\Program Files\TreeViewer\ on Windows and in /usr/lib/TreeViewer/ on Linux; you should keep a backup version of the original file, just in case). This should allow you to correctly open some SVG files that did not work before.

      • Unfortunately, this is not possible for most users on macOS, because replacing the file would invalidate the signature of the app package. If you know what this means and you are able to re-sign and re-notarize the app, it should work on macOS as well.

    • Alternatively, in some cases it might be sufficient to recreate the SVG file so that it only uses features that TreeViewer supports. You can do this by downloading the FixSVG program: (Windows, macOS and Linux) and then running it like this:

      FixSVG.exe input.svg > output.svg    # Windows
      ./FixSVG input.svg > output.svg      # Linux, macOS

      This will attempt to fix the file called input.svg, saving it as output.svg.

      Source code

      The source code for FixSVG is actually a single line of code:

      VectSharp.SVG.SVGContextInterpreter.SaveAsSVG(args.Length switch { 0 => VectSharp.SVG.Parser.FromStream(Console.OpenStandardInput()), 1 => VectSharp.SVG.Parser.FromFile(args[0]), _ => throw new ArgumentException("\n\nInvalid arguments!\nPlease either specify a single file, or do not\nprovide any arguments to read from the standard input.\n\n") }, Console.OpenStandardOutput());

• While PDF is also a vector format, TreeViewer currently does not directly include the vector image in the output; instead, each PDF image is rasterised at the time the tree is drawn. The resolution for the rasterised image can be increased or decreased by changing the Scale factor parameter in the options for the Draw image module.

  • This will also be fixed in the next release of TreeViewer (which will come out at some point).

• A previous version of this tutorial showed how to use the Draw image module to include one image at a time. This can be useful if you have very few taxa to illustrate, or if you want to include some other image within the tree plot, such as another tree. For example, the tree in Fig. 2 of Sánchez-Baracaldo et al. (2021) was obtained by adding the small tree in the top-right corner (including some Nostocales genera, such as Richelia, Dolichospermum and Nodularia) to the larger cyanobacterial tree.

• You can fine-tune the position and size of the image for each taxon using the X, Y, Width, and Height parameters. By clicking on the little "wrench" icon next to them, you can set these parameters so that the value is read from a node attribute (by default, ImageX, ImageY, ImageWidth and ImageHeight, respectively).

Daniel L. Rabosky, Jonathan Chang, Pascal O. Title, Peter F. Cowman, Lauren Sallan, Matt Friedman, Kristin Kaschner, Cristina Garilao, Thomas J. Near, Marta Coll, Michael E. Alfaro, An inverse latitudinal gradient in speciation rate for marine fishes, Nature 559, 392–395 (2018). https://doi.org/10.1038/s41586-018-0273-1

Patricia Sánchez-Baracaldo, Giorgio Bianchini, Jamie D. Wilson, Andrew H. Knoll, Cyanobacteria and biogeochemical cycles through Earth history, Trends in Microbiology, 2021. DOI: 10.1016/j.tim.2021.05.008