ARB for Mac OS X: Phylogeny with Finesse!

[last updated, Jan, 2008] | Fink | ARB home | GreenGenes |


10.5 - LEOPARD

INTRO: This page is provided so that Mac users can install the phylogenetic database program called ARB. I have been running ARB on various mac computers since 2002 and it has been a wonderful and extremely useful tool for my research (microbial diversity in salt lakes). The german programmers keep on putting more exciting features into it, so it can be an incredibly powerful environment for bioinformatic analyses. The target plaftorm for ARB is linux, but this is a form of the unix operating system, like OS X, and so, with a bit of tweaking, the ARB source can be compiled to run macs. The Fink packaging system makes installation relatively easy for non-unix geeks. 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 YOU can set up ARB and use it without having to be C/C++ or unix shell programmers.

The porting was done by Ben Hines, and tested by me (Mike Dyall-Smith) before being made available as a Fink package in the unstable tree. The unix source code is found on the ARB home page at http://www.arb-home.de/ . For instructions on how to set up ARB under Tiger (10.4) and Panther (10.3), see my earlier web page.

To install ARB, you will need some knowledge of the unix operating system- 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. Use the installation disc (now a dual layer DVD), begin an installation but choose to do a custom install and select only these two items (developer tools, X11). [this link may also be useful]
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 (like the leap to 10.5, aka Leopard), 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 Leopard 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, ie:
   
   cd /sw/etc
   Then look at the files in this directory (ls -la) and you will see listed the fink.conf file (fink configuration)
   /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.
   
   *A problem I found with Leopard is that I couldn't selfupdate fink or install new programs because the curl command would time out, so the connection to remote servers would be cut before any files could be downloaded. If I manually copied the curl command into another terminal shell window, and modified the timeout period to 70 seconds, then files could be downloaded (but slowly). This was a real nuisance. A workaround, suggested by Alexander Hansen, was to use the wget command instead of curl. To do this you have to modify the 'fink.conf' file. Use the same commands as shown in point 7 above for access to the unstable tree, but here you need to add a new line to the file, and type in the line of text shown below.
   
   DownloadMethod: wget
   
   I put this line in just before the list of download sites in the file (e.g. Mirror-apache: http://www.apache.org/dist).
   
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. The Xfree86 version was used up to Tiger (10.4) but In Leopard they switched to another version of X11, from X.org. The change has caused some difficulties but the latest revision (2.1.1) works well enough. You should have installed X11 in step 2 above, but just to check, have a look for it in the Applications > Utilities folder. If present, then get the latest revision (2.1.1) from here.
    
    Put the Terminal.app icon in the dock, start it up, then issue the command 'xterm' and see if the X11 window comes up. While you have X11 running, uncheck the preference setting (X11 > preferences) 'disable shortcuts under X11. 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 . On my machine, Fink was unable to downlaod source files using the curl method, the default in fink. The specified timeout was 30 sec, and this was too short, so you would be asked to try again, and again... The Fink mailing lists helped me, with the suggestion to change the download method to wget. This took a little fiddle as wget was not already installed, and using the command 'fink install wget' then tried to download wget using, you guessed it, curl, which stalled. OK, you just copy the offending command and alter the timeout to 70 sec, which works, ie. 'curl --connect-timeout 70 -f -L -A 'fink/0.27.9' -O http://distfiles.master.finkmirrors.net/wget-1.10.2.tar.gz'. It downloads the source file to your home directory, then you drag it into the /sw/src directory and repeat the 'fink install wget' command in Terminal. Fink can then find the source tar file in the src directory, and process it. Once you have wget compiled, you can alter your fink.conf file to use it. Add the line 'DownloadMethod: wget' to fink.conf' (found at /sw/etc/fink.conf). I found wget to work like a rocket. Source files downloaded rapidly and could then be compiled and installed.
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 15-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. This may not work, 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. For some reason the command-key editing functions did not work. These are used to quickly move bases around sequence alignments while in the Edit window of ARB. I had to modify the actions of the Option and Command(apple) keys using an .Xmodmap file with the lines shown below (I got this from the MacOSXhints website). I know this works on an intel macbook, but the keycodes for these keys may not be the same on other keyboards. I will need some feedback on this. Assuming the keys are the same, make sure you are in your home directory (cd ~), create a new file with the name .Xmodmap, (the dot in the front is part of the name), using the command sudo pico .Xmodmap, then put the text shown below in it, save the file and exit (cmd-o, cmd-x). With these modifications I can use the option-arrow keys to bring bases to and from a position. All the other editing functions can be found by playing with option, ctrl, command and shift keys with the arrow keys. If someone finds a better solution, please let me know.
    
    ! Make 'Option' key be Meta and Command be Alt.
    ! See http://mail.gnu.org/archive/html/help-gnu-emacs/2003-05/msg00389.html
    clear mod4
    keycode 66 = Meta_L
    keycode 63 = Mode_switch
    add mod4 = Meta_L
    
18. Now you need to get sequence data files to use in the first place. If you have your own data, and are upgrading from a Tiger, then you may find your .arb files will not open or crash in the new version of ARB. I suspect the new version is more fussy about sequence names. I had to export all my data out of ARB and then re-import to a new arb library. It worked fine after that.
    If you haven't used ARB before, and you are a 16S rRNA sequence gatherer like me, then you can get files from the SILVA web site, or (and I used this one as a base), the GreenGenes website (which is a fantastic resource!). Note that you would need a massively powerful computer to handle the entire SILVA collection of sequences, so it is better to limit yourself to the sequences you really need.
19. OK, to fire up ARB you can either issue the command arb in a Terminal window or in an X11 window. If you use Terminal, the arb command will first start up X11 (this is the recommended method in Leopard), because ARB must run in an X-windows environment. [screenshot of main NT window, and Edit4 window]

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', This should not be a problem with the Leopard X11, I have not seen it during my testing, and it is recommended NOT to set the DISPLAY in a configuration file. However, this issue was a common problem in Tiger and before. Check your environment settings, ie. issue the command env and see if DISPLAY is listed. If for some reason you need to set the Display setting, try using the command:
export DISPLAY=:0.
If you can now start up ARB, then you may 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. This is a permissions issue, you need to change the permissions on this file so you can write to it.
To fix this, issue the following commands
cd /sw/share/arb/lib
sudo chmod g+w arb_tcp.dat

libGLw.1.dylib file not found (either a compile failure or failure ot open the Edit window on a compiled copy of ARB
The suspect for this is the Leopard 10.5.2 update, which REMOVED this file, along with a few others (see below) that ARB uses!! I had a copies of of the old files in an archvied version of Leopard. So I found them (e.g. locate libGLw.1.dylib), then moved them from the archived location to the right location in the new system files (e.g. to /usr/X11/lib/).The error message you get in the terminal session trying to use the ARB EDIT window, is given below. Now, someone else had the same problem and found that the reason for the lack of this library was that Xcode does not install it! His comments were, " I figured out that xcode's installer didn't actually install /usr/X11/lib/libGLw.dylib! I had to pkgutil --forget and re-install, as per http://www.uoregon.edu/~noeckel/LeopardIntelSetup.html " Either way, Apple does not seem to like the GLw files. All the files are still in the X11 SDK files in your Developer directory (e.g. /Developer/SDKs/MacOSX10.5.sdk/usr/X11/include/GL/GLwMDrawAP.h). A 'locate' command will find them. You can then copy (cp command) to the right locations (either /usr/X11/lib/, or /usr/X11/include/GL/, see below). Is there an easier workaround to this? Well, as another alternative here is a zip file with the files removed by Apple and needed by ARB. Unzip, put them back in the right places and you should be back in operation.

Error message in Terminal (on an installed version of ARB, after the 10.5.2 update), when trying to open Edit window:

Action: 'arb_edit4 -c default_configuration &'
dyld: Library not loaded: /usr/X11/lib/libGLw.1.dylib
Referenced from: /sw/share/arb/bin/arb_edit4
Reason: image not found

[Marin Costabel, Fink list, wrote, Feb 24, 2008] I don't know what the story behind this is, but the MacOSX-10.5.2
updater package runs a script named "removeOldPreLeopardX11" which has
the following lines:

rm -rf "$3/usr/X11/X11.app"
rm -rf "$3/usr/X11/bin/dumpkeymap"
rm -rf "$3/usr/X11/include/xorg"
rm -rf "$3/usr/X11/lib/X11/man/man1"
rm -rf "$3/usr/X11/lib/libGLw.1.dylib"
rm -rf "$3/usr/X11/lib/libGLw.dylib"
rm -rf "$3/usr/X11/include/GL/GLwDrawA.h"
rm -rf "$3/usr/X11/include/GL/GLwDrawAP.h"
rm -rf "$3/usr/X11/include/GL/GLwMDrawA.h"
rm -rf "$3/usr/X11/include/GL/GLwMDrawAP.h"

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 (noting the path to Safari on your computer):
Fig.browser: /Applications/safari.app/Contents/MacOS/Safari %f

You can also set the pdf reader to Preview.app using the same method.
Fig.pdfviewer: /Applications/Preview.app/Contents/MacOS/Preview %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 ('ls -la'). The second issue may be because the sockets are being used by another program (I have not had this issue in Leopard). 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/probe_server.arb RESERVED
ARB_PT_SERVER1 localhost:3031 arb_pt_server -D$(ARBHOME)/lib/pts/LSU_rRNA.arb
ARB_PT_SERVER2 localhost:3032 arb_pt_server -D$(ARBHOME)/lib/pts/SSU-rRNA.arb

PT server error 1.
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 2
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