---

Megalodon

Megalodon is a research command line tool to extract high accuracy modified base and sequence variant calls from raw nanopore reads by anchoring the information rich basecalling neural network output to a reference genome/transcriptome.

Raw nanopore reads are processed by a single command to produce basecalls (FASTA/Q), reference mappings (SAM/BAM/CRAM), modified base calls (per-read and bedgraph/bedmethyl/modVCF), sequence variant calls (per-read and VCF) and more.

Detailed documentation for all megalodon arguments and algorithms can be found on the megalodon documentation page.

Prerequisites

As of version 2.0, the primary megalodon run mode requires the guppy basecaller. See the community page for download/installation instructions.

All other requirements are handled by pip or conda installation. If installing from source, numpy must be installed before running installation for cython optimizations.

Taiyaki is no longer required to run megalodon, but installation is required for two specific run modes: 1) output mapped signal files (for basecall models training) 2) running the taiyaki basecalling backend (for neural network designs including experimental layers)

Installation

Megalodon is a command line tool. pip and conda are the recommended installation interfaces for megalodon.

pip install megalodon
# or
conda install megalodon

Getting Started

Megalodon is accessed via the command line interface megalodon command.

# megalodon help (common args)
megalodon -h
# megalodon help (all args)
megalodon --help-long

# Example command to output basecalls, mappings, variants and CpG methylation
#   Compute settings: GPU devices 0 and 1 with 40 CPU cores
megalodon raw_fast5s/ \
    --outputs basecalls mappings variants mods \
    --reference reference.fa --variant-filename variants.vcf.gz \
    --mod-motif Z CG 0 --devices 0 1 --processes 40

This command produces the megalodon_results output directory containing all requested output files and logs. The format for each output is described briefly below and in more detail in the full documentation

The path to the guppy_basecall_server executable is required to run megalodon. By default, megalodon assumes this path is ./ont-guppy/bin/guppy_basecall_server. Use the --guppy-server-path argument to specify a different path.

Inputs

• Raw reads
  • Directory containing raw read FAST5 files (sub-directories recursively searched)
• Reference
  • Genome or transcriptome sequence reference (FASTA or minimap2 index)
• Variants File
  • Megalodon requires a set of candidate variants for --outputs variants (provide via --variant-filename argument; VCF or BCF).

Outputs

All megalodon outputs are written into the directory specified with the --output-directory option with standard file names and extensions.

• Basecalls
  • Format: FASTQ (default) or FASTA
  • Basecall-anchored modified base scores are also available in hts-spec BAM format tags (--outputs mod_basecalls).
• Mappings
  • Format: SAM, BAM (default), or CRAM
  • A tab-separated mapping text summary is also produced including per-read alignment statistics.
• Modified Base Calls
  • Per-read modified base calls
    • Per-read SQL DB containing modified base scores at each covered reference location
    • Tab-delimited output can be produced by adding the --write-mods-text flag or produced post-run using the megalodon_extras per_read_text modified_bases command.
      • This output can drastically slow processing, especially on slower disk or when outputting modified bases at all contexts.
  • Aggregated calls
    • Format: bedgraph, bedmethyl (default), and/or modVCF
  • In order to restrict modified base calls to a specific motif(s) specify the --mod-motif argument. For example, to restrict calls to CpG sites specify --mod-motif Z CG 0.
• Sequence Variant Calls
  • Per-read Variant Calls
    • SQL DB containing per-read variant scores for each covered variant
    • Tab-delimited output can be produced by adding the --write-variants-text flag or produced post-run using the megalodon_extras per_read_text variants command.
  • Aggregated calls
    • Format: VCF
    • Default run mode is diploid. To run in haploid mode, set --haploid flag.
    • For best results on a diploid genome see the variant phasing workflow on the full documentation page.

Live Processing

As of version 2.2, Megalodon now supports live run processing. Activate live processing mode by simply adding the --live-processing argument and specifying the MinKNOW output directory as the Megalodon FAST5 directory. Megalodon will continue to search for FAST5s until the final_summary* file is created by MinKNOW indicating data production has completed.

Guppy Models and Parameters

As of version 2.2, Megalodon requires Guppy version>=4.0.

The Guppy model defines the modified bases capable of being output by Megalodon. Basecalling models must be trained to specifically detect a type or types of modified bases. See the Megalodon documentation here for instructions to construct modified base training data and train a new modified base model.

By default, megalodon uses the dna_r9.4.1_450bps_modbases_dam-dcm-cpg_hac.cfg guppy config. This config is compatible with DNA, R9.4.1, MinION/GridION reads and allows output of 5mC and 6mA calls in biological contexts (CpG, dcm and dam sites). Use the --guppy-config option to specify a different guppy model config. The appropriate Rerio model is recommended for the highest accuracy modified base calls.

All configs can be used to output basecalls and mappings (as well as signal_mappings and per_read_refs for basecall training <https://nanoporetech.github.io/megalodon/model_training.html>). Modified base and sequence variant outputs require Megalodon calibration files. To list configs with default calibration files, run megalodon --list-supported-guppy-configs. See calibration documentation here for details on Megalodon model calibration.

Only flip-flop configs/models are currently supported by megalodon (this excludes k-mer based and RLE model types).

In addition to the --guppy-config and --guppy-server-path options, a number of additional arguments control the behavior of the guppy backend. The --guppy-params argument will pass arguments directly to the guppy_basecall_server initialization call. For example to optimize GPU usage, the following option might be specified: --guppy-params "--num_callers 5 --ipc_threads 6"

Finally the --guppy-timeout arguments ensures that a run will not stall on a small number of reads taking a very long time (default 5 seconds).

High Quality Phased Variant Calls

In order to obtain the highest quality diploid sequence variant calls, the full variant phasing pipeline employing whatshap should be applied. This pipeline is described in detail on the full documentation page. The default diploid variant settings are optimized for the full phasing pipeline and not the highest quality diploid calls directly from a single Megalodon call.

High-Density Variants

When running megalodon with a high density of variants (more than 1 variant per 100 reference bases), certain steps can be taken to increase performance. See variant atomize documentation for further details.

Disk Performance Considerations

Per-read modified base and variant statistics are stored in an on-disk sqlite database. As of version 2.0, the status of output queues is displayed by default and (as of version 2.2) the extract signal input queue. If the extract_signal input queue is often empty, Megalodon is waiting on reading raw signal from FAST5 files. If any output status bars indicate a full queue, megalodon will stall waiting on that process to write data to disk. Moving the input data directory or --output-directory accordingly to a location with faster disk I/O performance should improve performance.

RNA

Megalodon now supports processing direct RNA nanopore data. In order to process an RNA sample specify the --rna flag as well as an RNA model using the --guppy-config argument.

Megalodon performs mapping using the standard minimap option, map-ont, and not the splice option, so a transcriptome reference must be provided. Megalodon supports RNA modified base detection provided an appropriate basecalling model, though no RNA modified base models are currently released for general use. Megalodon does not currently support variant detection from direct RNA data, but this feature may be added in a future release.

Note

Megalodon does not currently perform checking that a set of reads agree with the provided model or options specified (e.g. --rna). Users should take care to ensure that the correct options are specified for each sample processed.

License and Copyright

© 2019-20 Oxford Nanopore Technologies Ltd.

Megalodon is distributed under the terms of the Oxford Nanopore Technologies, Ltd. Public License, v. 1.0. If a copy of the License was not distributed with this file, You can obtain one at http://nanoporetech.com