How to install

Guidance installation

The details on how to how to install and how to run, as well as the downloadable links are available through these two github repositories:

The steps to install GUIDANCE are also described below:

1. Getting started

1.1 - Installing on a Singularity image

1.2 - Installing on bare metal

1. Getting started

GUIDANCE was developed to run on HPC infrastructures and cloud environments. The instructions given here consider execution in HPC environment. In order to run it in the cloud, specific instructions are given in this project .

These instructions will get you a copy of the project up and running on your machine. There are two main options to run GUIDANCE: directly on top of your OS and inside a Singularity image. We strongly recommend to use Singularity as it makes all the process much more easier.

1.1 Installing on a Singularity image


In order to run GUIDANCE in this mode, you only need to install the guidance COMPSs' branch and generate the Singularity image containing all the depedencies. If you want to generate execution traces, you should install this COMPSs' branch.


It is possible to find the instructions to install COMPSs in their github repository.

Regarding the Singularity image generation, it is enough to run this script. It will automatically create a local docker registry and upload to it the base docker image necessary to create the Singularity image. Nevertheless, you should modify the file placed in $PROJECT_PATH/singularity/singularity/base.def in order to include the folder in your local file system that should be visible into the image. More precisely, you should only touch this lines:

mkdir -p $SINGULARITY_ROOTFS/gpfs/home/
mkdir -p $SINGULARITY_ROOTFS/gpfs/scratch/
mkdir -p $SINGULARITY_ROOTFS/gpfs/apps/MN4
mkdir -p $SINGULARITY_ROOTFS/gpfs/projects/
mkdir -p /opt/intel
mkdir -p /scratch

In addition, a GUIDANCE binary should be generated from this repository. In order to do so, you should run the following command in the root of the repository:

mvn clean install

This will generate a binary guidance.jar.

1.2 Installing on bare metal


First of all, you need to install the guidance COMPSs’ branch in your system. Afterwards, all the dependencies should be installed in the machine in which GUIDANCE will run. More precisely, the following binaries should be installed and accessible from all the worker nodes:
  • Minimac4
  • Minimac3
  • Plink 1.9
  • Eagle 2.4
  • Impute 2.3.2
  • Qctool 1.4
  • Snptest 2.5
  • Tabix
  • Bgzip
  • Shapeit v2 r727
  • Samtools
  • Bcftools
  • R (tested version 3.5.1)
Next, the following environment variables should be set in order to tell GUIDANCE where the binaries are located in each machine:

export PLINKBINARY=/PATH_TO/plink_1.9/plink
export EAGLEBINARY=/PATH_TO/Eagle_v2.4.1/eagle
export QCTOOLBINARY=/PATH_TO/qctool_v1.4-linux-x86_64/qctool
export SHAPEITBINARY=/PATH_TO/shapeit.v2.r727.linux.x64
export IMPUTE2BINARY=/PATH_TO/impute_v2.3.2_x86_64_static/impute2
export SNPTESTBINARY=/PATH_TO/snptest_v2.5
export MINIMAC3BINARY=/PATH_TO/Minimac3/bin/Minimac3
export MINIMAC4BINARY=/PATH_TO/Minimac4/release-build/minimac4

export R_LIBS_USER=/gpfs/home/bsc05/bsc05997/TOOLS/R_libs/

In the last case, R_LIBS_USER specify the path into which are installed the R dependencies in case they are not installed in the default path. More precisely, the following packages should be available:
  • data.table
  • plyr
  • dplyr
  • reshape
  • gap
  • sfsmisc
  • BiocManager
  • IRanges
In addition, in the folder "RSCRIPTDIR" there shuould be all the scripts available here.

Finally, maven should be installed in the system in order to compile the GUIDANCE binary.


Once all the dependencies are in the system, you should checkout the GUIDANCE repository and generate the guidance binary. In order to do so, you should run the following command in the root of the repository:

mvn clean install

This will generate a binary guidance.jar.