LispMDS is a Common Lisp implementation of Antigenic Cartography developed at the Centre for Pathogen Evolution (CPE) at the University of Cambridge.
The following is known to work on OS X Yosemite (10.10.2), Sierra (10.12), and likely other OS X versions close to those. We do not yet have installation instructions for other flavors of UNIX or other operating systems.
These instructions also assume you're using the bash shell. If you have
no idea what that means, relax - you're probably using bash.
We run LispMDS under Allegro Common Lisp (ACL). LispMDS is unlikely to run out-of-the-box on other Lisp implementations.
If you're not at the CPE, you're on your own as to obtaining ACL. The install instructions below may be of some use, though.
If you're at the CPE,
download ACL
and save it to a file (we'll assume you save it to ~/Downloads/acl80-mac-intel.tar.bz2).
Open the OS X Terminal application and type the following commands to
install ACL (note that you may be asked to enter your password for the
second command):
$ cd /usr/local
$ [ -d acl80 ] || { sudo mkdir acl80; sudo chown $USER acl80; }
$ tar xfj ~/Downloads/acl80-mac-intel.tar.bz2
Then
download the license file
(here saved as ~/Downloads/acl80-mac-intel-enterprise.lic but, depending
on your browser, you may have acl80-mac-intel-enterprise.lic.txt) and
install it:
$ mv ~/Downloads/acl80-mac-intel-enterprise.lic /usr/local/acl80/devel.lic
If you are not working on LispMDS development, you'll need to get a copy of the LispMDS source code. First of all, create a Github account. Send either Barbara, Derek, Eugene or Terry your Github username and ask to be added to the team that can see the lispmds repository.
Follow the instructions for adding an ssh key and uploading it into Github. Once you've done that and you have been added to the lispmds team (last paragraph) you should be able to clone the Github repository:
$ cd /usr/local
$ [ -d lispmds ] || { sudo mkdir lispmds; sudo chown $USER lispmds; }
$ git clone [email protected]:acorg/lispmds
If you are working on LispMDS development, you will already have a copy
of the lispmds repository checked out. In this case, make a symbolic link
called lispmds in /usr/local that points to your locally checked out
git repository. E.g., via ln -s $HOME/ac/lispmds /usr/local/lispmds.
First, if you're not already using it, install Homebrew, an OS X package manager.
It's possible you'll need to change some permissions under /usr/local (I
think this happens on systems that had some /usr/local directories before
brew was installed). Run this command in any case (you may need your
password):
$ sudo chown -R $USER /usr/local/share /usr/local/lib
This step is redundant in 10.12, cask is installed with homebrew initially. And caskroom.io domain has been taken.
We make use of brew Caskroom, so you'll need that too:
$ brew install caskroom/cask/brew-cask
If you're using Mac ports, I (Terry) recommend you stop. You can tell by
looking at your PATH variable:
$ echo $PATH
This will show all the directories your shell searches when you run a
command. If you see /opt/local/bin listed in there, you're using Mac
Ports.
You can stop using Mac Ports by getting rid of any mention of
/sw/bin/init.sh in either (or both) your ~/.bashrc or ~/.bash_profile
files. If you don't know what you're doing, ask for help. If you know how
to use a text editor and you think you know what you're doing, comment out
any such lines (i.e., put a # at the start of the lines).
Add this line to your ~/.bashrc:
PATH="/usr/local/acl80:/usr/local/lispmds/bin:$PATH"
There shouldn't be any other lines altering your PATH in that file. If
there are, either merge them or delete the other line. If you don't know
how to do that, ask for help.
At this point it's probably easiest to log out and log back in. If you
repeat the echo $PATH command above, you should see no mention of
/opt/local/bin in your PATH.
You will be prompted for your password while the first command below is
running if brew needs to create /opt/homebrew-cask.
The second command below will present you a normal Mac OS X dialog to
install the XQuartz application that brew downloaded. You'll be asked to
accept the license and for your password. Note that the path name
/usr/local/Caskroom/xquartz/2.7.11/XQuartz.pkg may differ for
you. You may try to run find /usr/local/Caskroom -name XQuartz.pkg
to find where the XQuartz.pkg file is.
$ brew cask install Caskroom/cask/xquartz
$ open /usr/local/Caskroom/xquartz/2.7.11/XQuartz.pkg
Pay particular attention to the $ brew link -f --overwrite tcl-tk in the
following. If it fails or gives any kind of warning or error, wish will
not be linked in and starting pymol from the MDS gui will not work.
brew linkapps is deprecated. python should be perhaps installed via cask.
$ brew tap homebrew/dupes
$ brew install homebrew/dupes/tcl-tk --with-threads --with-x11
$ brew link -f --overwrite tcl-tk
$ brew install python --with-tcl-tk --with-threads --with-x11
$ # brew linkapps python - deprecated, do not run!
$ brew install gnuplot --with-x11
$ brew install imagemagick
$ brew install gs
To make sure the wish linking worked correctly:
$ type wish
wish is /usr/local/bin/wish
If you insted see /usr/bin/wish, the $ brew link -f --overwrite tcl-tk
command must have failed in some way. You have to get this right! If it
doesn't work, ask for help.
LispMDS can interact with PyMOL. Set that up via:
$ brew install brewsci/bio/pymol
It may be that your pymol relies on an older version of the GLEW library
(1.11) that you don't have installed (you may have 1.12). Try running
pymol at the terminal. If you see an error like the following
$ pymol
Traceback (most recent call last):
File "/usr/local/Cellar/pymol/1.8.4.0/libexec/lib/python2.7/site-packages/pymol/__init__.py", line 71, in <module>
import pymol
File "/usr/local/Cellar/pymol/1.8.4.0/libexec/lib/python2.7/site-packages/pymol/__init__.py", line 533, in <module>
import pymol._cmd
ImportError: dlopen(/usr/local/Cellar/pymol/1.8.4.0/libexec/lib/python2.7/site-packages/pymol/_cmd.so, 2): Library not loaded: /usr/local/lib/libGLEW.2.0.0.dylib
Referenced from: /usr/local/Cellar/pymol/1.8.4.0/libexec/lib/python2.7/site-packages/pymol/_cmd.so
Reason: image not found
you'll need to install version 2.0.0 of GLEW manually. Then:
$ cd /tmp
$ curl -OL http://downloads.sourceforge.net/project/glew/glew/2.0.0/glew-2.0.0.tgz
$ tar xf glew-2.0.0.tgz
$ cd glew-2.0.0
$ make
$ sudo make install
If curl command above fails, you may need to download glew-2.0.0.tgz manually,
go to the download page for GLEW 2.0.0
and download the glew-2.0.0.tgz file.
After this, you should be able to run pymol successfully.
If pymol causes your screen to flicker crazily try running pymol -M to
force mono mode. If that works, you can set an environment variable so that
the lisp MDS gui (when you finally run it - see below) will know to invoke
pymol with the -M flag. Put this into your ~/.bashrc file:
export MDS_PYMOL_FORCE_MONO=1
Then in the terminal:
$ source ~/.bashrc
Run the LispMDS GUI via:
$ /usr/local/lispmds/bin/mds-gui
It will be more convenient for you if you make a shell alias for this, or
put /usr/local/lispmds/bin into your shell's PATH. If you don't know
how to do that, ask a friendly system administrator for help :-)
When you're looking at a map window in the GUI, all the buttons on the left hand side should have equal width. If they do not, you are not running the correct version of wish. See the warning above about making sure brew links the right version of wish!
If changes have been made to LispMDS, and you're not a LispMDS developer, you can install them via:
$ cd /usr/local/lispmds
$ git pull origin master
Restart LispMDS (if you're already running it) for the changes to take effect.
If you are a LispMDS developer, you'll probably already know what to do.
Note that you can try out different branches just by switching to them (via
git checkout branch-name) in your local LispMDS repository.