Downloading and Installing SHORE

Download

Download the latest SHORE binary or source code release

https://sourceforge.net/projects/shore
or http://1001genomes.org/software

or check out the git repository to compile SHORE from the very latest source:

> git clone git://shore.git.sourceforge.net/gitroot/shore/shore

Installing SHORE using the binary file

Navigate to the folder where you stored the downloaded file:

 > tar xzvf shore_<platform>_<version>.tar.gz

Now, adjust the PATH environment variable to include the extracted shore directory (or copy the shore binary to a location in your PATH).

For example, in a typical bash environment, add a similar line to the file $HOME/.bashrc:

export PATH=$PATH:YOUR/SHORE/DIRECTORY

Installing SHORE using the source files

Installation prerequisites

SHORE requires gcc and g++ version 4.0.2 or later to be built successfully (check by running `g++ --version` in a terminal).

In addition to that, please make sure that the following libraries and development headers are installed on your system:

Library	Version	Debian / Ubuntu package name	MacPorts package
boost filesystem	1.34.1 - 1.53.0	libboost-filesystem-dev	boost
boost iostreams	1.34.1 - 1.53.0	libboost-iostreams-dev	boost
boost thread	1.34.1 - 1.53.0	libboost-thread-dev	boost
GNU Scientific Library	≥0.11	libgsl0-dev	gsl-devel
zlib	≥1.1.3	zlib1g-dev	zlib
liblzma	≥5.0.1	liblzma-dev	xz-devel

When installing libraries using a package manager like Ubuntu Software Center, aptitude or MacPorts, be sure to select the *-dev or *-devel versions of the packages where available.

Compiling and installing SHORE

Navigate to the directory where you stored the downloaded file

> tar xzvf shore_<version>.tar.gz
> cd shore_source_<version>

(or navigate to your shore git folder).

In case you checked out a development snapshot from git, you need to run the autogen script first. The autogen script additionally requires autoconf, automake and libtool installed on your system.

./autogen.sh

If you downloaded a regular release, the autogen step can be skipped. To build and install SHORE, simply type

./configure
make
make install

This will install the SHORE binary into /usr/local/bin, the scoring matrix files into usr/local/share/shore, documentation files into /usr/local/share/doc/shore and libraries and development headers into /usr/local/lib and /usr/local/include, respectively.

To install into a different directory, use the --prefix option to configure

./configure prefix=<path>

to install SHORE into <path>/bin, <path>/share etc.

Using locally installed libraries / MacPorts

If there is no system wide installation for some of the libraries that SHORE requires, but you installed them e.g. into your home directory, it may be necessary to set the environment variables LD_LIBRARY_PATH, LIBRARY_PATH and CPLUS_INCLUDE_PATH for the compiler and linker to recognize them.

E.g. if the Boost and GSL libraries are installed into /home/xyz/boost-1.48 and /home/xyz/gsl-1.11, set:

export CPLUS_INCLUDE_PATH=/home/xyz/boost-1.48/include:/home/xyz/gsl-1.11/include
export LIBRARY_PATH=/home/xyz/boost-1.48/lib:/home/xyz/gsl-1.11/lib
export LD_LIBRARY_PATH=/home/xyz/boost-1.48/lib:/home/xyz/gsl-1.11/lib

These instructions also apply to libraries installed on OS X using MacPorts. MacPorts typically installs libraries to /opt/local. To use them, set:

export CPLUS_INCLUDE_PATH=/opt/local/include
export LIBRARY_PATH=/opt/local/lib

Additional important configure options

• ./configure --with-mpi

A binary with support for Message Passing Interface (MPI) parallelization will be built. This additional binary will be named `shore-mpi`.

• ./configure --without-lzma

Disables suppport for LZMA compression.

Building SHORE for distributed memory setups

SHORE can also be compiled to support distributed memory parallelization through the MPI (Message Passing Interface) standard.

Make sure to have appropriate MPI development files installed, e. g. MPICH2.

First, follow the above instructions for compiling shore from source.

To build and install the MPI-enabled SHORE binary, add the option --with-mpi when running ./configure.

An additional command shore-mpi will then be built and installed, which can be passed to an MPI process manager like mpiexec (see using SHORE with MPI).

Download and install an alignment tool

SHORE can currently be run with five different alignment tools. The native tool of SHORE is GenomeMapper, which can be downloaded from http://1001genomes.org/downloads.

Navigate to the folder where you stored the downloaded file:

> tar xzvf genomemapper.tar.gz
> cd genomemapper
> make

See the GenomeMapper manual for further details.

Now, copy the genomemapper and gmindex binaries to a location in your PATH, or set the GENOMEMAPPER environment variable as described below.

In addition to GenomeMapper, SHORE supports several third party aligners.

Installation of R

SHORE can optionally make use of R (http://www.r-project.org) to provide visualization, e.g. of run statistics. In order to use this feature, R has to be installed and the installation path has to be added to the $PATH environment variable. Note that it is not necessary to have R installed to run SHORE.

Environment variables

Since SHORE supports external alignment tools, it needs to know where these are located on the respective system. The easiest way to achieve this is making sure the alignment tools are installed in a location that is pointed to by the $PATH environment variable (exemplary description for the bash environment; for tcsh or any other shell, users have to set the environment variables in an equivalent way).

Add one or more similar lines to the file $HOME/.bashrc:

export PATH=$PATH:/ALIGNMENT_TOOL/INSTALL/DIRECTORY

Alternatively, individual environment variables may be set up for each specific alignment tool that should be used:

export GENOMEMAPPER=/GENOMEMAPPER/INSTALL/DIRECTORY

third-party tools:

export BWA=/BWA/INSTALL/DIRECTORY
export BOWTIE=/BOWTIE/INSTALL/DIRECTORY
export ELAND=/CASAVA/INSTALL/DIRECTORY

TMP directory

Some files need to be sorted before SHORE can use them. Before using these input files SHORE checks if they are sorted in the appropriate way and in case of inconsistencies SHORE will start to sort them. E.g., initially alignments are sorted by read ids, but to analyze them they need to be sorted by the alignment location. Therefore sorting is required. SHORE implements its own sorting program. By default this program uses /tmp if the files to be sorted are large (which is usually the case). Therefore, it can happen that the disk space in /tmp is not sufficient; we recommend at least 200GB. This can be achieved by setting the TMPDIR environment variable to a file system with sufficient space.

 export TMPDIR=/DIRECTORY/WITH/SUFFICIENT/SPACE