These instructions describe the procedure for installing setup Disperse. It has been tested on openSUSE Linux, Gentoo Linux, Windows XP, and Mac OS X.
Disperse is written in both Java and Perl, and requires a Java runtime environment 1.6 or later and Perl 5 to be installed on your system. See http://java.sun.com/ and http://www.perl.org/ for information on download and setup of Java and Perl, respectively.
Note that both the 'java' and 'perl' interpreters need to be on the PATH for Disperse to work. Too check if they are, open a command prompt/terminal/console window and type 'perl -version' and 'java -version'. This should print messages about the installed perl/java version, respecively. If instead you get a message stating that the program can not be found or similar, you need to add the location (install directory) of the interpreter to your PATH variable. Describing how to do this for your particular operating system is out of scope of this text. Please consult your operating system documentation, or see this Wikipedia article for a brief guide on setting environment variables.
Disperse makes use of a number of 3rd party Java libraries and Perl modules. These need to be installed on your system for Disperse to work.
Some or all of these modules may already be included in your perl installation. If not, you will need to download and install them yourself. This can be done in different ways depending on your operating system. See this tutorial for assistance.
The Disperse install script will try to install any missing dependencies.
A number of Java libraries, mostly from the Apache software foundation, are included with the distribution of Disperse. See Project Dependencies for details.
The ProbeMaker program is included with the Disperse distribution.
For licensing reasons, the PieceMaker program is not included in the Disperse distribution (PieceMaker is free for non-profit, academic use, but not for commercial use).
Request PieceMaker from the author via e-mail. To ensure that you get the correct version, please specify that you intend to use it together with Disperse. Also specify your home department/institution.
The piecemaker jar files need to be manually copied inte the 'extlib' subdirectory of the Disperse install directory.
Disperse requires the 'fastacmd' program for retrieving sequences from a BLAST database file. The location of the fastacmd program must be specified in the disperse configuration file (see below).
See http://www.ncbi.nlm.nih.gov/blast/download.shtml for download instructions.
Used to find exon coordinates for targeted genes. See ftp://ftp.ncbi.nlm.nih.gov/pub/CCDS/current_human. Included with the Disperse distribution. If you wish to change to a newer version, just download it via ftp, and change the Disperse configuration file to point to the new file.
Used to extract sequence data for target regions. See ftp://ftp.ncbi.nlm.nih.gov/blast/db/. The location of this database must be specified in the Disperse configuration file.
Required to check for SNPs affecting restriction sites. The locaction of this is specified in the configuration file.
Before installation, ensure that Java and Perl are installed and on the PATH, as described above.
Note the location of the fastacmd program, and the blast database file.
The installation is performed in the following steps, with detailed operating system-specific instructions following further down:
From this point, you can choose to proceed with manual installation and configuration (following instructions provided below for your operating system), or to use the provided install script by navigating to the disperse install directory and typing 'perl install.pl' at the command prompt. Depending on your system configuration, you may also be able to launch the install script by clicking or double-clicking its icon in your file manager/explorer.
The install script will check for prerequisites, and if the Perl cpan utility is available, it will try to install any missing required perl modules. It will also check the default configuration file, allowing you to enter the locations of external programs and data, and giving you the possibility to download the (large) variationdata fileand the ccds file, if not present. See the configuration file specification for details.
After completing the install script, copy or move the piecemaker jar files into the 'extlib' subdirectory of the Disperse install directory, as described below for the different operating systems.
If you have problems using the install script, try following the relevant instructions below. After these steps, make sure to edit main configuration file, 'config/default_config.properties', to specify the locations of required files and programs.
The easiest way to perform the installation isfrom the command line, although several of the steps can probably be performed from the desktop environment. You may need root privileges depending on where you wish to install disperse.
Open a console/terminal window, navigate to where you put your downloaded files, and type:
'tar -xvzf disperse-disdtribution-version.tar.gz'
'mv disperse-disdtribution-version /usr/local/disperse
'mv dbSNP_127.txt /usr/local/disperse/data'
'mv piecemaker-core-version.jar /usr/local/disperse/extlib' 'mv piecemaker-swingui-version.jar /usr/local/disperse/extlib'
'cd /usr/local/disperse/'
'./setup.sh'
'chmod +x *.sh'
The installation procedure for windows differs slightly from above. Depending on where you wish to install the software, you may need to use an administrator account.
Generally, you can use the windows compressed files utility to open the zip file contents of the zip file by right-clicking the file's icon. You can then drag-and-drop or copy-paste the disperse folder to a location of your choice, perhaps 'C:\disperse'.
'setup'
This will create the launch scripts for the Java programs.
Open the Terminal program, which you'll find in the Applications->Utilities folder.
Follow the installation instructions for linux systems, above.