
=====================================================================
   DISCO
=====================================================================

Compiled binaries distribution

v1.0
2011-05-24

Jeffrey W. Martin and Bruce R. Donald
disco@cs.duke.edu

Copyright © 2011 Bruce Donald Lab, Duke University



=====================================================================
   LICENSE
=====================================================================

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA

Contact Info:
	Bruce Donald
	Duke University
	Department of Computer Science
	Levine Science Research Center (LSRC)
	Durham
	NC 27708-0129 
	USA
	brd@cs.duke.edu

<signature of Bruce Donald>, May 2011
Bruce Donald, Professor of Computer Science


=====================================================================
   CITING DISCO
=====================================================================

When publishing work that uses DISCO, please cite one of the following:

[1] Jeffrey W. Martin, Anthony K. Yan, Chris Bailey-Kellogg, Pei Zhou, and
Bruce R. Donald. A graphical method for analyzing distance restraints
using residual dipolar couplings for structure determination of symmetric
protein homo-oligomers. Protein Science, 20(6):970–985, 2011.

[2] Jeffrey W. Martin, Anthony K. Yan, Chris Bailey-Kellogg, Pei Zhou, and
Bruce R. Donald. A geometric arrangement algorithm for structure deter-
mination of symmetric protein homo-oligomers from NOEs and RDCs. In:
Proceedings of The Fifteenth Annual International Conference on Research in
Computational Molecular Biology (RECOMB), Vancouver, BC, 2011. Springer
Berlin, pages 222–237.


=====================================================================
   INSTALLATION
=====================================================================

DISCO has been tested in and works in the following
operating systems and architectures:

	Linux (x86_64/amd64)
	Windows 7 (64bit)

It is likely DISCO also works with he following operating
systems and architectures, although they have not yet been tested:

	Linux (x86)
	Windows 7 (32bit)
	Windows Vista, XP, 2000 (32bit, 64bit)

Before running DISCO, the following prerequisite software must be installed:

	Java v6+ JRE                     http://www.java.com/en/download/
	Python v2.6 (not 2.7!)           http://www.python.org/
	JPype v0.5.4+ for Python 2.6     http://jpype.sourceforge.net/
	Xplor-NIH                        http://nmr.cit.nih.gov/xplor-nih/

Wait, Xplor-NIH is not available for Windows!

	Yes, it's true. When run on Windows, DISCO will do everything except the
	final structure minimization. The resulting structures can then be minimized
	using the software of your choice.

Should I use the 32 bit or 64 bit versions?

	If you have a 64 bit OS, you should use the 64 bit versions. The 64 bit
	versions allow DISCO to address more than 2GB of memory. Two of the example
	scripts included with this distribution require more than 2GB of memory, and
	so require the 64 bit versions.
	
	If you don't have access to a 64 bit OS and you must use a 32 bit OS along
	with the 32 bit versions of the prerequisites, then DISCO will only be able
	to address up to 2GB of memory. DISCO will not have enough memory available to
	run two of the example scripts:
	
		discoProteinScienceGb1Reassigned.py
		discoRecombGb1.py
		
	To run all of the example scripts, the 64 bit versions are required.

Please make sure the "bitness" of Java, Python, and JPype match. For instance, if
you've installed the 64 bit Java, you must also use the 64 bit versions of Python
and JPype.

For Linux users, your distribution will most likely already have packages for
Java, Python, and JPype. Your distributon's package manager will offer the
simplest option for installation. Xplor-NIH, however, will require manual
installation. Additionally, linux users will need to install the CGAL package.
Alternatively, one could download it from the CGAL website and install it manually:

	CGAL v3.6.1+                       http://www.cgal.org/

For Windows users installing the 64 bit versions of Java and Python:

	Sadly, JPype is not available in 64 bits for windows, so I've taken
	the liberty of compiling a 64 bit version from the JPype sources. See the
	following folder in the distribution for instructions on how to install
	the 64 bit version of JPype:
	
		extra/jpype64

After installing Xplor-NIH, make sure the directory for the pyXplor executable file
has been added to the PATH environment variable. One could alternatively add a symlink
for pyXplor to ~/bin, /usr/local/bin, or /usr/bin.

If pyXplor is not available "on the PATH," DISCO's structure minimization routines
will fail and DISCO will not finish successfully on Linux.

After the above software has been installed, unpack the files in this archive
to your favorite folder. We'll refer to the folder you choose as the "installation folder"


=====================================================================
   WHAT COMES WITH THE DISCO DISTRIBUTION
=====================================================================

This DISCO distribution comes with pre-compiled binaries for your operating
system and architecture which makes it possible to run the DISCO procotols on
your system of interest.

In addition, DISCO comes with fully-automated scripts to perform analyses on
the DAGK and GB1 proteins as previously described in Protein Science[1] and
RECOMB[2]. These seven demo scripts, when run, will write their results to the
output directory in the installation folder. Each script is described in more
detail below.

	1. discoProteinScienceDagk.py

		This script performs the analysis of DAGK as described in our
		Protein Science paper[1].

	2. discoProteinScienceGb1.py

		This script performs the analysis of GB1 as described in our
		Protein Science paper[1] using the orignally-assigned NOEs.

	3. discoProteinScienceGb1Reassigned.py

		This script performs the analysis of GB1 as described in our
		Protein Science paper[1] using NOEs with simulated atom ambiguity.
		
		NOTE: This script requires the 64 bit versions of the DISCO
		      prerequisites to run.

	4. discoRecombDagk.py

		This script performs the analysis of DAGK as described in our
		RECOMB paper[2].

	5. discoRecombGb1.py

		This script performs the analysis of GB1 as described in our
		RECOMB paper using the NOEs with simulated atom ambituity.

	6. discoDimerAlignmentTensorAxis.py

		This script is a utility script that determines which axis of
		the alignment tensor describes the symmetry axis orientation
		for dimeric protein complexes.
	
	7. discoGb1ReassignNoes.py

		This script is a utility script that performs the atom ambiguity
		simulation and reassignment for NOEs.
		
		NOTE: This script requires the 64 bit versions of the DISCO
		      prerequisites to run.


=====================================================================
   RUNNING THE DEMO SCRIPTS - Windows
=====================================================================

Open the command prompt and navigate to the DISCO installation folder:

	> cd C:\path\to\installation\folder

To run any of the demo scripts, type the following into the command prompt:

	> python discoXXX.py

where discoXXX.py is the name of one of the python demo scripts included in
the distribution.

NOTE: You may need to specify the full path to the python interpreter.
For example:

	> C:\python26\python.exe discoXXX.py
	
The results of DISCO will be written to the output folder in your
installation folder.


=====================================================================
   RUNNING THE DEMO SCRIPTS - Linux
=====================================================================

Open your favorite terminal and navigate to the DISCO installation folder.

	$ cd /path/to/installation/folder
	
To run any of the demo scripts, type the following at the terminal:

	$ python discoXXX.py

where discoXXX.py is the name of one of the python demo scripts included in
the distribution.

The results of DISCO will be written to the output folder in your
installation folder.


=====================================================================
   RUNNING DISCO ON YOUR SYSTEM OF INTEREST
=====================================================================

To run DISCO on your system of interest, make a copy of one of the demo scripts
to use as a starting point. Read the descriptions of the input parameters
carefully and then modify them as needed. DISCO can then be run on your system of
interest by running python on your modified script instead of the demo script.

These demo scripts should be sufficient to run the DISCO protocols for most
systems. However, if your system is significantly different from DAGK and GB1,
these scripts may require additional modification to work beyond just tweaking
the input parameters.

For this reason, DISCO was designed with a Python scripting layer on top
of a modular and powerful Java library. The Java library provides algorithms to
perform all of DISCO's tasks as well as more general manipulations of protein structures
as well as NMR data. If the demo scripts provided in the distribution are not
sufficient to run DISCO for your system, it is possible to modify the DISCO protocols
directly by editing a copy of the disco.py python module (found in the lib folder).
Python modules can be edited using a simple text editor and do not require explicit
compilation. Hence, the high-level operation of DISCO can be customized without
recompiling any of the Java or C++ libraries.

If more control is needed (or completely new functionality is desired),
DISCO is entirely open-source, so one can also modify the Java and C++ sources. See
the DISCO website to download the full source package at:

	http://www.cs.duke.edu/donaldlab/software/DISCO/


=====================================================================
   TROUBLESHOOTING
=====================================================================

When I try to run DISCO, I get the following error. How can I fix it?

	RuntimeError: Unable to start JVM at src/native/common/jp_env.cpp:54

This error can be thrown when the JVM fails to start. One possible reason for this
is that not enough memory is available to initialize the JVM heap. You can change
how much memory the JVM requests by modifying additional settings in lib/disco.py
Try changing JvmMaxHeapSize to a value that fits within the memory currently
available to your operating system.


When I try to run DISCO, I get the following error. How can I fix it?

	Msrs computation worker N ended with an error!
	...
	java.io.FileNotFoundException: C:\path\to\installation\folder\output\msrs.dat (The system cannot find the file specified)
	
This is somewhat of a generic error that simply indicates the worker process that
computes the MSRs has crashed. There may or may not be an additional error message above
this one explaining what went wrong. If there is no additional error message, then
the most likely cause is running out of memory. Sadly, this error originates from a library
that is called by DISCO, so we don't get much control over what happens when the error
occurs. You're most likely to see this error message on the GB1 reassigned NOE example scripts,
since it computes the most annuli/circles, and hence computes the largest arrangement
among the example scripts. You could also see this message on your own system of interest
if the number of circles in the arrangement is in the thousands. Computing larger arrangements
(with more circles in them) needs more memory.

Ok, so how do I fix it?
	
	Are you running DISCO on a machine with less than 2GB of available memory?
	
		Try using a machine with more memory available.
		
	Are you running DISCO on a machine with more than 2GB of available memory, but only using a 32-bit OS?
	
		Try switching to a 64-bit OS. Your operating system won't be able to use more
		than 2GB (or 3GB with the right settings) using 32-bit addresses. Also switch
		to the 64 bit versions of the DISCO prerequisites. This allows the DISCO process
		to address more than 2GB of memory.
	

If you have difficulties or questions, feel to contact us with
inquiries by email:

	disco@cs.duke.edu
