Medaka

medaka is a tool to create consensus sequences and variant calls from nanopore sequencing data. This task is performed using neural networks applied a pileup of individual sequencing reads against a reference sequence, mostly commonly either a draft assembly or a database reference sequence. It provides state-of-the-art results outperforming sequence-graph based methods and signal-based methods, whilst also being faster.

© 2018- Oxford Nanopore Technologies Ltd.

Features

• Requires only basecalled data. (.fasta or .fastq)
• Improved accuracy over graph-based methods (e.g. Racon).
• 50X faster than Nanopolish (and can run on GPUs).
• Includes extras for implementing and training bespoke correction networks.
• Works on Linux and MacOS.
• Open source (Oxford Nanopore Technologies PLC. Public License Version 1.0)

For creating draft assemblies we recommend Flye.

Installation

Medaka can be installed in one of several ways.

Installation with pip

Official binary releases of medaka are available on PyPI and can be installed using pip:

pip install medaka

On contemporaray Linux and macOS platforms this will install a precompiled binary, on other platforms a source distribution may be fetched and compiled.

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

python3 -m venv medaka
. ./medaka/bin/activate
pip install --upgrade pip
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 versions >=1.14 and minimap2 version >=2.17 are recommended as these are those used in development of medaka.

The default installation has the capacity to run on a GPU (see Using a GPU below), or on CPU. If you are using medaka exclusively on CPU, and don't need the ability to run on GPU, you may wish to install the CPU-only version with:

pip install medaka-cpu --extra-index-url https://download.pytorch.org/whl/cpu

Installation with conda

The bioconda medaka packages are not supported by Oxford Nanopore Technologies.

For those who prefer the conda package manager, medaka is available via the anaconda.org channel:

conda create -n medaka -c conda-forge -c nanoporetech -c bioconda medaka

Installations with this method will bundle the additional tools required to run an end-to-end correction workflow.

Installation from source

This method is useful only when the above methods have failed, as it will assist in building various dependencies. Its unlikely that our developers will be able to provide further assistance in your specific circumstances if you install using this method.

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:

bzip2 g++ zlib1g-dev libbz2-dev liblzma-dev libffi-dev libncurses5-dev
libcurl4-gnutls-dev libssl-dev curl make cmake wget python3-all-dev
python-virtualenv

In addition it is required to install and set up git LFS before cloning the repository.

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

# Note: certain files are stored in git-lfs, https://git-lfs.github.com/,
#       which must therefore be installed first.
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.

When building from source, to install a CPU-only version without the capacity to run on GPU, modify the above to:

MEDAKA_CPU=1 make install

Using a GPU

Since version 2.0 medaka uses PyTorch. Prior versions (v1.x) used Tensorflow.

The default version of PyTorch that is installed when building from source or when installing through pip can make immediate use of GPUs via NVIDIA CUDA. However, note that the torch package is compiled against specific versions of the CUDA and cuDNN libraries; users are directed to the torch installation pages for further information. cuDNN can be obtained from the cuDNN Archive, whilst CUDA from the CUDA Toolkit Archive.

Installation with conda is a little different. See the [conda-forge]https://conda-forge.org/docs/user/tipsandtricks/#installing-cuda-enabled-packages-like-tensorflow-and-pytorch) documentation. In summary, the conda package should do something sensible bespoke to the computer it is being installed on.

As described above, if the capability to run on GPU is not required, medaka-cpu can be installed with a CPU-only version of PyTorch that doesn't depend on the CUDA libraries, as follows:

pip install medaka-cpu --extra-index-url https://download.pytorch.org/whl/cpu

if using the prebuilt packages, or

MEDAKA_CPU=1 make install

if building from source.

GPU Usage notes

Depending on your GPU, medaka may show out of memory errors when running. To avoid these the inference batch size can be reduced from the default value by setting the -b option when running medaka_consensus. A value -b 100 is suitable for 11Gb GPUs.

Usage

medaka can be run using its default settings through the medaka_consensus program. An assembly in .fasta format and basecalls in .fasta or .fastq formats 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, otherwise 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}

The variables BASECALLS, DRAFT, and OUTDIR in the above should be set appropriately. The -t option specifies the number of CPU threads to use.

When medaka_consensus has finished running, the consensus will be saved to ${OUTDIR}/consensus.fasta.

Haploid variant calling

Variant calling for haploid samples is enabled through the medaka_variant workflow:

medaka_variant -i <reads.fastq> -r <ref.fasta>

which requires the reads as a .fasta or .fastq and a reference sequence as a .fasta file.

Diploid variant calling

The diploid variant calling workflow that was historically implemented within the medaka package has been surpassed in accuracy and compute performance by other methods, it has therefore been deprecated. Our current recommendation for performing this task is to use Clair3 either directly or through the Oxford Nanopore Technologies provided Nextflow implementation available through EPI2ME Labs.

Models

For best results it is important to specify the correct inference model, according to the basecaller used. Allowed values can be found by running medaka tools list\_models.

Recent basecallers

Recent basecaller versions annotate their output with their model version. In such cases medaka can inspect the files and attempt to select an appropriate model for itself. This typically works best in the case of BAM output from basecallers. It will work also for FASTQ input provided the FASTQ has been created from basecaller output using:

samtools fastq -T '*' dorado.bam | gzip -c > dorado.fastq.gz

The command medaka inference will attempt to automatically determine a correct model by inspecting its BAM input file. The helper scripts medaka_consensus and medaka_variant will make similar attempts from their FASTQ input.

To inspect files for yourself, the command:

medaka tools resolve_model --auto_model <consensus/variant> <input.bam/input.fastq>

will print the model that automatic model selection will use.

Bacterial and plasmid sequencing

For native data with bacterial modifications, such as bacterial isolates, metagenomic samples, or plasmids expressed in bacteria, there is a research model that shows improved consensus accuracy. This model is compatible with several basecaller versions for the R10 chemistries. By adding the flag --bacteria the bacterial model will be selected if it is compatible with the input basecallers:

medaka_consensus -i ${BASECALLS} -d ${DRAFT} -o ${OUTDIR} -t ${NPROC} --bacteria

A legacy default model will be used if the bacterial model is not compatible with the input files. The model selection can be confirmed by running:

medaka tools resolve_model --auto_model consensus_bacteria <input.bam/input.fastq>

which will display the model r1041_e82_400bps_bacterial_methylation if compatible or the default model name otherwise.

Read-level models

Recently, "read-level" consensus polishing models have been developed that integrate additional read information, such as base