New upstream version 3.2.0

# The version number.

################################################################################

# The default version number is the latest official build

SET (gatb-tool_VERSION_MAJOR 2)

SET (gatb-tool_VERSION_MINOR 0)

SET (gatb-tool_VERSION_PATCH 7)

SET (gatb-tool_VERSION_MAJOR 3)

SET (gatb-tool_VERSION_MINOR 2)

SET (gatb-tool_VERSION_PATCH 0)

# But, it is possible to define another release number during a local build

IF (DEFINED MAJOR)

    SET (gatb-tool-version ${JENKINS_TAG})

ENDIF()

#############################

# getting git version

#from http://stackoverflow.com/questions/1435953/how-can-i-pass-git-sha1-to-compiler-as-definition-using-cmake

exec_program(

    "git"

    ${CMAKE_CURRENT_SOURCE_DIR}

    ARGS "rev-parse --short HEAD"

    OUTPUT_VARIABLE VERSION_SHA1 )

add_definitions( -DGIT_SHA1="${VERSION_SHA1}" )

################################################################################

# Define cmake modules directory

################################################################################

# One can uncomment this line and set the wanted values

#set (KSIZE_LIST "32   64   96  128  160  192  224  256")

# by default, it's compiling up to 128.

################################################################################

# THIRD PARTIES

add_executable(${PROJECT_NAME} ${ProjectFiles})

target_link_libraries(${PROJECT_NAME} ${gatb-core-libraries})

# merci

set (MERCI_SOURCE_DIR ${PROJECT_SOURCE_DIR}/merci)

include_directories (${MERCI_SOURCE_DIR})

file (GLOB_RECURSE  MerciFiles  ${MERCI_SOURCE_DIR}/*.cpp)

add_executable("merci"  ${MerciFiles})

target_link_libraries("merci" ${gatb-core-libraries})

################################################################################

#  DOC

################################################################################

# We copy the project binary to the 'bin' directory

INSTALL (TARGETS ${PROJECT_NAME} DESTINATION bin)

INSTALL (DIRECTORY "${PROJECT_SOURCE_DIR}/test/" DESTINATION test)

INSTALL (FILES LICENSE README.md DESTINATION bin/..)

# We include the "bin" tag into binary archive file name

# Run the newly created makefile:

make -j8

# Go back at the installation root directory

cd ..

# run tests

echo "Running simple test..."

cd test

. ./simple_test.sh

cd ..

# Minia 

[![License](http://img.shields.io/:license-affero-blue.svg)](http://www.gnu.org/licenses/agpl-3.0.en.html)

| **Linux** | **Mac OSX** |

|-----------|-------------|

[![Build Status](https://ci.inria.fr/gatb-core/view/Minia/job/tool-minia-build-debian7-64bits-gcc-4.7/badge/icon)](https://ci.inria.fr/gatb-core/view/Minia/job/tool-minia-build-debian7-64bits-gcc-4.7/) | [![Build Status](https://ci.inria.fr/gatb-core/view/Minia/job/tool-minia-build-macos-10.9.5-gcc-4.2.1/badge/icon)](https://ci.inria.fr/gatb-core/view/Minia/job/tool-minia-build-macos-10.9.5-gcc-4.2.1/)

[![License](http://img.shields.io/:license-affero-blue.svg)](http://www.gnu.org/licenses/agpl-3.0.en.html)

# What is Minia ?

CMake 2.6+; see http://www.cmake.org/cmake/resources/software.html

c++ compiler; compilation was tested with gcc and g++ version>=4.5 (Linux) and clang version>=4.1 (Mac OSX).

C++11 compiler; (g++ version>=4.7 (Linux), clang version>=4.3 (Mac OSX))

## Instructions

    # get a local copy of minia source code

    git clone --recursive https://github.com/GATB/minia.git

    # compile the code on your computer

    # compile the code an run a simple test on your computer

    cd minia

    sh INSTALL

Type `minia` without any arguments for usage instructions.

Short manual: http://minia.genouest.org/files/minia.pdf

A more complete manual:

    cd doc 

    pdflatex manual.tex

If you cannot compile it: http://minia.genouest.org/files/minia.pdf

# What is new ? (2018)

Minia version 1 was implementing a rather unusual way to perform the assembly: traverse the graph and attempt to jump over errors and variants. This worked rather okay but not for e.g. repeated regions with many sequencing errors. Minia version 2 also followed the same philosophy, and had major improvements coming from the integration of the GATB library (mostly speed improvements) and cascading Bloom filter.  Minia version 3 uses newer techniques and has virtually nothing in common with Minia 1: there is no Bloom filter anymore (the data structure is based on unitigs produced by the BCALM software). The assembly is performed using graph simplifications that are heavily inspired by the SPAdes assembler.

# Contact

\documentclass[a4paper]{article}

\usepackage{fancyvrb}

\usepackage{pdfpages}

\usepackage{url}

\begin{document}

\newcommand\vitem[1][]{\SaveVerb[% to use verb in description

\section{Forewords}

Minia-GATB is the codename of a new version of Minia using the GATB library. We will drop the "-GATB" suffix and just refer to it as "Minia". 

In terms of features, not much has changed: Minia remains a contigs assembler using very low memory. Notable changes are:

Minia 3 is a completely new version that no longer uses Bloom filters.

In terms of goals, not much has changed: Minia remains a contigs assembler using very low memory. Notable changes since Minia 1/2 are:

\begin{itemize}

    \item Different command line format 

    \item Much faster $k$-mer counting step

    \item Bubbles are collapsed using the most covered path (coverage information is now available for each node in the graph)

    \item Faster $k$-mer counting step

    \item Different graph construction step (uses BCALM software to construct unitigs)

    \item Different graph representation (not a Bloom filter, but an indexed list of unitigs)

    \item SPAdes-style graph simplifications

\end{itemize}

\section{Installation}

Downlad the binary and run Minia using the comand \verb+./minia+.

To install Minia from the sources, just type: \\ \verb+mkdir build && cd build && cmake .. && make -j 4+ \\

Minia has been tested on Linux and MacOS systems.

See Github page.

\section{Parameters}

The basic usage is:\\

\begin{verbatim}

    ./minia -in [input file] -kmer-size [kmer size] \

            -abundance-min [abundance value] -out [prefix]

    ./minia -in [input file] -kmer-size [kmer size] -out [prefix]

\end{verbatim}

Not much has changed since Minia 2 but we recommend that you still read the next section for an updated explanation of parameters.

An example command line is:\\

\verb+./minia -in reads.fastq -kmer-size 31 -abundance-min 3 -out minia_assembly_k31_m3+\\

\verb+./minia -in reads.fastq -kmer-size 31 -out minia_assembly_k31+\\

The main parameters are:

    \item \verb+kmer-size+  -- k-mer length (integer)

    \item \verb+abundance-min+ -- specifies how many times a $k$-mer must be seen in the reads to be considered correct (integer)

\item \verb+prefix+ -- any prefix string to store output contigs as well as temporary files for this assembly

\end{enumerate}

Minia now uses the Cascading Bloom filters improvement (http://arxiv.org/abs/1302.7278) by default, thanks to Gustavo Sacomoto for the implementation in Minia. Launch Minia with the \verb!-debloom original! option to revert to the original data structure.

\section{Explanation of parameters}

\begin{description}

\vitem+kmer-size+

The $k$-mer length is the length of the nodes in the de Bruijn graph. It strongly depends on the input dataset. We recommend that you use the KmerGenie software to automatically find the best $k$ for your dataset.

The $k$-mer length is the length of the nodes in the de Bruijn graph. It strongly depends on the input dataset. For proper assembly, we recommend that you use the Minia-pipeline that runs Minia multiple times, with an iterative multi-k algorithm. That way, you won't need to choose k. If you insist on running with a single k value, the KmerGenie software can automatically find the best $k$ for your dataset.

\vitem+abundance-min+

The \verb+abundance-min+ is used to remove erroneous, low-abundance $k$-mers. This parameter also strongly depends on the dataset. Any $k$-mer that appears strictly less than \emph{abundance-min} times in the reads will be discarded. A typical value is $3$. It is also called "coverage cut-off" in other software (e.g. Velvet).

KmerGenie has an experimental feature (in the output of the command, not in the HTML report) that reports an optimal coverage cut-off (synonymous to abundance) parameter that exactly corresponds to the abundance-min parameter of Minia.

The \verb+abundance-min+ is a hard cut-off to remove likely erroneous, low-abundance $k$-mers. In Minia 3, it is recommended to set it to 2 unless you have a good reason not to. Minia 3 also implements other ways to remove erroneous k-mers, using a more adequate relative cut-off, in the graph simplifications step.

\textbf{Setting \emph{abundance-min} to $1$ is not recommended}, as no erroneous $k$-mer will be discarded, which will likely result in a very large memory usage. In particular, if KmerGenie tells you to set abundance to 1, then still, set it to 2. If the dataset has high coverage, try larger values. 

Setting \emph{abundance-min} to $1$ is not recommended, as too many erroneous $k$-mer will be kept, which will likely result in a very large memory usage. If the dataset has high coverage, it may be worth it to try larger values. 

\vitem+prefix+

The \verb+prefix+ parameter is any arbitrary file name prefix, for example, \verb+test_assembly+.

The \verb+prefix+ parameter is any arbitrary output files name, for example, \verb+test_assembly+.

\end{description}

These are the main two parameters that control the quality of assembly. Minia command line has a few more parameters but they are either for advanced usage, or just minor tweaks. Some are described in the rest of this manual.

\section{Input}

\begin{description}

\item \emph{Larger $k$-mer lengths}

Minia supports arbitrary large $k$-mer lengths. To compile Minia from the source, to support $k$-mer lengths up to, say, 160, type this in the build folder:

Minia supports arbitrary large $k$-mer lengths. To compile Minia from the source, to support $k$-mer lengths up to, say, 320, type this in the build folder:

\begin{verbatim}

rm -Rf CMake* && cmake -Dk4=160 .. && make

rm -Rf CMake*

cmake -DKSIZE_LIST="32   64   96  128  160  192  224  256  320" ..

make -j 4

\end{verbatim}

The list of kmers should only contain multiples of 32. Intermediate values are used to create optimized code for k values that are shorter than the max. The last k value specifies the highest kmer size that can effectively be used in this compiled version of Minia. Apart from that, whatever k values are in this list do not affect the assembly quality in any way.

\item \emph{FASTA/FASTQ}

Minia assembles any type of Illumina reads, given in the FASTA or FASTQ format. Giving paired or mate-pairs reads as input is OK, but keep in mind that Minia won't use pairing information.

Minia can direclty read files compressed with gzip. Compressed files should end with '.gz'. Input files of different types can be mixed (i.e. gzipped or not, in FASTA or FASTQ)

\item \emph{Graph input}

Minia can take as input a graph in the HDF5 format, constructed using the dbgh5 program, or a different GATB tool, or from a previous run of Minia (useful when one wants to tweak assembly parameters). Use the \verb+-graph+ parameter to specify the graph, instead of the \verb+-in+ parameter.

\end{description}

\section{Output}

\subsection*{Creating unitigs}

Minia supports the creation of unitigs. Use the following command line: 

\begin{verbatim}

-starter simple -no-length-cutoff -traversal unitig

\end{verbatim}

Minia will also output unitigs in the FASTA format. Those are non-branching paths in the de Bruijn graph prior to any graph simplification. File: \verb+[prefix].unitigs.fa+. 

The \verb+-starter simple+ option is to turn off Minia's heuristics for starting node selection (which avoid starting inside a bubble).

Note that there is a known bug in the \verb+-starter simple+ behavior: some of the unitigs of length k won't be returned (technically: the branching nodes which are neighbors of branching nodes are not returned).

\section{Selection of graph simplification steps}

By default, Minia performs 3 types of graph simplifications: tip removal, bulges removal, and erroneous connections removal. Those are similar to SPAdes. You can selectively ask to not perform any (or all) of those operation through those command line arguments: \verb+-no-tip-removal+, \verb+-no-bulge-removal+, \verb+-no-ec-removal+.

\section{Fine-tuning of graph simplification steps}

Most of the graph simplification steps are highly inspired by the SPAdes assembler.

A regular user needs not modify any of the graph simplifications parameters.

Yet, for advanced users, it is possible to do so in order to increase or reduce the aggresiveness of variant/error removal.

Tip removal implements two modes: "short tips" removal and "longer tips" removal. Short tips are removed no matter what their coverage is. By default, a tip is considered short if it is of length $\leq 3.5k$. Longer tips are of length $\leq 10k$. They are removed if their coverage is smaller than the average coverage of the neighbor unitigs, multiplied by a constant factor.

To make tip clipping more conservative, I would recommend specifying a high \verb+-tip-rctc-cutoff+ cutoff, such as \verb+-tip-rctc-cutoff 20+. This will make sure that the coverage of a tip is at least 20 times smaller than the coverage of its neighbors.

Explanation all the other simplifications steps would make this manual a bit longer. For now you can try to guess using slide 11 of \url{http://cristal.univ-lille.fr/~chikhi/pdf/2017-august-3-biata.pdf}. Some information can also be found in the SPAdes paper, where the term \emph{bulge} is defined.

\section{Memory usage}

We estimate that the memory usage of Minia is roughly $1$ GB of RAM per gigabases in the target genome to assemble. It is independent of the coverage of the input dataset, provided that the \verb!abundance-min! parameter is correctly set. For example, a human genome was assembled in $5.7$ GB of RAM. This was using the original data structure; the current implementation relies on Cascading Bloom filters and uses $\approx 4$ GB. A better estimation of the memory usage can be found in the Minia article.

We estimate that the memory usage of Minia is in the order of $1$ GB of RAM per gigabases in the target genome to assemble. It is independent of the coverage of the input dataset, provided that the \verb!abundance-min! parameter is not too low.

\section{Disk usage}

Minia writes large temporary files during the k-mer counting phase. These files are written in the working directory when you launched Minia. For better performance, run Minia on a local hard drive. 

Minia writes large temporary files during the k-mer counting phase. These files are written in the working directory when you launched Minia. For better performance, run Minia on a local hard drive, SSD, or (very large) ram disk, around 2-3x time the space of the input.

\section{Reproducibility}

Default Minia parameters do not ensure a deterministic execution: due to e.g. multi-threading, the results may change a little bit between executions (but should still give more or less the same assembly).

To make sure that results are perfectly identical between runs on the same data and the same parameters, run with these options:

\verb!-nb-cores 1 -nb-glue-partitions 200!. Also make sure that the same compiler version was used.

\section{Influences}

This version of Minia could not exist without inspiration taken from these great pieces of software and methods:

\begin{itemize}

    \item khmer \url{https://github.com/dib-lab/khmer}

    \item KMC2 \url{https://github.com/marekkokot/KMC}

    \item SPAdes \url{http://bioinf.spbau.ru/spades}

    \item MSP \url{http://www.vldb.org/pvldb/vol6/p169-li.pdf}

    \item Meraculous \url{https://jgi.doe.gov/data-and-tools/meraculous/}

\end{itemize}

\end{document}