Installing and configuring Disperse

These instructions describe the procedure for installing setup Disperse. It has been tested on openSUSE Linux, Gentoo Linux, Windows XP, and Mac OS X.

Requirements

Java and Perl

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.

Perl modules and Java libraries and programs

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.

  • Perl modules

    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.

    • FindBin
    • FileHandle
    • File::Spec
    • Getopt::Long
    • LWP::Simple
    • Log::Log4perl

      The Disperse install script will try to install any missing dependencies.

  • Java libraries

    A number of Java libraries, mostly from the Apache software foundation, are included with the distribution of Disperse. See Project Dependencies for details.

  • ProbeMaker 1.5.0

    The ProbeMaker program is included with the Disperse distribution.

  • PieceMaker 1.3.2

    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.

External programs

  • NCBI-BLAST (Standalone)

    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.

Data

  • CCDS data file (CCDS.yyyymmdd.txt)

    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.

  • Blast database file (human_genomic.*)

    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.

The following data is optional:

  • SNP data file

    Required to check for SNPs affecting restriction sites. The locaction of this is specified in the configuration file.

Installation

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:

  • Download the latest disperse distribution (.zip for windows, .tar.gz forlinux/MacOS X)
  • Unpack the zip or tar file and move the unpacked contents to a location of your choice.

    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.

Linux

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.

  1. Unpack the distribution .tar file

    Open a console/terminal window, navigate to where you put your downloaded files, and type:

    'tar -xvzf disperse-disdtribution-version.tar.gz'

  2. Move the unpacked directory to your location of choice, for example:

    'mv disperse-disdtribution-version /usr/local/disperse

  3. If you downloaded the optional SNP data file, place it in the 'data' subdirectory of the install directory.

    'mv dbSNP_127.txt /usr/local/disperse/data'

  4. Place the 'piecemaker-core-version.jar' and (optionally) 'piecemaker-swingui-version.jar' files in the 'extlib' subdirectory of the install directory.

    'mv piecemaker-core-version.jar /usr/local/disperse/extlib' 'mv piecemaker-swingui-version.jar /usr/local/disperse/extlib'

  5. Move to the install directory and execute the setup script. This will create the launch scripts for the Java programs.

    'cd /usr/local/disperse/'

    './setup.sh'

  6. Make the newly created scripts executable.

    'chmod +x *.sh'

Windows

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.

  1. Unpack the distribution .zip file, and copy it to the location of your choice.

    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'.

  2. If you downloaded the optional SNP data file, place it in the 'data' subdirectory of the install directory.
  3. Place the 'piecemaker-core-version.jar' file in the 'extlib' subdirectory of the install directory. Place the 'piecemaker-swingui-version.jar' file in the 'extlib' subdirectory of the install directory. (optional, required for fragment visualization)
  4. Execute the setup script. Double-click the setup.bat icon, or open a comman prompt and type 'cd C:\disperse'

    'setup'

    This will create the launch scripts for the Java programs.

Mac OS X

Open the Terminal program, which you'll find in the Applications->Utilities folder.

Follow the installation instructions for linux systems, above.