Jonathan Foster's Homepage

Astronomy compels the soul to look upwards and leads us from this world to another.

      ~ Plato, The Republic

Notes

These are notes about setting up various astronomy software and Python installations on Macs. Collected here for myself and other lost souls.

  1. LaTeX hyperef and emulateapj
  2. Mac astronomy software

LaTeX hyperef and emulateapj

This information has also appeared as a post on Astrobetter

If you want your paper on the arxiv/astro-ph to be read by everyone, it's worth your time to use emulateapj to format it. The emulateapj version will be shorter, look nicer, and have figures closer to the relevant part of the text. You can improve the experience of reading your article on the screen by adding hyperlinks in the article with the hyperef package. The basic idea of hyperef is simply to turn this:

into this:

with links to all the references in the bibliography and internal links to figures/sections/equations referenced in the text. As a bonus, you get nice formatting and active links to any urls (e.g. http links) that appear in your article simply by wrapping them in \url{http:www.mylink.com}.

Unfortunately, there are a few hoops to jump through. I hope you're already using \ref{sec:mysec} commands and labels to let LaTeX automatically take care of numbering your figures and tables. If you aren't, you should do so; hyperef is useless without such links. The first major problem you will notice is that the hyperef package links to the captions of figures. This isn't useful. If you click on a link to Figure 7 you want to be taken to the Figure, not the caption. You want clicking on the link to give you this:

and not this:

There are at least two options to deal with this problem. The caption package and the hypcap package. Unfortunately, neither works right out of the box with emulateapj! The caption package throws an error because both it and emulateapj are redefining the longtable environment. The hypcap package fails to work because the deluxetable environment (which makes nice figures) does not actually have a caption associated with the table. Option 1 is to ignore this error; your article will still compile fine. You can put something like this:

\nonstopmode %This makes us ignore errors

in your document header, but in my experience this still won't allow your document to compile on the arxiv. The better (if slightly less convenient) solution is to wrap your deluxetables (and any other environment that causes problems) with \capstartfalse and \capstarttrue

\capstartfalse
\begin{deluxetable}
...
\end{deluxetable}
\capstarttrue

Now your links from the text to Figures/Tables go the right place.

What about getting back? Typically if you're reading and want to reference a figure on another page, you'll immediately want to go back to where you were reading. This isn't something that hyperef enables, but your PDF browser might support this. There are "back"/"forward" actions/buttons in many PDF readers. See this discussion for information about your viewer. On a Mac, the command is cmd-[ (left square bracked) in Preview and cmd-left-arrow in Adobe Reader. Unfortunately, many of the PDF-viewers built into web browsers don't support this.

Now everything works and you can tweak to make things look they way you like. I like the following options:

\usepackage[backref,breaklinks,colorlinks,citecolor=blue]{hyperref}
\usepackage[all]{hypcap}
\renewcommand*{\backref}[1]{[#1]}

Note that you have to load hypcap after hyperref. The backref option and the extra \renewcommand combine to give you nicely-formatted links back from references back into your article like so:

Unfortunately these links go back to the section in which the reference is cited, not directly to the citation. This can be a little annoying if you have long sections in your article, but it's not so bad.

One final tweak is nice. I typically reference a figure with the command

see Figure~\ref{fig:myfig}

With hyperef, this will make the figure number a clickable link, but not the word "Figure". The easy fix to this is to replace all your \ref commands with the hyperef command \autoref and remove your hand-typed "Figure"/"Table"/etc. This step is obviously a little bit of a pain, since it involves some find-and-replace. But if you are going to take the time to do it right, you might as well do it really right.

In conclusion:

  1. Add the following lines to the top of your document
    \usepackage[backref,breaklinks,colorlinks,citecolor=blue]{hyperref}
    \usepackage[all]{hypcap} %This makes links go to figures, but breaks on deluxetables
    \renewcommand*{\backref}[1]{[#1]}
  2. Wrap any float environments that break hypcap (like deluxetable) in
    \capstartfalse
    ...
    \capstarttrue
  3. Wrap any external urls in \url
  4. (Optional) Replace all your Something~\ref{} commands with \autoref{}
  5. Remember that your PDF browser might have a back button to make using these links much nicer.

New Setup under 10.7

I have just recently set up a new computer under 10.7, starting from scratch. Here is what I put on the machine, ranging from very easy to more complex installations

Complicated Installs

  1. Scisoft for Mac OS X: Scisoft is a useful huge package of astronomy programs, libraries and utilities. I don't need all (or most) of this package, but it's useful to have around. The installation and setup is easy. I installed version Scisoft_OSX_macintel_2012.8.1.pkg and following the inspiration of the Urania blog, I updated the DS9 installation to version 7.0.2, for the cropping, save-and-restore and 3D visualization mostly. I also followed the advice to make an alias to load the Scisoft packages only when needed, making it easier to function with another Python distribution by adding this to my .profile (using BASH):

    	
    alias load_scisoft=". /usr/local/scisoft/bin/Setup.bash"
    
    

    Important (to me) programs in the Scisoft for Mac OSX distribution include WCSTOOLS, IRAF, CFITSIO, and the Astromatic Software Tools (SExtractor, SWarp, ec.). In this version of Scisoft for Mac OSX, the installation directory is /usr/local/scisoft.

  2. DS9 The latest versions of DS9 on the Mac are no longer self-contained Mac applications. I'm not sure what the latest version that supported this mode was, but it is now significantly out-of-date. The latest versions are only released as X11 versions. This is fine, in most cases, but it is annoying because you can no longer double-click on a FITS file to open it. I fixed this by creating an Automator application to run DS9 with an input file, and then telling the Finder to open all .FITS files with this Automator application.

    The key steps are as follows:

    • Launch Automator
    • Choose a document type as "Application"
    • Choose an action: Library>Utilities>Run Shell Script
    • Set the shell appropriately. My example is for bash.
    • On the right-hand field called "Pass inputs", select "as arguments".
    • Modify the code as follows:
      	
      . /usr/local/scisoft/bin/Setup.bash
      for f in "$@"
      do
      	echo "$f"
      	cd "$(dirname "$f")"
      	ds9 $f
      done
      
      
      The first line here intialized the Scisoft environment so that the script can find DS9. Automator scripts seem to run in blank profile -- none of your setup files in your own profile have any influence. If you had DS9 installed somewhere that is always in the default path, you would not need this step. In the rest of the lines, DS9 sessions are launched for all the input files (in this case, it will be all the FITS files your double-click) with the current directory set to the directory of the file (without this, the working directory for DS9 defaults to the home directory).
    • Save this as an application somewhere permanent. I called mine DS9.
    • Find a .FITS file and "Get Info". Choose to open this file with your automator application, and then hit the "Change All..." button underneath.
    This will allow you to double-click and open any .FITS file in DS9. Since I load scisoft only into my path when needed, but I want ds9 to be available all the time, I also did:
    	ln -s /usr/local/scisoft/bin/ds9 /usr/local/bin/ds9
    	ln -s /usr/local/scisoft/bin/ds9.zip /usr/local/bin/ds9.zip
    
    to always put ds9 in my path. This works poorly with multiple FITS files. DS9 opens for the first one, and then loads the second one when you close the first DS9 window.

  3. Enthought Python Distribution (EPD) EPD is a scientific distribution of Python with most of the useful/difficult-to-compile packages you might want to use for astronomy pre-compiled. It is free with an education e-mail address. Important packages are ipython, matplotlib, numpy, scipy, PIL, and pyfits. I installed version 7.3, which is Python 2.7.3. EPD configures your startup scripts so that its version of Python is the default, and things like pip and easy_install install into the EPD directories.

  4. Python Packages. The astropy project is coming along, but does not yet contain particularly useful packages for me. Therefore, I need to install things by hand. I attempted to install aplpy using the auto_install.py script at the aplpy homepage but ran into a problem. One of the required pacakges is pywcs, which is not part of EPD. pywcs needs WCSLIB, which (oddly) is not part of Scisoft, but out-of-the-box WCSLIB does not build under 10.7 (actually, out-of-the-box nothing builds on 10.7, but you can get the Apple Developer tools for free from the App Store and find the sort of hidden option to install command line tools). The problem seems to be a bug in Apple's version of GCC. CLANG works, however, so you can do

    	export CC=CLANG
    	sudo python auto_install.py --stable --extra
    	
    
    to actually get things to work. The --extra tag tells the script to instal atpy and vo as well. This script gets a bunch of useful astronomy python stuff installed.

    For the rest of the python packages I want, there is a choice between easy_install, pip, and manually installing packages. I went with pip, getting the get-pip.py script from pip-installer and then running sudo python get-pip.py to put it into the EPD Python installation. Yes, in theory I could have followed the recommendations and installed virtualenv instead, but since virtualenv is an admission of how complicated and borked Python installation and maintainence is, I thought I should suffer instead.

    Now, in theory, installing new packages will simply be a matter of

    	sudo pip install packagename
    
    
    and everything will work well under EPD. This leaves the Scisoft Python distribution as the abandoned orphan stepchild distribution. pyds9 and astLib installed easily by-hand using the normal
    python setup.py install
    

  5. Kvis Karma is now in maintainance-only mode. Following the README I grabbed karama-1.7.20-x86_64_Darwin-11.2.tar.bz2 from the ftp site and threw the contents in ~/Applications and added a symlink to this location as speficied in the README. I was not able to use the .karmarc file to set up the environment. This file existed, but was blank. Instead, I added the following to my .profile:

    
    PATH="/usr/local/karma/bin:${PATH}"
    export PATH
    export KARMABASE="/usr/local/karma"
    				
    This seemed to work, except I could not display axis labels. I also need to grab karma-1.7.20-common.tar.bz2 and replace the dummy symlink share with share/ from this folder (this contains the fonts). There were a bunch of other dummy symlinks present as well, so I replaced them with the real folders from the above common file. Everything works now.

  6. Montage. Fairly simple installation. Download, make, and then add to path (no make install is defined?). I put version 3.3 in ~/Applications.

  7. ASAP After failing to install ASAP manually (following these instructions) because of difficulty getting casacore installed, I realized that there as a short-cut and that a full version of ASAP is under the nicely-maintained CASA. This aborted attempt left me with gfortran installed in /usr/local/bin/gfortran (this is gfortran binary 4.6.2 from gcc.gnu.org), rpfits stuff installed in /usr/local/ subdirectories, and another copy of wcslib (4.15) in /usr/local/lib. The first two, at least, are useful. I suppose I also have cmake installed now (required for casacore, but not used successfully).

  8. CASA This was a very easy installation on 10.7. Drag the application to /Applications and then double-click and it completes installation on launch. ASAP commands are under the package sd, so old_asap.command is now sd.old_asap.command.

  9. FUSE/SSHFS I use FUSE and SSHFS to mount external ssh servers as local volumes. Installation is pretty straightforward package installers. Mount commands for my various servers can be defined as aliases. See this page for examples. Mount

    mkdir ~/mountpoint
    sshfs user@some-host.net:/home/user/ ~/mountpoint 
    -oauto_cache,reconnect,defer_permissions,negative_vncache,volname=somename
    
    Unmount
    umount ~/mountpoint
    
  10. Homebrew. In a quixotic quest to run the FITS viewer Ginga, I installed homebrew in order to install python-qt. This seemed to work (compiled successfully) but Ginga still won't see qt and run. Dunno why.

Easy Installs

  • Textmate 2: My text editor of choice. The alpha of Textmate 2 is quite stable, and is now open-source on github as well. I have a license for Textmate 1, so I was able to just download the Textmate 2 binary, enter my registration code, and begin editing files (such as this one).
  • Launchbar: Another personal choice. There are many fine launchers on the Mac (Alfred, Quicksilver), but I like Launchbar, and I bought a copy once upon a time.
  • MacTeX-2012: The best choice for LaTeX on the Mac. Simple (large) package installer, which includes applications like BibDesk, TeXShop, and LaTeXiT (plus some others I don't use).
  • iTerm2: Sure, the default Terminal in MacOSX is fine, but it lacks the features, flair and large memory requirements of iTerm2.
  • Inkscape
  • OmniGraffle
  • OmniGraphSketcher
  • GraphClick
  • The Unarchiver