Installation instructions for Twilight                   (DATE: 2012-10-17)
========================================

This document provides a guide for installing the side-packages needed to 
run Twilight, a program for visualizing ligands, which are in disagreement
with electron density. 

For full functionality, the Crystallographic Object-Oriented Toolkit (coot)
needs to be installed on your system. Please visit the coot web page 
http://www.biop.ox.ac.uk/coot for further instructions on installing coot.

The package is shipped as a BZIP-compressed tarball. Each supported platform
offers a great variety of utilities for extraction. We assume you are familiar
with your preferred extraction program, and nowadays on most operating systems 
a double click on the package will extract its contents.

The software depends on Python 2.X, and it was tested with Python 2.7. We
therefore recommend installing Python 2.7 on your system, unless it is already
present. See the following supported operating systems for a detailed
description on installation and launching.

For all Operating Systems, please unpack the Twilight archive into a suitable 
working directory of your choice. Then follow the remaining instructions.


Linux
-----

We have tested Twilight on Debian 6, aka 'Squeeze'. PyGTK is available for
most Linux distributions, and on many of them, along with Python, it is
already installed by default. Please see your distribution dependent package
manager for instructions on how to find/install packages on your system.

At the time of writing, Debian 6 (Squeeze) was shipped with Python 2.6 by
default. The Twilight application will nevertheless run on these systems and
emit some warnings as some negligible functionalities will not be
supported. To install PyGTK on this Linux distribution you need to enter the
following command (requires root privileges):

sudo aptitude install python2.6 python-gtk2

See steps 4 and 5 from the Windows installation instructions for testing and
launching the Twilight application. 


Mac OS X
--------

On Mac OS X, PyGTK is a little bit more complicated to install, as no
installer packages are available for this platform.

In case fink (http://www.finkproject.org/) is installed on your system, you
need to install the corresponding 'pygtk2-gtk-pyXY' package, where 'XY' is the
matching version number for your Python interpreter. For example, if you are
running Python 2.7 (as can be found out by typing 'python --version' in the
command line), you need to install 'pygtk2-gtk-py27' with the command 'fink
install pygtk2-gtk-py27'. See steps 4 and 5 from the Windows installation
instructions for testing and launching the Twilight application.

If you are using MacPorts (http://www.macports.org/), the following series of
commands should install PyGTK for Python 2.7. As we are not using MacPorts, we
could not test this approach. 

sudo port install python27
sudo port select --set python python27
sudo port install py27-gtk

Instead of setting up from scratch fink or macports, a Linux virtual machine
running Debian may be a time saving option, see the Linux section of the
README. We have successfully tested Twilight on several operating system
with VirtualBox, https://www.virtualbox.org.

See steps 4 and 5 from the Windows installation instructions for testing and
launching the Twilight application.


Windows
-------

Please have a look at the PyGTK web site, http://www.pygtk.org/downloads.html.
A Python interpreter has to be installed prior to installation of the PyGTK
package. The steps for installing PyGTK on Windows are summarized below: 

1. Find out if there is already some Python interpreter on your machine. Open
   a DOS-shell (Start->All Programs->Accessories->Command Prompt) and type
   'python --version'. If there is a message like 'Python 2.X.Y', remember
   that you have installed a Python interpreter with version number 2.X and
   skip the next step. If the command has not been recognized follow the next
   step.

2. Install Python. We recommend to install the 32-bit version of Python 2.7,
   which can be retrieved from http://python.org/download. Remember your
   Python version: 2.7

3. Install PyGTK. Go to the home page of PyGTK and download the all-in-one
   installer. You will also find a README file in the download directory for
   detailed explanations. Importantly, you need to download the matching
   version for your Python interpreter you have taken down in either step 1 or
   step 2. For example, if you have installed Python 2.7 on your system, the
   PyGTK package 'pygtk-all-in-one-2.24.2.win32-py2.7.msi' will install PyGTK
   2.24.2 for your 32-bit Windows.

4. Test your installation. Open a Command Prompt (see step 1) and change the
   working directory to the installation directory of Twilight. Type in the
   command 'python pygtktest.py', and if everything has been installed
   properly, a short message will appear in a PyGTK window. You are now ready
   to run the real application.

5. Run Twilight. If you are not yet in the installation directory of Twilight,
   change to it now. Type 'python twilight.py', and after a short loading time
   an empty Twilight window will appear. (In the future, you can also
   double-click on the file 'twilight.py' in your file manager to start the
   application in default mode.) Use the 'File' menu to load the ligand table
   file called 'ligands-2012-01-15.tsv'. 
   Additional options can be supplied to the Twilight program, please type
   'python twilight.py --help' for a comprehensive list of available
   options. Especially, if you are interested in exploring ligands in very good
   agreement with electron density, invoke Twilight with the command line
   option '--show-hq-rscc'. Sorting and grouping the table by RSCC value alone
   (default is by combined score S) is achieved by the command line option
   '--sort-rscc'. 
