Skip to main content Skip to navigation

School of Life Sciences

TreeMos FAQ

Introduction

This software is designed to search for instances of phylogenetic mosaicism among a group of sequence alignments and individual sequences. The software is designed to run on Mac OS X, Windows and Linux. We have tested the software on Mac OS X 10.4.9 and 10.5.2, Windows XP and SuSE Linux 9.3

The software makes use of standard phylogenetic and sequence analysis packages to identify phylogenetic mosaicism using the algorithm described.

The software can be used in three different ways:

  • Through a web browser - this allows you to run the software, and to visualise instances of phylogenetic mosaicism, from your web browser
  • From the command line - this allows you to run the software using a simple text menu, and to generate images of phylogenetic mosaicism for viewing later
  • As part of a high-throughput pipeline - this allows you to run the software without human intervention, and to generate raw data files describing instances of phylogenetic mosaicism

You can also use your web browser to monitor the running and view the output of the command line program.

Prerequisites

Mac OS X

All of the software needed to run TreeMos is included in Mac OS X.

The web browser version of the software needs personal web sharing to be switched on, and the installation will switch it on for you. If you switch it off later, and need to switch it back on again, click on the 'System Preferences' icon. Under 'Internet and network' click on 'Sharing'. Make sure that 'Personal Web Sharing' is switched on.

This version was compiled to run on Intel-based Macs. If you have a PowerPC Mac, then you also need to install the Fink program to allow TreeMos to access the resources it needs during installation. Fink is available from https://www.finkproject.org/Link opens in a new window.

Windows

In Windows, we have tested the software using Xampp version 1.6.6a and Activeperl version 5.10.0 to provide a personal webserver with CGI. We recommend that you install these, which are both free, before you install TreeMos. Xampp is available from https://www.apachefriends.org/ and Activeperl is available from https://www.activestate.com/Link opens in a new window.

Linux

Most of the software needed to run TreeMos is included in Linux. To run the web browser version, you need to start Apache (httpd) and ensure that it is configured to use Perl to generate CGI pages. If you are not sure how to do this, you could just install the Xampp package from https://www.apachefriends.org/, which is free. We also recommend that you install the CPAN package.

Licensing

TreeMos is provided under a GNU GPL license. Full license details. By installing TreeMos you agree to abide by the conditions of all applicable licenses.

A number of components are provided with the software, including the third-party packages NCBI BLAST, CLUSTALW, Phylip, and Upload Lite. These softwares are provided as-is, and are the property of their respective owners. See the License details here. If you already have some or all of these packages installed, do not worry, the copies that come with TreeMos are separate, and will not interfere with any previously installed versions you may have. If you wish, you can reconfigure TreeMos to use your own installed versions instead of installing its own, but bear in mind that we may not have tested your exact combination of components, so results may vary.

Installation

When you have the prerequisites, double-click the install package to begin installation. You will be guided through the process, and the software will carry out a number of checks to make sure it is installed correctly. If you simply answer 'Yes' to the default values, you should obtain a working installation.

Running TreeMos from your web browser

To run the program from your browser, Apache must be running first, then double-click on the TreeMos icon that was created at installation. In Mac OS X, this is in Applications/TreeMos folder and is called 'TreeMos.app'. In Windows, it is in the TreeMos folder on your desktop and is called 'TreeMos Browser'. Alternatively, on any type of computer, open your browser, and type in this URL: http://localhost/cgi-bin/treemos

You will then need to identify the files containing your sequence alignments, and click 'Search'.

Progress of the search is indicated, and when TreeMos has finished searching your alignments, you can view the results.

You can save results using the 'Archive' button, before carrying out new searches.

Running TreeMos from the command line

To run the program from the command line, first open a command shell. In Mac OS X this is Applications/Utilities/Shell. In Windows click Start/Run and type cmd.exe. In Linux start a command shell.

Use cd to change to the directory in which you installed TreeMos. The default location in Mac OS X is /Applications/TreeMos/TreeMos.app/Contents/Resources. In Windows it is "Desktop\TreeMos_1.0e_Win".

Type 'perl treemos [directory]' where [directory] is the name of the directory which contains your alignment files.

If you type 'perl treemos' without a directory name, the program will tell you it needs to know the directory name.

The raw results data will be generated in the 'results' subdirectory, and images visualising mosaicism will be generated in the htdocs/treemos_images/results directory of your personal webserver.

Logs of all activities, and any errors, will be written to the 'logs' subdirectory.

If you want to change any of the locations to which temporary files, results, or logs are written, you can change these directory names in the package treemos_config.pm.

Frequently asked questions

How should I prepare my data for searching?

Gather your group of sequences (taxa) together, and create multiple alignments of each 'family' or subgroup of taxa, in FASTA format.

Place the FASTA multiple alignment files together in a directory. These will form the base data for TreeMos to search for instances of phylogenetic mosaicism.

What values should I use for the window size, increment size, and distance limit parameters?

The default values were set as appropriate for search among protein sequence alignments from a gene superfamily.

For search among nucleotide sequence alignments, you might consider increasing the window and increment sizes by a factor of three.

Increasing the window size reduces sensitivity and increases specificity by providing stronger phylogenetic signal to the tree-building and distance estimation algorithms.

Using increments smaller than the window size potentially generates finer-grain results with a subquadratic increase in processing time.

Increasing the distance limit increases sensitivity and reduces specificity, by considering more distant relationships as potentially important.

How are the results reported?

Instances of mosaicism are reported for each taxon, and for each 'family' of taxa (i.e. group of taxa for which you have generated a multiple alignment).

In the Web browser version, each window in the taxon which has anomalous phylogenetic affiliations with one or more segments of other taxa are highlighted, with links to the relevant segments.

In addition to the visualisation of results, a text file is generate, in tab-separated format, which lists all of the detail of each segment of the sequence, and the segment which is its nearest neighbour. This data file is called treemos.out, and is generated in the treemos results directory. In Mac OS X this directory is /Applications/TreeMos/TreeMos.app/Contents/Resources/results. In Windows this directory is called results and is inside the main TreeMos folder. You can open this file in Excel or a similar spreadsheet, or process the file automatically.

If TreeMos is run from the command-line or as part of a pipeline, this results file is the primary output, and is generated on STDOUT.

Can I save my results before I carry out a new search?

Yes. Click on the 'Archive' button in the menu at the top, and follow the directions. This will save the pictorial results. To save the text file results, take a copy of the file and save to your preferred location.

If I am using a personal web server to run TreeMos, can the program be accessed over the internet by other people, or by me using another computer?

TreeMos is designed to ensure that data are stored securely, away from any publicly accessible regions of your personal webserver. The personal webserver is only used as a convenient way of running the programs and viewing the results.

We have deliberately switched off the option for external users to run TreeMos searches, so that use of TreeMos can be limited to the computer on which it is installed.

If you wish, you can also add additional, operating-system-specific security control by adding a password to the treemos directories in your personal webserver.
However, TreeMos was envisaged to have potential as an intranet or internet service, so please contact us if you would like more details of this.

My personal webserver does not store its pages in the standard place. Can I change the locations TreeMos uses?

Yes. The file 'config' can be used to override a number of the default settings. Type the full path to your cgi-bin and/or htdocs directories in this file.

I already have BLAST/PHYLIP/ClustalW installed. Can I change TreeMos to use my existing versions?

Yes. The file 'config' can be used to override a number of the default settings. Type in the full path to your executables in this file. Please note that the TreeMos process must have execute-permission to these programs, and we recommend checking the permissions of these programs to ensure they are executable by all users.

I want my personal webserver pages to be in a subdirectory of my main webserver directory

Edit the app_dir entry in the 'config' file in the TreeMos directory, to contain the directory name you prefer. The line 'app_dir=treemos' would cause the pages to appear in a subdirectory of your personal webserver root called 'treemos'.

I have an older version of perl installed in Windows, can I use that instead of the latest one?

You will need to edit the installation file 'installer' in the source directory, before you install TreeMos. You need to find the line that calls ppm to install GD and change the details of the GD module to one which matches your version of perl.

I only want to use the command line option, and don't need the web browser version. Can I delete the TreeMos files from cgi-bin and htdocs?

Yes. The command-line version works as a self-contained unit. If you don't want to use any locations in your personal webserver, edit the cgi-bin and htdocs entries in the 'config' file in the TreeMos directory to point to the locations you prefer.

When I try to open the program, my browser gives the message 'Can't open the page "http://localhost/cgi-bin/treemos" because it could not connect to the server "localhost"'.

This is most likely to be because your personal web server software is not running.

In Mac OS X, click on the 'System Preferences' icon. Under 'Internet and network' click on 'Sharing'. Make sure that 'Personal Web Sharing' is switched on.

In Windows or Linux, if you have installed Xampp as your personal web server, open the Xampp Control Panel, and ensure that Apache is running (click 'Start' if it is not).

In 'vanilla' Linux, ensure that httpd is running, and that CGI is working correctly.

When I try to open the program, my browser gives the message ****

This is most likely to be because you are using a Mac PowerPC and the TreeMos software includes the Intel version of the GD library. You will need to obtain the GD library binaries for Power PC, and we recommend using Fink *** to do this. If you install Fink, and then double click on the 'install' program in the TreeMos directory, TreeMos will use Fink to acquire the GD library.

In Windows, when I start a search, the page does not refresh.

This is a known problem with the Windows version. Once you have clicked 'Search', click 'Back', or http://localhost/cgi-bin/treemos to monitor progress and view results.

Contact details

Please contact the authors through our website at https://warwick.ac.uk/fac/sci/lifesci/research/archaeobotany

We welcome feedback on TreeMos, how you use it, and how you found the experience. If you have any problems or requests, we will try to help. You can also register your download of the software there.

Citation

The TreeMos software is described in Moore, J.D., Allaby R.G. (2008) TreeMos: a high-throughput phylogenomic approach to find and visualise phylogenetic mosaicism. Bioinformatics 24(5):717-718.

The underlying algorithm is described in Allaby, R.G., Woodwark, M. (2007) Phylogenomic analysis reveals extensive mosaicism in the Human GPCR superfamily. Evolutionary Bioinformatics 3:155-168.

License

See license details. By installing or using this software you accept the terms of the license.

ReadMe.html version 1.0e 23/04/2008 J.D. Moore