Medaka

medaka is a tool to create a consensus sequence of nanopore sequencing data. This task is performed using neural networks applied a pileup of individual sequencing reads against a draft assembly. It outperforms graph-based methods operating on basecalled data, and can be competitive with state-of-the-art signal-based methods whilst being much faster.

© 2018 Oxford Nanopore Technologies Ltd.

• Requires only basecalled data. (.fasta or .fastq)
• Improved accurary over graph-based methods (e.g. Racon).
• 50X faster than Nanopolish (and can run on GPUs).
• Benchmarks are provided here.
• Includes extras for implementing and training bespoke correction networks.
• Works on Linux (MacOS and Windows support is untested).
• Open source (Mozilla Public License 2.0).

Tools to enable the creation of draft assemblies can be found in a sister project pomoxis.

Documentation can be found at https://nanoporetech.github.io/medaka/.

There are currently two installation methods for medaka, detailed below.

Installation with pip

Medaka can be installed using the python package manager, pip:

pip install medaka

On Linux platforms this will install a precompiled binary, on MacOS (and other) platforms this will fetch and compile a source distribution.

We recommend using medaka within a virtual environment, viz.:

virtualenv medaka --python=python3 --prompt "(medaka) "
. medaka/bin/activate
pip install medaka

Using this method requires the user to provide several binaries:

• samtools,
• minimap2,
• tabix, and
• bgzip

and place these within the PATH. samtools/bgzip/tabix version 1.3.1 and minimap2 version 2.11 are recommended as these are those used in development of medaka.

Installation from source

Medaka can be installed from its source quite easily on most systems.

Before installing medaka it may be required to install some prerequisite libraries, best installed by a package manager. On Ubuntu theses are:

• gcc
• zlib1g-dev
• libbz2-dev
• liblzma-dev
• libffi-dev
• libncurses5-dev
• make
• wget
• python3-all-dev
• python-virtualenv

A Makefile is provided to fetch, compile and install all direct dependencies into a python virtual environment. To setup the environment run:

git clone https://github.com/nanoporetech/medaka.git
cd medaka
make install
. ./venv/bin/activate

Using this method both samtools and minimap2 are built from source and need not be provided by the user.

Using a GPU

All installation methods will allow medaka to be used with CPU resource only. To enable the use of GPU resource it is necessary to install the tensorflow-gpu package. In outline this can be achieve with:

pip uninstall tensorflow
pip install tensorflow-gpu

However, note that The tensorflow-gpu GPU package is compiled against a specific version of the NVIDIA CUDA library; users are directed to the tensorflow installation pages for further information.

medaka can be run using its default settings through the medaka_consensus program. An assembly in .fasta format and basecalls in .fasta or .fastq format are required. The program uses both samtools and minimap2. If medaka has been installed using the from-source method these will be present within the medaka environment, else they will need to be provided by the user.

source ${MEDAKA}  # i.e. medaka/venv/bin/activate
NPROC=$(nproc)
BASECALLS=basecalls.fa
DRAFT=draft_assm/assm_final.fa
OUTDIR=medaka_consensus
medaka_consensus -i ${BASECALLS} -d ${DRAFT} -o ${OUTDIR} -t ${NPROC} -m r94

The variables BASECALLS, DRAFT, and OUTDIR in the above should be set appropriately. When medaka_consensus has finished running, the consensus will be saved to ${OUTDIR}/consensus.fasta.

It is crucially important to specify the correct model, -m in the above, according to the basecaller used. Allowed values can be found by running medaka consensus --help. For example to run medaka with a model suitable for the flip-flop basecaller in Guppy use -m r941_flip.

Medaka has been trained to correct draft sequences processed through racon, specifically racon run four times iteratively with:

racon -m 8 -x -6 -g -8 -w 500 ...

Processing a draft sequence from alternative sources (e.g. the output of canu or wtdbg2) may lead to poorer results even when the draft is of a superior quality than that obtained from racon.

The walkthrough outlines one recommended workflow rapid construction of a draft for input into medaka. A second approach would be to run canu followed by racon applied twice iteratively before entry into medaka.

We thank Joanna Pineda and Jared Simpson for providing htslib code samples which aided greatly development of the optimised feature generation code, and for testing the version 0.4 release candidates.

Licence and Copyright

© 2018 Oxford Nanopore Technologies Ltd.

medaka is distributed under the terms of the Mozilla Public License 2.0.

Research Release

Research releases are provided as technology demonstrators to provide early access to features or stimulate Community development of tools. Support for this software will be minimal and is only provided directly by the developers. Feature requests, improvements, and discussions are welcome and can be implemented by forking and pull requests. However much as we would like to rectify every issue and piece of feedback users may have, the developers may have limited resource for support of this software. Research releases may be unstable and subject to rapid iteration by Oxford Nanopore Technologies.