Revision as of 11:02, 9 May 2011 by Zwickl
- Step 1: Get your dataset ready
- Versions 1.0 and later accept aligned data in a variety of file formats (Nexus, Phylip, Fasta). This version also includes rigorous support for features of the Nexus format such as assumptions blocks, which may include commands to exclude alignment columns or entire sequences.
- Step 2: Tell GARLI what you want it to do
- Graphical OS X version – (NOTE – GUI VERSION NOT YET AVAILABLE FOR VERSIONS after 0.951) Double click on the icon to start the program. On the File menu, choose Open and select your dataset. You will now see an interface with several tabs that you can use to tell GARLI what to output and how to run. Default values will already be entered, and they typically work well (at least for an initial exploratory run). The rest of this manual gives details on what the settings mean, which you might want to alter, and why.
- All other versions – Most GARLI versions are command-line programs, and have no interface at all. All directions to the program are provided through a text-based configuration file, which by default is named garli.conf. You will need to open this file in a text editor (Textedit, BBedit, TextWrangler, Notepad, vi, emacs, etc.) to make changes. In the file you will see a series of fairly cryptically named options. The only thing that must be changed in the file is to enter your dataset name as the datafname. You should also change the ofprefix setting to give the program a prefix to be added to the beginning of output filenames. The default values for most settings should work well, at least for an initial exploratory run. The rest of this manual gives details on what the settings mean, which you might want to alter, and why. Make sure that you save the configuration file after making any changes.
- Step 3: Run the program
- Graphical OS X version – Simply press the Run button. The program can be terminated prematurely, but should ideally be allowed to decide when to stop on its own.
- Windows version – Double-click on the executable to start it. It will automatically read the garli.conf file and start. (If you like, you may also start the windows version from the command line, which allows for executing batch scripts. See the FAQ.)
- All other versions – Linux and non-graphical OS X versions must be started from the command line. From a terminal or shell window, get to the directory containing the executable and your dataset. Type “./Garli-2.0” (or whatever the executable you have is named). The “./” is important, and tells the computer to look for the executable in the current directory. If you know what you are doing, you may of course put the executable somewhere in your path and omit the “./”. (See the FAQ for details on performing multiple runs in batch)
- Step 4: Interpret results
- A number of important files are created during and after a run. Assuming that the output file prefix is “run1” (“ofprefix = run1” in the config file), then the files will be:
- run1.screen.log – This contains all information output to the screen during the run. Things of interest include a summary of the chosen model of sequence evolution, the final model parameter estimates and a summary of the results of multiple search replicates.
- run1.best.tre – This will contain a Nexus trees block with the best scoring result across all search replicates, with optimized branch lengths. For nucleotide data it will contain a Nexus PAUP block that can be used to load GARLI’s model parameter estimates into PAUP.
- run1.best.all.tre – If multiple search replicates were done (searchreps > 1 in the config file), this will contain a Nexus trees block with the best tree found by each of the individual replicates.
- You should always either perform multiple search replicates within a single program execution (searchreps > 1 in the config file), or do multiple program executions to verify the results that you obtain. If doing multiple runs, be sure to first change the ofprefix setting in the config file (or the “Prefix for output files” in the GUI version) so that you don’t overwrite your previous results. The search algorithm of GARLI is stochastic, so it is entirely possible that another run with the same settings could give a different result (although hopefully not). You may also try specifying a starting tree or changing other settings. Look through the FAQ for more info.