ARB for Mac OS X 10.4: Phylogeny with Finesse!

INTRO: This page is provided so that Mac addicts can get the phylogenetic database program called ARB up and running on OS X 10.3 and 10.4 (Tiger). Since these are now obsolete versions, I am concentrating on 10.5 now. In any case, have been running ARB on a number of iMac (400-800mHz, intel) machines since 2002 and it has been a wonderful and extremely useful tool for my research (microbial diversity in salt lakes). The ARB program is a large collection of UNIX programs, and is primarily aimed at linux users. However, it has been packaged as part of the Fink project. What is Fink? "The Fink project wants to bring the full world of Unix Open Source software to Darwin and Mac OS X. We modify Unix software so that it compiles and runs on Mac OS X and make it available for download as a coherent distribution." [see fink website for more]. This means that intelligent non-geeks can set up ARB and use it without having to be C/C++ or unix shell programmers.

These instructions refer to the OS X port of the unix program ARB for handling sequence data in a phylogenetic tree environment. The conversion was done by Ben Hines, and tested by me (Mike Dyall-Smith) before being made available as a Fink package on June 18, 2002. The unix source code is found on the ARB home page at http://www.arb-home.de/ . Contributors to the instructions below include Todd Black and Tim Beckenham, who provided a nice guide (pdf format) for setting up ARB on OS X 10.3.

You will need some knowledge of unix - not a lot, but a rudimentary grounding. Buy a book, look up web tutorials, anything. You need to be able to do simple things like know your way around directories, copy (cp) and edit files (e.g. pico editor), change privileges (chmod), have superuser (sudo) status, know about paths, listing (ls) directories and editing 'invisible' files (like .profile). Get familiar with the Terminal and X11 applications (Utilities folder). Having a unix person around can really help here.

Main points:

1. Update your OS X if necessary, then do a disk repair (or repair permissions) using disk utility (Applications > Utilities > Disk Utility)
2. You will need to install the developer tools (=Xcode) and the X-windows application X11. These are on the installation disk but are not installed by default. If they are not installed then you need to do a custom install. Put in the installation disc that has Xcodes, select just these two items, and install them.
3. To get the OSX-ported ARB package (along with the many supporting programs that are needed to run ARB), you will need to install the Fink management program. I suggest you go to the Fink site and read about it. Fink will handle program source file downloads, compiling and installation, updates, removals etc., and it is designed to be very easy to use. It can get a bit messy when OS versions go through major updates (10.3 > 10.4 and now, almost 10.5), but you don't have to upgrade your installed fink applications, they usually work fine under the new operating system. OK, so click on the link below.
   http://fink.sourceforge.net/
4. Read the Fink home page intro and news pages first, then the 'Read more...' page. There is a FAQ if you are interested or want answers to basic questions.
5. Go to the 'download' page to get Fink (0.8.1). The step-by-step instructions are easy to follow. Select the type of machine you have, either the PPC (Power PC) or the new intel chip processors. In step 5 it says you need to open Terminal.app and run some commands. If you don't understand any of this, read up the terminal application and about the unix command line. The step 6 of fink installation mentions installing packages, including Fink Commander, or apt-get. Often there is no binary for ARB, and you have to compile it on your machine, so you need to read the next part of this page; installing and using Xcode and X11. For those with no unix knowledge: you should get familiar with the 'Terminal' and simple unix commands. The arb discussion list can help with queries of this nature, but check out the web for tutorials (eg. 1, 2).
   
   For initial installations of Fink creates the correct path settings (/sw/bin/pathsetup.sh ). The default shell in Panther is 'bash'. If you know what you are doing and want to do this manually, the login command you need is the following (for bash):
   source /sw/bin/init.sh
   - and would go in the .bashrc file.
6. Once Fink is up and running, you can issue very simple terminal commands like 'fink install xxx' where xxx is the program of your desire! (well, at least from the long, and ever increasing list of available software). It is amazing how many applications are available (use fink list to see them all). More info on fink can be had by the man fink command (the documentation or manual for fink). Fink operations can also be handled with 'FinkCommander'. It is worth trying out if you are worried by terminal commands.
7. ARB version: the most recent version is in the unstable tree. Fink won't let you at the unstable packages without your explicit agreement. Unstable, means the programs in this section of the fink archive are relatively untested (or completely untested). They can't give an assurance of how well the software works as they haven't had enough feedback. However, if you are only installing ARB, then the unstable version seems to be OK as far as Ben and I can tell. It is not an 'official release' by the ARB programmers, so be careful to backup important files. To allow fink to access the unstable packages, you must edit the /sw/etc/fink.config file exactly as described in the fink site (this is a good time to read the Fink FAQ). Using Terminal, change directory (cd) to:
   
   /sw/etc/fink.conf
   
   To edit this file you need to use sudo command. When you issue a sudo command you will be asked for your password before it will continue, i.e.
   sudo pico -w fink.conf
   Look for a line starting with "Trees:" It should look like
   Trees: local/main stable/main stable/crypto local/bootstrap
   Modify it to look the same as below, with the added unstable entries (in bold)
   
   Trees: unstable/main unstable/crypto local/main stable/main stable/crypto local/bootstrap
   
   Save (ctrl-o) and exit (ctrl-x) the fink.config file using the commands in brackets, ie. hold down the ctrl key and the o key at the same time, etc.
8. Configure and Update Fink: Once Fink is installed and the unstable tree opened, issue the command fink configure and you will get a series of questions put to you about how to get and handle files from the fink web site, where your system should look for fink files, etc. On my machine it didn't want to look for tarballs (archived files) in /sw/src and I had to type that in as my preferred option. I set the download sites for various programs to be close or within my own country, and you can set things like firewall proxies, etc. You will know if all is well if you can do a fink selfupdate command and it updates itself. You might find it fails to connect and gives you the option of trying another mirror site (because they are all so busy); try a few others and it should eventually work.
   Note: From my home computer, I was never able to get around a firewall that was set in my workplace server (even if I tried to get round it using the instructions in the Fink FAQ), so I had to copy my entire /sw directory at work (where I could update fink) and use that to replace my home version. Recently I have switched to a commercial ISP and I can update Fink fine.
9. Issue the command fink update-all
   After updating Fink, this will update all the core programs used by Fink, including the unstable ones.
10. Issue the command fink index to force Fink to update all the unstable packages
11. ARB runs in X-windows (the unix window environment). In 2003, Apple released its own version of the Xfree86 windows environment, simply called X11. You should have installed this in step 2 above, but just to check, have a look for X11 in the Applications > Utilities folder. Double click to open the application and see that it gives a terminal window that you can use like Terminal. While you have X11 running, uncheck the preference setting 'disable shortcuts under X11' (X11 > preferences). If you have to install X11, remember to alter this pref. setting later or you will have difficulty editing sequence alignments. Note, ARB only runs in an X11 window, not in a Terminal.app window.
12. Install ARB: If you are not in the home directory, go home (cd ~) and then issue the command fink install arb .
13. If all is well, it will ask to install about 24 supporting packages after which your screen should be full of compilation text that will continue to scroll down for - well, a long time. Go and do something useful, looking in every 30 min to see if it has hit an error.
14. Modify the etc/hosts file to give arb a static hostname for the computer to work with. The Rendezvous name works OK, and you can find it at: System Preferences -> Sharing. Under the Computer Name entry box there is an edit button. Click that and it will show you what your local hostname is, eg. something like 'computername.local'
    
    Start up a terminal session and enter the commands....
    cd /etc
    sudo pico –w hosts
    You will see something like this....
    #
    # Host database
    #
    127.0.0.1 localhost
    255.255.255.255 broadcasthost
    ::1 localhost
    
    Make the following change, indicated in bold ( the trailing “.” is meant to be there)
    #
    # Host database
    #
    127.0.0.1 localhost
    127.0.0.1 computername.local.
    255.255.255.255 broadcasthost
    ::1 localhost
15. Recently, this didn't work for me, and I found another method to set this. If you find that updating the PT-server gives an error (repeated several times) that it can't connect to SomeHostName (see the 'troubleshooting' guides at bottom of page), simply add the hostname it is complaining about to the end of the first line of the hosts file, ie. change the initial file to:
    # Host database
    #
    127.0.0.1 localhost SomeHostName
    255.255.255.255 broadcasthost
    ::1 localhost
    
16. Save that and close the terminal window.
17. Now you need to get sequence data files to use in the first place. If you haven't used ARB before, and you are a 16S rRNA sequence gatherer like me, then you can get files from the ARB web site, or (and I used this one as a base), the GreenGenes website (which is a fantastic resource!)
18. OK, to fire up arb you must start X-windows first, eg by starting Apple X11. It produces an Xterm window that you can type commands into. Enter the command arb and hit return:

If you are lucky, you may see the first window of ARB come up that asks for a file. Use the directory to find your XXX.arb tree file and hit the 'open' button and it should bring up the main ARB_NT window with a beautiful tree. At this point you need to read about ARB at the home page, and work out how to build your PT-server, align sequences, import new sequences, edit them, etc. The web site at ARB now has links to some marvellous tutorials. To use the probe or alignment options you will need to make or update your PT-server. This can cause problems (see below for solutions).

TROUBLESHOOTING

'Can't open display', you may need to set the DISPLAY environment setting. Check your environment settings, ie. issue the command env and see if DISPLAY is listed. If not, try using the command:
export DISPLAY=:0.
If you can now start up ARB, then you need to add the display command to one of your setup files (.login, .profile, or .bashrc)

arb_tcp.dat error
By default the arb_tcp.dat is read only. So when you go to update it via Probes -> PT Server
Admin -> Create Template it won’t let you edit it.
To fix this, issue the following commands
cd /sw/share/arb/lib
sudo chmod g+w arb_tcp.dat

Build error, missing png.h and tiffio.h
Recently (2008), someone was trying to install ARB on a 10.4 system. They found that ARB would not build because it lacked these files. The solution was to manually install libpng3 and libtiff, then to install ARB. ie. do
fink install libpng3
fink install libtiff
fink install arb

Xfig Helpfiles
XFig tries to open up its html help files in Netscape. To modify this behaviour you need to
change the settings in the Fig file which can be found at /sw/etc/app-defaults/
sudo pico -w Fig
Initial Settings:
Fig.browser: netscape –remote ‘openFile(%f)’ || netscape %f
Change to:
Fig.browser: /Applications/safari.app/Contents/MacOS/Safari %f

Searching the World Wide Web
In arb there is an option to search the world wide web. You can find it under Properties ->
Search World Wide Web (WWW). This link still refers to Netscape. Currently working on
replacing this with mozilla. (any suggestions out there??)

'fink command not found'
After installing some program or other my path settings for ARB were removed. Using the 'env' command I could see that the path settings no longer included sw/bin, so a 'fink selfupdate' command came back with an error message saying that this command could not be found. How to repair the path settings (easily) on an existing ARB installation? Use the command '/sw/bin/pathsetup.sh' and all should be put right again.

Extra programs to install
Install ghostview
Install this pdf/postscript viewer application to add extra functionality to arb.
fink install gv

PT-SERVER ISSUES : I'll assume you have been able to open up your database, and can see your tree. Next, to configure ARB so that it can digest this sequence database and be able to find probes or sequencing primers it needs to access the PT-server.

The PT-server is a kind of scratch file that ARB uses to store information about sequences and to greatly speed up searches for probe sequences. It also seems to cause many people grief, and there are a lot of useful posts about it on the ARB discussion list. Typically, you find that when you try to check or update your PT server you get errors that you don't have permission to write to it, or you cannot connect to the socket for that server. The first problem is sorted out quickly by finding if you have read and write permission. The second is often remedied by not using the top two sockets that are offered in the PT-server admin window (see below). After you have successfully 'updated' your PT server, it should contain files with suffixes .ARM and .ARF.

Part of the PT-server setup is specifying a port/socket for each PT-server you want to use. For this you have to edit the file arb_tcp.dat, hidden at /sw/share/arb/lib, so the full path is: /sw/share/arb/lib/arb_tcp.dat

Open this with the sudo pico command, ie. sudo pico /sw/share/arb/lib/arb_tcp.dat

and edit the names to something more descriptive than 'usr1.arb', ie. the end of the lines

ARB_PT_SERVER0 localhost:3030 arb_pt_server -D$(ARBHOME)/lib/pts/NoUse1.arb
ARB_PT_SERVER1 localhost:3031 arb_pt_server -D$(ARBHOME)/lib/pts/NoUse2.arb
ARB_PT_SERVER2 localhost:3032 arb_pt_server -D$(ARBHOME)/lib/pts/usr3.arb

PT server issue 1 : I find I can't use the top two sockets (so I renamed them NoUse1.arb, NoUse2.arb), so use the third one, or any below that. I think the first two sockets are already in use for some function (?). On my installation, I edited the 3rd socket (usr3.arb in the example list above) to SSU_rRNA.arb (they must end in .arb). OK, now you need to select this socket from the PT-server admin in the Probes menu, and then 'update server'. If you have a problem, this is the time you will find out. Commonly, people find they get an error along the lines that ARB can't find the PT-server. Try using a different socket. Check you have the corrent level of priveleges to read and write to the PT-server disk. 'Check server' always gives me a 'permission denied' response that is not very useful.

PT server error 2.
ARB Error: When saving /sw/share/arb/lib/pts/user1.arb~: Permission denied.
To fix this, check permissions on /sw/share/arb/lib/pts.
drwxr-xr-x root admin pts
Change to
drwxrwxr-x root admin pts
With the following commands
cd /sw/share/arb/lib
sudo chmod g+w pts

PT Server error 3
If you go Probes -> PT server Admin ->Check server you may get:
Trying ::1
connect to address ::1 refused
Trying 127.0.0.1
connect to address 127.0.0.1 refused
....repeated several times...
Even with this error the PT Server may still work - and complete its calculations.

Other errors? Check out the fink FAQ pages for the most common problems, then search the ARB discussion list archives for postings on your issue. If nothing relevant is found, ask on the fink users discussion list.

It may seem a lot of mucking around, but I confess that ARB rapidly becomes addictive! There are many, many features. I have been using it regularly for a few years and I am constantly finding out new things it can do. Same with OSX. The combination of unix power and Apple ease of use is fascinating. Try dragging a mac file or folder into the Terminal (not X11) and see the path come up; saves a lot of hassle for copying files. Spotlight is a lot easier for me than 'grep'. You can process the trees through a powerful graphics package called XFIG (from within ARB), and you have ghostscript and ghostview to handle postscript and pdf files.

I may have left out something critical but at least it is a start. I got ARB up and running in a day, on an old iMac 400Mhz. I have it also running on a lovely G4 iMac (the 'desk lamp' flat screen model) and a recent intel iMac.

Good luck, and happy treeing! Remember, the ARB discussion list is there to help you.

Mike Dyall-Smith
Department of Microbiology and Immunology,
University of Melbourne, Australia
email: mlds (AT) unimelb.edu.au