Wiki

Installing and updating ATLAS

Requirements

ATLAS requires g++ and the library Armadillo to be installed, which in Ubuntu can be installed via the Synaptic Package Manager and with OSX can be installed with Homebrew. If you do not have root access armadillo can be installed locally: download armadillo. Check out these instructions for armadillo installation in Windows.

On Mac computers, ATLAS requires the omp library to be installed, which can also be done with Homebrew (see Compile section below for exact command)

Download

ATLAS is hosted on bitbucket and can be downloaded with the command:

git clone --depth 1 https://bitbucket.org/WegmannLab/atlas.git

Compile

For most users, we recommend using the master branch. However, for the curious, there is a refactored feature-branch called modular_recal. Note that this feature branch is still in beta!

Master Branch

A makefile for ATLAS is provided with the source code. If Armadillo is installed globally compile ATLAS by typing

cd atlas; make

If Armadillo is installed locally the command to compile ATLAS is

make ARM=false

If this is the case you might have to change the path to armadillo in the makefile to your local path.

If you are compiling ATLAS on a mac computer and get the error "omp.h not found", you can install the missing library with

brew install libomp

Feature Branch

The feature branch first needs to be checked out by typing

cd atlas; git checkout feature/modular_recal

If you are switching from the master branch or an older feature branch, you may need to clean the repository. Warning, this will irrevocably delete all personnel files in the atlas folder!

git clean -dfi

answer the question with 'c'.

The feature branch relies on CMake to download and install all dependencies

cmake .

Finally, you can install atlas using

make

Update

ATLAS is under active construction. Obtain the newest version by typing:

make clean; git fetch; git pull; make

If you are updating an atlas directory that you cloned before Oct. 15 2018 you might have to update the remote URL:

cd atlas; git remote set-url origin 'https://vlink@bitbucket.org/WegmannLab/atlas.git/'

Containers

The Singularity container to ATLAS version 0.9.9 can be downloaded here. The Singularity file to create such a container can be found here.
The a Docker file to create an ATLAS docker package can be downloaded here (written by Mahesh Binzer-Panchal - National Bioinformatics Infrastructure Sweden).

Running ATLAS

The program ATLAS is launched via the command line, preferentially with the name of an arguments file as the only argument. All necessary arguments are then specified in the argument file. Basically, an argument file is a simple collection of pairs of argument names and corresponding values (separated by one or several white space characters, i.e. blanks or tabs), enriched with comments. While each name-value pair has to be at the beginning of a new line, the order is of no importance. Comments may either be added after a name-value pair or given on a line on their own. Note that all comments must be proceeded with a double slash ''//''. Empty lines may be present anywhere within the file and are ignored.

For example, if the argument file is named example.arguments, the program has to be launched as follows:

./atlas example.arguments

An example for a *.arguments file to run recal would be:

task recal

bam example.bam

pmdFile example_PMD_input_Empiric.txt

chr X

limitWindows 20

verbose

Additionally, arguments may be passed on the command line. In that case, arguments that are also given in the input file will be overwritten. The required syntax is as follows:

./atlas example.arguments name=value

where name is the name of an argument and value is the corresponding value. For instance,

./atlas example.arguments window=1000000

launches ATLAS using a window size of 1Mb instead of the window size that might be specified in example.arguments.

Note that there is no restriction on the number of arguments to be passed that way and arguments can also be specified on the command line only. Note further that the order in which the arguments are given, both in the input file or on the command line, is of no importance.

ATLAS is designed to perform multiple tasks. To specify the desired task, the mandatory argument task has to be specified either in the input file or on the command line. Each task requires/allows for specific parameters that can be found on its respective page of this manual. A list of all tasks can be found here. Engine parameters that are common to all tasks can be found here.

In all tasks, reads that are not tagged as a "proper pair" are considered to be single-end.

Progress Report & Log File

By default, ATLAS writes only minimal information to the screen. To get a more detailed progress report printed to the screen, simply add the argument verbose either in the input file or on the command line. To save the progress report into a file (e.g. out.txt), simply redirect the output using

./atlas example.arguments verbose > out.txt

Alternatively, ATLAS can also write the progress report to a log file. To invoke this, simply use the argument logFile, followed by the name of the desired file. Note that this will overwrite any existing file with that name. Note further that verbose and logFile can both be used at the same time.