TreeViewer

<p align="center"> <a href="https://treeviewer.org"><img src="Icons/Program/Banner.svg"></a> </p>

Introduction

TreeViewer is a cross-platform program to draw phylogenetic trees. It is based on a "modular" approach, in which small modules are used to perform individual actions (such as computing the coordinates of the nodes of the tree, or drawing the tree branches) that together contribute to the final plot.

Each TreeViewer module has a user manual, and these can be displayed in TreeViewer by opening the Module Manager window (from the Edit menu) or by clicking on the various question mark (?) icons that are shown throughout the program when appropriate.

TreeViewer is written using C# .NET 7 and is available for Windows, macOS (Intel x64 and Apple Silicon ARM) and Linux operating systems. It consists of the main GUI program and a command-line utility that can be used to plot trees that are too large to be previewed on-screen in real time. It is licensed under a GNU Affero GPLv3 license.

Citing TreeViewer

If you use TreeViewer, please cite it as:

Bianchini, G., & Sánchez-Baracaldo, P. (2024).
TreeViewer: Flexible, modular software to visualise and manipulate phylogenetic trees
Ecology and Evolution, 14, e10873. https://doi.org/10.1002/ece3.10873

| Download citation: | | | | | |:---|---|---|---|---| | RIS (ProCite, Reference Manager) | EndNote | BibTex | Medlars | Plain text |

Installing TreeViewer

The easiest way to start using TreeViewer is to install the program using the installer for your operating system. Alternatively, you may wish to install the program manually or on a headless server.

Windows

Download TreeViewer-Win-x64.msi and double-click it (if you get a Windows Defender SmartScreen warning, click on More info and choose Run anyway). The installer will guide you through the process, and will do four main things:

1. Copy the program files (by default in C:\Program Files).
2. Delete any downloaded modules from previous versions of TreeVIewer.
3. Add the installation path to the PATH environment variable (so that you can recall TreeViewer from the command line, wherever you are located).
4. Add a shortcut to TreeViewer to the Start Menu.

Of course, 3 and 4 are optional, and you can decide to skip these steps during the installation.

You can now run TreeViewer using the shortcut that has been created. Alternatively, you can invoke the program from the command line by typing TreeViewer in the command prompt (which you can open by pressing Win+R on your keyboard, typing cmd and pressing Enter). You can also run the command-line version by typing TreeViewerCommandLine.

TreeViewer has been test on Windows 10 and Windows 11 on Intel x64 processors. It seems to work OK on Windows 11 for ARM running in an emulator, but this has not been tested extensively.

macOS

Download TreeViewer-Mac-x64.pkg and double-click it (starting from version 1.2.0, the TreeViewer installer and disk image are fully signed and notarized). If you get a message that the app cannot be opened because it was not downloaded from the App Store, right-click or ctrl-click on the file and choose "Open", then click on the "Open" button in the dialog that opens. The installer will open and guide you through the process. It will do three main things:

1. Copy the TreeViewer app to the /Applications folder.
2. Delete any downloaded modules from previous versions of TreeViewer.
3. Create symlinks to the TreeViewer executables (TreeViewer and TreeViewerCommandLine) in the /usr/local/bin folder.

Once the installer has finished, you can run TreeViewer by opening the App in your Applications folder. You can also run it from the command line by typing TreeViewer (or TreeViewerCommandLine for the command line version) in a terminal window.

TreeViewer has been tested on macOS Catalina (Intel x64), Big Sur (Intel x64), Monterey (Intel x64 and M1 Apple Silicon arm64), Ventura (M1 Apple Silicon arm64), and Sonoma (M1 Apple Silicon arm64).

Linux

TreeViewer has been tested on Debian 12 (bookworm), MX Linux 23.1, Ubuntu 22.04.3, Linux Mint 21.2, openSUSE Leap 15.5, Fedora 38, Manjaro 23.0.4, and CentOS 7. It may work on other distributions as well.

Open a terminal window and download the installer using wget or curl (whichever you prefer/have available):

wget https://github.com/arklumpus/TreeViewer/releases/latest/download/TreeViewer-Linux-x64.run

(To use curl, replace wget with curl -LO). Make the downloaded file executable and execute it as root:

chmod +x TreeViewer-linux-x64.run
sudo "./TreeViewer-linux-x64.run"

Depending on your system, you may have to replace sudo with su -c. You should be prompted for the super-user password. The installer will:

1. Copy the TreeViewer files to /usr/lib/TreeViewer (this can be changed)
2. Delete any downloaded modules from previous versions of TreeViewer.
3. Create symlinks to the TreeViewer and TreeViewerCommandLine executables in /usr/bin (this step can be skipped).
4. Add TreeViewer to the Desktop menu (this step can be skipped, but it is highly advised not to skip it, unless you are installing TreeViewer on a headless server without a desktop environment).

Note for CentOS users: the more utility on CentOS 7, which is used by the installer to display the licence notice, does not support the -e option. This will result in the licence terms failing to be displayed; you can find the licence document in this repository. This does not otherwise affect the installation.

You can now open TreeViewer using the icon that has been added to the desktop menu, or by typing TreeViewer (or TreeViewerCommandLine for the command-line version) in the command line.

Getting started

The first time you open TreeViewer after installing it, you will be greeted by a welcome window that will allow you to install the latest version of all the available modules. It is advised to install all the available modules, otherwise some actions may not be available in the program.

After this step is completed, on Windows and Linux a new window will open, asking you with which extensions you wish to associate TreeViewer. Choose the files that you would like to open with TreeViewer and click OK to create the file associations (on Windows, you may have to click on the "shield" button to execute this step as an administrator: when you do this, the program will restart after showing an elevation prompt and go straight to the file association window).

On macOS, file associations work differently: the file extensions supported by TreeViewer will automatically be associated with the program, unless you have another program that is already associated with them. You will also need to grant permission to TreeViewer to open files from anywhere on your computer; a window will open with detailed instructions on how to do this.

After these preliminary operations have been completed, the main TreeViewer window should open.

To verify that everything is working correctly, you can download and open the test.tbi file. You should get a warning about the file containing source code: this is a security feature, as files coming from unknown sources may contain malicious code. Whenever you open a file that has not been created by you, you will get a warning like this; however, you can choose to permanently trust the creator of the file, and in this way you will not get prompted again if you open another file that has been created by the same user.

After granting the file permission to load and compile the source code, you should get a plot similar to the one below:

<p align="center"> <img src="test.svg" height="250"> </p>

Troubleshooting and known issues

This section details some known issues that occur on Linux and macOS. In the vast majority of cases, these should not significantly affect your enjoyment of TreeViewer.

Linux

• On some Linux distributions, the file icons sometimes don't show up for some file types. This appears to be dependent on the file manager used by each distro, so unfortunately there is not much that we can do. Strangely enough, even though the custom icon is not shown, double clicking the files should still work and open them in TreeViewer.

• For complicated reasons, TreeViewer converts text into paths when drawing them in the GUI on Linux (everything works normally when exporting SVG or PDF files). As a result, drawing trees with many thousands of text labels will use more RAM than would normally be needed (e.g., on the same machine using another OS). If you need to work with such a large tree, you may want to remove the tip labels (see the tutorial on working with large trees) or to use a different OS.

macOS

• On macOS laptops,