Processing NMR Data With OS X/Linux Freeware

Volume 3: Installing NMRPipe on a Mac

by Josh Kurutz, Ph.D.

Technical Director of the Biomolecular NMR Facility

University of Chicago Last revised: July 20, 2006 Disclaimer: This guide is written in good faith by a user for other users, but the author cannot take responsibility for problems associated with using it. Be advised that the contents may not be error-free or comprehensive, though the author has attempted to make them as useful as practical.

2

Table of Contents. 1) Motivation .........................................................................................................................................2 2) Summary of instructions ....................................................................................................................2 3) Get your Mac ready ...........................................................................................................................3

A. Get X11 from Apple......................................................................................................................3 B. Prepare your terminal windows to emulate “tc-shell” windows. .....................................................3

4) Obtain the Necessary NMRPipe files .................................................................................................4 A. Obtain permission to download .....................................................................................................4 B. Download the files.........................................................................................................................5 C. Put the files in the right place.........................................................................................................7

5) Install NMRPipe................................................................................................................................7 6) (Create and) Configure your .tcshrc file .............................................................................................9 7) Check NMRPipe Folder Contents ....................................................................................................12 8) Try it out! ........................................................................................................................................12 9) Au revoir .........................................................................................................................................15

Table of Figures. Figure 1. An X11 window.........................................................................................................................3 Figure 2. Where to find "NetInfo Manager" ..............................................................................................4 Figure 3. Mac user info, including your shell type (needs to be “tcsh”). ....................................................4 Figure 4. First set of installation files available for download....................................................................5 Figure 5. Second set of installation files available for download................................................................6 Figure 6. The third set of files available for download...............................................................................6 Figure 7. Files in /Applications/nmrpipe, showing their permissions. ........................................................7 Figure 8. What you should see when the installation script starts working.................................................8 Figure 9. What you should see immediately after successful installation. ..................................................8 Figure 10. What I see with "ls" in my home directory. ..............................................................................9 Figure 11. What I see with "ls -a" in my home directory. ..........................................................................9 Figure 12. Setting TextEdit prefs to default to "Plain Text" documents. ....................................................9 Figure 13. The contents of the .tcshrc file necessary for NMRPipe..........................................................10 Figure 14. The error encountered when saving the file as ".tcshrc"..........................................................10 Figure 15. All the entries in your .tcshrc file you need to run NMRPipe and Dynamo. ............................11 Figure 16. Make sure you have a ".tcshrc.txt" file. ..................................................................................11 Figure 17. Make sure you changed the name correctly to ".tcshrc". .........................................................11 Figure 18. The contents of the nmrpipe directory after installation. .........................................................12 Figure 19. NMRPipe’s NMRDraw interface on startup. ..........................................................................13 Figure 20. Successful results for "which nmrPipe" ..................................................................................13 Figure 21. Results of typing "nmrPipe -help" ..........................................................................................14 Figure 22. Results of typing "man nmrPipe" ...........................................................................................14 Figure 23. The format conversion interface initiated by typing "varian". .................................................15

2

NMRPipe Installation Guide

1) Motivation NMRPipe is really great, but installing it isn’t exactly a “drag and drop” process. The instruction provided on the NMRPipe download website are quite comprehensive, but may be lethally confusing for people with limited experience installing programs in a unix/linux environment. Here I provide one good path for getting NMRPipe and its accessory programs working on a Mac running OS X. I know it works because I just got a new computer and downloaded all the freshest files from the NMRPipe site and got the program working for me. I captured my screen during the process, and these pictures make up most of this guide. There are certainly other ways of doing this, but this worked for me and it should work for you, too. Have fun!

2) Summary of instructions For those of you who don’t wish to read through the verbose explicit instructions, here’s a short summary of the things you need to do.

1) Make sure you have X11 2) Set your default shell to “tcsh” in the tool NetInfo Manager. 3) Download the files you need for NMRPipe from the NMRPipe website (startby by going to:

http://spin.niddk.nih.gov/NMRPipe/. To get to the download site, you’ll need to have gotten a username and password by emailing Frank Delaglio at his special email address, delaglio@spite.niddk.nih.gov.) For simplicity, all you need are: install.com, binval.com, and NMRPipe.tar. Don’t bother w/ the optional components because they’re included in the NMRPipe.tar bundle. If you wish, you can get the all-caps text files now, but they’ll appear once the program is installed anyway. If you can afford about 800 MB of hard drive space, download the sample data files “data.tar” and “valpha_all.tar.” I don’t know if it’s necessary or not, but I’d recommend downloading all the “Sample Data and Demo” files except “valpha.tar” and “valpha_time.tar”, which are enormous and redundant if you have “valpha_all.tar.”

4) Create the directory /Applications/nmrpipe and put all the downloaded files there. 5) Start X11, type “cd /Applications/nmrpipe,” then type “chmod +x *” to make all files executable. 6) The big moment: Type “./install.com /Applications/nmrpipe” and watch all the announcements in

your window. 7) If you don’t have one, create a .tcshrc file. Add the following lines to the end of your .tcshrc file:

if (-e /Applications/nmrpipe/com/nmrInit.mac.com) then source /Applications/nmrpipe/com/nmrInit.mac.com endif if (-e /Applications/nmrpipe/dynamo/com/dynInit.com) then source /Applications/nmrpipe/dynamo/com/dynInit.com endif alias nmrDraw "nmrDraw -Ws 1000 700" setenv NMR_CONT CORRECT

8) Exit X11 and restart it. 9) Type “nmrDraw”. You should see a big black and purple GUI. If so, you should be set! If not, you

need to try installing again, perhaps following the verbose instructions this time.

3

3) Get your Mac ready Before messing with NMRPipe, you’ll need to get your Mac prepared for performing unix-type tasks properly. You’ll be operating out of X11 windows that present you with a command line. First, you’ll need to get the X11 utility from Apple. Second, you need to configure these windows correctly. Possibly unbeknownst to you, these “environments” come in different flavors, and you need to use one that NMRPipe can work with. Once that’s taken care of, you can start really doing things with NMRPipe installation files.

A. Get X11 from Apple This is EZ. Go to: http://www.apple.com/support/downloads/x11formacosx.html Download it and install it in the usual Apple way. I put mine in /Applications/Utilities (the unix way of saying “the Utilities folder within the Applications folder.”) Once that’s installed, start it up to make sure it works. You should get a window that looks like this:

Figure 1. An X11 window.

B. Prepare your terminal windows to emulate “tc-shell” windows. The window you prepared above has a certain “flavor” to it. The environment you’re working in when using the command line is called a “shell.” The kind of shell we need is called a “c-shell”, but there are several kinds of c-shells. In the NMRPipe INSTALL file, Frank Delaglio warns us to not use the “sh” or “bash” shells. Pity, because your Mac defaults to using bash shells unless you change its prefs, which is the goal of this section. The shell that works well for me is the “tc-shell,” designated with “tcsh” and set up in part by the file .tcshrc. If you wish, you can leave these more complicated system prefs alone and simply type “tcsh” every time you open a new X11 window, but I think that it’s not worth the daily trouble. Open the program “NetInfo Manager,” found under “/Applications/Utilities” (Figure 2):

4

Figure 2. Where to find "NetInfo Manager"

Once your program is open, select /…/users…/(your username – mine is “jkurutz”). In the lower pane, scroll down until you see a line that reads “shell” on the left (Figure 3). You need this line to read “tcsh” on the right. Edit if necessary, and don’t be surprised if the program asks you to authenticate with an administrator’s password.

Figure 3. Mac user info, including your shell type (needs to be “tcsh”).

Once you’ve modified your shell type, it would be prudent to select “Deauthenticate” under NetInfor Manager’s “Security” menu choice. Close the NetInfo Manager program.

4) Obtain the Necessary NMRPipe files

A. Obtain permission to download The materials you need to install NMRPipe (and other related applications) are available for download from the NIH, but you need to get a username and password to access the relevant site. The NMRPipe home is at: http://spin.niddk.nih.gov/bax/software/NMRPipe/NMRPipe.html You won’t find the word “download” here. Under “Availability”, you find that you need to email Frank Delaglio to get a username and password to get to the download site. Here’s his email address, straight from the “availability” entry: delaglio@spite.niddk.nih.gov Just email him a polite note asking to download NMRPipe, and either he or some automated entity will reply with the address of the download website, a username for you, and a password for you.

5

B. Download the files Go to the download website described in the email. Plan on spending about 5-10 minutes gathering all the files you’re going to need for a full installation. This won’t be a simple “download the disk image and double click it” sort of job. There will be a bunch of files and, maybe, some text files to save.

Figure 4. First set of installation files available for download.

The above figure is a screenshot from the download page (Figure 4). The easiest thing to do is ignore the first section, “NMRPipe Installation Files.” Weird, huh, but it’s OK. NMRPipe.tar is a compendium of all the …tar.Z files in the first section. Now go straight to the “Simple” section and download “install.com,” “binval.com,” and “NMRPipe.tar.” At the most basic level, this is all you’ll need to get NMRPipe working. When clicking on the install.com and binval.com files, you may get text files in your window; either save them as text or right-click on the links and save the linked files to your desktop (or another handy place). If you want to look at pre-canned data to familiarize yourself with the program, you can download the files data.tar and valpha_all.tar. Be warned! These files are 160 and 691 MB, respectively!

6

Figure 5. Second set of installation files available for download.

Ignore the “Optional Components” section. The NMRPipe.tar file will ensure you get the three programs listed, and you don’t need to see the source code to use NMRPipe. If you want to look at the definitive installation instructions, look at the INSTALL file. Also, it’s always good to take a look at the README file. You don’t need to download them for reference, as they should be provided if you install using the NMRPipe.tar file.

Figure 6. The third set of files available for download.

The last set of file you’ll see is the “Sample Data and Demos” section. I went ahead and got everything, but you can skip it if you just need basic processing capability. Beware the 468 MB and 192 MB valpha.tar and valpha_time.tar files! The contents of “valpha_time.tar” and “valpha_hn.tar” appear to be subsets of “valpha_all.tar,” and I bet the same is true for “valpha.tar.” Everything else looks reasonable-sized. So if you want data, get “valpha_all.tar” and don’t mess with the other valpha files.

7

C. Put the files in the right place Now that you’ve got the files somewhere on the computer, you need to put them in the folder where you want NMRPipe to reside. I suggest you create a folder called “nmrpipe” in “Applications.” I recommend you use all lowercase letters because you may be needing to type the name of this directory over and over, and you can’t change it later or else you’ll confuse NMRPipe. Drag all the files you just downloaded into this new directory. If you want, you can create subdirectories within your nmrpipe directory and stash your sample data there, out of the way of the program’s files.

5) Install NMRPipe Detailed instructions for installing NMRPipe are in the file called INSTALL, but these instructions will work fine.

1) Start X11. You should see a window with a command line prompt that looks like Figure 1. 2) Change to the nmrpipe directory by typing “cd /Applications/nmrpipe.” 3) Type “ls” to lit the files in the directory. You should at least have install.com, binval.com, and

NMRPipe.tar here. 4) Change the permissions on these files so you can “execute” them by typing “chmod +x *”. 5) Type “ls –l” to see your files with their permissions. The left hand column should have bunches of

“x”s, as shown here:

Figure 7. Files in /Applications/nmrpipe, showing their permissions.

6) Now comes the big moment. Type “./install.com /Applications/nmrpipe”. You should see the following start scrolling up your window (Figure 8):

8

Figure 8. What you should see when the installation script starts working.

When it’s done, you should see this:

Figure 9. What you should see immediately after successful installation.

Pay attention to these lines! You’ll need to copy and paste both “if…endif” statements into your .tcshrc file. Either leave this window open and unaltered or copy the text you see now and paste it somewhere handy like a sticky.

7) Congratulate yourself if you saw what you’re supposed to.

9

6) (Create and) Configure your .tcshrc file You might think that installing the program was all you’d need to do run it. Not so in a unix environment! Before you can run NMRPipe you must edit an invisible file in your home directory. Its name is “.tcshrc”, and you can’t see it with your mac’s Finder. (It’s the antecedent “dot” that masks it, so .tcshrc ≠ tcshrc) Let’s assume you don’t have a .tcshrc file already. If you do, then you can skip ahead and edit it with the necessary lines. To find out whether you have one, go to your X11 window and type “cd” to bring you to your home directory. Type “ls” to see your files; the list should agree with what you see with Finder:

Figure 10. What I see with "ls" in my home directory.

Now try it again and give “ls” “-a”, so type “ls –a”. This enables you to see the previously hidden files, whose names start with “.”.

Figure 11. What I see with "ls -a" in my home directory.

This installation was done on a new computer with no other programs needing a .tcshrc file, so you can see I don’t have one. If you are familiar with using command line editors like “vi”, it might be easiest to create and edit a file with “vi .tcshrc”, but by default I’ll assume you don’t know how to use “vi”. Instead, you should start up “TextEdit” – NOT Microsoft Word! The file you’re creating needs to be free of invisible formatting marks that Word and even RTF (rich text format) documents have them all over. Start up “TextEdit,” and open its preferences panel. Under the “New Document” settings, make sure the “plain text” button is highlighted:

Figure 12. Setting TextEdit prefs to default to "Plain Text" documents.

10

With TextEdit configured this way, open a new document. Cut and paste the final message from the NMRPipe installation stream into the new plain text document.

Figure 13. The contents of the .tcshrc file necessary for NMRPipe.

Note that, if you installed your program in a folder other than /Applications/nmrpipe, or if these spellings or capitalizations are different what’s shown here, it’s critical that you use your own location, spelling, and capitalization in the .tcshrc file. Now save the document. Remember it needs to reside in your home directory. In my case, this is /Users/jkurutz. Here’s what happens when you try to give it the name “.tcshrc”:

Figure 14. The error encountered when saving the file as ".tcshrc"

TextEdit gives you this warning when trying to save “.tcshrc.” Don’t panic. You want the dot, so click the “Use “.”” button. You’ll see at the top of your document’s window that it bears the new name “.tcshrc.txt”. Don’t bother with changing this yet. Next, you should add the lines to your .tcshrc file necessary to run Dynamo. Even if you aren’t going to use it right away, it’ll be good to do it now while the relevant text is still in your X11 window. Copy the three lines concerning dynamo from the tail of the installation stream and paste them at the end of your .tcshrc.txt file (Figure 15). For good measure, you can add the alias shown to make the NMRPipe display adopt a reasonable size when it starts up, and you would be prudent to add the “setenv” line to ensure you can keep using nmrPipe after its expiration date (thus avoiding quite a shock a couple of years down the road)(Figure 15).

11

Figure 15. All the entries in your .tcshrc file you need to run NMRPipe and Dynamo.

Now save the file and close it. Go to an open X11 window and get to your home directory (i.e., “cd”). Type “ls -a” to see the invisible and visible files. You should see the file “.tcshrc.txt”:

Figure 16. Make sure you have a ".tcshrc.txt" file.

Now change the name “.tcshrc.txt” to “.tcshrc” by typing “mv .tcshrc.txt .tcshrc”. Then type “ls –a” to make sure you got it right.

Figure 17. Make sure you changed the name correctly to ".tcshrc".

If you see this and the contents of the .tcshrc file include the lines shown in Figure 15, you’re good to go!

12

7) Check NMRPipe Folder Contents It might help you if you looked at the new contents of your /Applications/nmrpipe folder. Just use the Finder and take a peek. Except for the “nmrpipe_data” and “nmrpipe_data+demos” directories, which I created to house the optional sample data, it should look like this:

Figure 18. The contents of the nmrpipe directory after installation.

Remember that I used the comprehensive NMRPipe.tar installation file, which included a bunch of extra files I don’t really need, like “nmrpipe.sgi6x.tar.Z.” I’ll delete the files ending in “tar.Z” sometime soon. They are important for installation, but not used for running the program. I wouldn’t delete other files except for sample data if I were you.

8) Try it out! You will fail the first time trying NMRPipe, but that’s OK. You’ll succeed in a minute. To get the graphical interface for NMRPipe, go to your X11 window and type “nmrDraw.” If you performed your installation like I did, you’ll see the message “tcsh: nmrDraw: Command not found.” To really get it to work, just exit X11, start it up again, and then type “nmrDraw”. You should see the following display (Figure 19) If you don’t see it, try logging out & logging back in or rebooting the computer, and make sure your default shell is “tcsh”.

13

Figure 19. NMRPipe’s NMRDraw interface on startup.

The official instructions advise you to try out a number of tests to make sure you’ve got things installed OK. Go ahead, it just takes a couple of minutes. From here on out, the commands I mention are to be executed from the X11 command line interface.

1) Type “which nmrPipe.” You should see this:

Figure 20. Successful results for "which nmrPipe"

2) Type “nmrPipe –help”. Remember this feature! It’s a great way to figure out how to get nmrPipe commands to work well. You should see the following (Figure 21):

14

Figure 21. Results of typing "nmrPipe -help"

Note that you get help on specific commands by typing “nmrPipe –fn (function) -help ,” e.g. “nmrPipe –fn LP –help” gives you information on the LP function. 3) “nmrPipe” on your system is now a unix command for which you can retrieve a manual entry by

typing “man nmrPipe”. You should see the following:

Figure 22. Results of typing "man nmrPipe"

4) Try starting up the conversion GUI. For Varian data, e.g., just type “varian” in the X11 window. You should get a pair of panels that look like this (Figure 23):

15

Figure 23. The format conversion interface initiated by typing "varian".

9) Au revoir If all that worked for you, then you’re all set to use NMRPipe! Please see the user guide for the program at the University of Chicago’s unofficial website: homepage.mac.com/jkurutz Follow the link to the “Guides and Protocols” page and download a “NMRPipe_guide” file for help with actually using the program. Feel free to take any of the other guides there. Have fun!