{"id":25596863,"url":"https://github.com/nanoporetech/medaka","last_synced_at":"2025-05-15T20:06:16.204Z","repository":{"id":38898316,"uuid":"93641740","full_name":"nanoporetech/medaka","owner":"nanoporetech","description":"Sequence correction provided by ONT Research","archived":false,"fork":false,"pushed_at":"2024-10-11T08:57:16.000Z","size":67199,"stargazers_count":455,"open_issues_count":22,"forks_count":81,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-05-14T17:31:39.649Z","etag":null,"topics":["medaka","nanopore"],"latest_commit_sha":null,"homepage":"https://nanoporetech.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanoporetech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-07T14:01:06.000Z","updated_at":"2025-05-14T07:47:50.000Z","dependencies_parsed_at":"2022-07-11T20:02:41.403Z","dependency_job_id":"43793a80-ccdc-43c5-a306-3095a583cfce","html_url":"https://github.com/nanoporetech/medaka","commit_stats":{"total_commits":842,"total_committers":19,"mean_commits":44.31578947368421,"dds":"0.37292161520190026","last_synced_commit":"cbf182f2aa7cd14165f02758f9386b8aed3aff4b"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fmedaka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fmedaka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fmedaka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fmedaka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanoporetech","download_url":"https://codeload.github.com/nanoporetech/medaka/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["medaka","nanopore"],"created_at":"2025-02-21T12:34:56.350Z","updated_at":"2025-05-15T20:06:11.171Z","avatar_url":"https://github.com/nanoporetech.png","language":"Python","funding_links":[],"categories":["Software packages"],"sub_categories":["Assembly"],"readme":"\n![Oxford Nanopore Technologies logo](https://github.com/nanoporetech/medaka/raw/master/images/ONT_logo_590x106.png)\n\n\nMedaka\n======\n\n[![](https://img.shields.io/pypi/v/medaka.svg)](https://pypi.org/project/medaka/)\n[![](https://img.shields.io/pypi/wheel/medaka.svg)](https://pypi.org/project/medaka/)\n[![](https://anaconda.org/nanoporetech/medaka/badges/version.svg)](https://anaconda.org/nanoporetech/medaka)\n\n\n`medaka` is a tool to create consensus sequences and variant calls from\nnanopore sequencing data. This task is performed using neural networks applied\na pileup of individual sequencing reads against a reference sequence, mostly commonly\neither a draft assembly or a database reference sequence. It provides\nstate-of-the-art results outperforming sequence-graph based methods and\nsignal-based methods, whilst also being faster.\n\n© 2018- Oxford Nanopore Technologies Ltd.\n\nFeatures\n--------\n\n  * Requires only basecalled data. (`.fasta` or `.fastq`)\n  * Improved accuracy over graph-based methods (e.g. Racon).\n  * 50X faster than Nanopolish (and can run on GPUs).\n  * Includes extras for implementing and training bespoke correction\n    networks.\n  * Works on Linux and MacOS.\n  * Open source (Oxford Nanopore Technologies PLC. Public License Version 1.0)\n\nFor creating draft assemblies we recommend [Flye](https://github.com/fenderglass/Flye).\n\nInstallation\n------------\n\nMedaka can be installed in one of several ways.\n\n**Installation with pip**\n\nOfficial binary releases of medaka are available on\n[PyPI](https://pypi.org/project/medaka/) and can be installed using pip:\n\n    pip install medaka\n\nOn contemporaray Linux and macOS platforms this will install a precompiled binary,\non other platforms a source distribution may be fetched and compiled.\n\nWe recommend using medaka within a virtual environment, viz.:\n\n    python3 -m venv medaka\n    . ./medaka/bin/activate\n    pip install --upgrade pip\n    pip install medaka\n\nUsing this method requires the user to provide several binaries:\n\n * [samtools](https://github.com/samtools/samtools),\n * [minimap2](https://github.com/lh3/minimap2),\n * [tabix](https://github.com/samtools/htslib), and\n * [bgzip](https://github.com/samtools/htslib)\n\nand place these within the `PATH`. `samtools/bgzip/tabix` versions \u003e=1.14 and\n`minimap2` version \u003e=2.17 are recommended as these are those used in development\nof medaka.\n\nThe default installation has the capacity to run on a GPU (see _Using a GPU_ below),\nor on CPU. If you are using `medaka` exclusively on CPU, and don't need the ability\nto run on GPU, you may wish to install the CPU-only version with:\n\n    pip install medaka-cpu --extra-index-url https://download.pytorch.org/whl/cpu\n\n\n**Installation with conda**\n\n\u003e The bioconda medaka packages are not supported by Oxford Nanopore Technologies.\n\nFor those who prefer the conda package manager, medaka is available via the\n[anaconda.org](https://anaconda.org/nanoporetech/medaka) channel:\n\n    conda create -n medaka -c conda-forge -c nanoporetech -c bioconda medaka\n\nInstallations with this method will bundle the additional tools required to run\nan end-to-end correction workflow.\n\n**Installation from source**\n\n\u003e This method is useful only when the above methods have failed, \n\u003e as it will assist in building various dependencies. Its unlikely that\n\u003e our developers will be able to provide further assistance in your\n\u003e specific circumstances if you install using this method.\n\nMedaka can be installed from its source quite easily on most systems.\n\n Before installing medaka it may be required to install some\n prerequisite libraries, best installed by a package manager. On Ubuntu\n theses are:\n \u003e     bzip2 g++ zlib1g-dev libbz2-dev liblzma-dev libffi-dev libncurses5-dev\n \u003e     libcurl4-gnutls-dev libssl-dev curl make cmake wget python3-all-dev\n \u003e     python-virtualenv\n In addition it is required to install and set up git LFS before cloning\n the repository.\n\nA Makefile is provided to fetch, compile and install all direct dependencies\ninto a python virtual environment. To set-up the environment run:\n\n    # Note: certain files are stored in git-lfs, https://git-lfs.github.com/,\n    #       which must therefore be installed first.\n    git clone https://github.com/nanoporetech/medaka.git\n    cd medaka\n    make install\n    . ./venv/bin/activate\n\nUsing this method both `samtools` and `minimap2` are built from source and need\nnot be provided by the user.\n\nWhen building from source, to install a CPU-only version without the capacity to\nrun on GPU, modify the above to:\n\n    MEDAKA_CPU=1 make install\n\n\n**Using a GPU**\n\nSince version 2.0 `medaka` uses PyTorch. Prior versions (v1.x) used Tensorflow.\n\nThe default version of PyTorch that is installed when building from source or \nwhen installing through `pip` can make immediate use of GPUs via NVIDIA CUDA.\nHowever, note that the `torch` package is compiled against specific versions of\nthe CUDA and cuDNN libraries; users are directed to the \n[torch installation](https://pytorch.org/get-started/locally/) pages for further\ninformation. cuDNN can be obtained from the \n[cuDNN Archive](https://developer.nvidia.com/rdp/cudnn-archive), whilst CUDA from\nthe [CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive).\n\n\u003e Installation with conda is a little different. See the\n\u003e [conda-forge]https://conda-forge.org/docs/user/tipsandtricks/#installing-cuda-enabled-packages-like-tensorflow-and-pytorch)\n\u003e documentation. In summary, the conda package should do something sensible\n\u003e bespoke to the computer it is being installed on.\n\nAs described above, if the capability to run on GPU is not required, `medaka-cpu`\ncan be installed with a CPU-only version of PyTorch that doesn't depend on the\nCUDA libraries, as follows:\n\n    pip install medaka-cpu --extra-index-url https://download.pytorch.org/whl/cpu\n\nif using the prebuilt packages, or \n\n    MEDAKA_CPU=1 make install\n\nif building from source.\n\n*GPU Usage notes*\n\nDepending on your GPU, `medaka` may show out of memory errors when running.\nTo avoid these the inference batch size can be reduced from the default\nvalue by setting the `-b` option when running `medaka_consensus`. A value\n`-b 100` is suitable for 11Gb GPUs.\n\n\nUsage\n-----\n\n`medaka` can be run using its default settings through the `medaka_consensus`\nprogram. An assembly in `.fasta` format and basecalls in `.fasta` or `.fastq`\nformats are required. The program uses both `samtools` and `minimap2`. If\nmedaka has been installed using the from-source method these will be present\nwithin the medaka environment, otherwise they will need to be provided by\nthe user.\n\n    source ${MEDAKA}  # i.e. medaka/venv/bin/activate\n    NPROC=$(nproc)\n    BASECALLS=basecalls.fa\n    DRAFT=draft_assm/assm_final.fa\n    OUTDIR=medaka_consensus\n    medaka_consensus -i ${BASECALLS} -d ${DRAFT} -o ${OUTDIR} -t ${NPROC}\n\nThe variables `BASECALLS`, `DRAFT`, and `OUTDIR` in the above should be set\nappropriately. The `-t` option specifies the number of CPU threads to use. \n\nWhen `medaka_consensus` has finished running, the consensus will be saved to\n`${OUTDIR}/consensus.fasta`.\n\n\n**Haploid variant calling**\n\nVariant calling for haploid samples is enabled through the `medaka_variant`\nworkflow:\n\n    medaka_variant -i \u003creads.fastq\u003e -r \u003cref.fasta\u003e\n    \nwhich requires the reads as a `.fasta` or `.fastq` and a reference sequence as a\n`.fasta` file.\n\n\n**Diploid variant calling**\n\nThe diploid variant calling workflow that was historically implemented\nwithin the medaka package has been surpassed in accuracy and compute performance by\nother methods, it has therefore been deprecated. Our current recommendation for\nperforming this task is to use [Clair3](https://github.com/HKU-BAL/Clair3) either directly\nor through the Oxford Nanopore Technologies provided Nextflow implementation available\nthrough [EPI2ME Labs](https://labs.epi2me.io/wfindex#variant-calling).\n\n\nModels\n------\n\nFor best results it is important to specify the correct inference model, according\nto the basecaller used. Allowed values can be found by running `medaka tools list\\_models`.\n\n**Recent basecallers**\n\nRecent basecaller versions annotate their output with their model version.\nIn such cases medaka can inspect the files and attempt to select an appropriate\nmodel for itself. This typically works best in the case of BAM output from\nbasecallers. It will work also for FASTQ input provided the FASTQ has been\ncreated from basecaller output using:\n\n```\nsamtools fastq -T '*' dorado.bam | gzip -c \u003e dorado.fastq.gz\n```\n\nThe command `medaka inference` will attempt to automatically determine a\ncorrect model by inspecting its BAM input file. The helper scripts\n`medaka_consensus` and `medaka_variant` will make similar attempts\nfrom their FASTQ input.\n\nTo inspect files for yourself, the command:\n\n```\nmedaka tools resolve_model --auto_model \u003cconsensus/variant\u003e \u003cinput.bam/input.fastq\u003e\n```\n\nwill print the model that automatic model selection will use.\n\n**Bacterial and plasmid sequencing**\n\nFor native data with bacterial modifications, such as bacterial isolates,\nmetagenomic samples, or plasmids expressed in bacteria, there is a research\nmodel that shows improved consensus accuracy. This model is compatible with\nseveral basecaller versions for the R10 chemistries. By adding the flag `--bacteria`\nthe bacterial model will be selected if it is compatible with the input basecallers:\n\n```\nmedaka_consensus -i ${BASECALLS} -d ${DRAFT} -o ${OUTDIR} -t ${NPROC} --bacteria\n```\n\nA legacy default model will be used if the bacterial model is not compatible with\nthe input files. The model selection can be confirmed by running:\n\n```\nmedaka tools resolve_model --auto_model consensus_bacteria \u003cinput.bam/input.fastq\u003e\n```\n\nwhich will display the model `r1041_e82_400bps_bacterial_methylation` if\ncompatible or the default model name otherwise.\n\n**When automatic selection is unsuccessful, and older basecallers**\n\nIf the name of the basecaller model used is known, but has been lost from the input\nfiles, the basecaller model can been provided to medaka directly. It must however\nbe appended with either `:consensus` or `:variant` according to whether the user\nwishing to use the consensus or variant calling medaka model. For example:\n\n```\nmedaka inference input.bam output.hdf \\\n    --model dna_r10.4.1_e8.2_400bps_hac@v4.1.0:variant\n```\n\nwill use the medaka variant calling model appropriate for use with the basecaller\nmodel named `dna_r10.4.1_e8.2_400bps_hac@v4.1.0`.\n\nHistorically medaka models followed a nomenclature describing both the chemistry\nand basecaller versions. These old models are now deprecated, users are encouraged\nto rebasecall their data with a more recent basecaller version prior to using medaka.\n\n\nImproving parallelism\n---------------------\n\nThe `medaka_consensus` program is good for simple datasets but perhaps not\noptimal for running large datasets at scale. A higher level of parallelism\ncan be achieved by running independently the component steps of\n`medaka_consensus`. The program performs three tasks:\n\n1. alignment of reads to input assembly (via `mini_align` which is a thin\n   veil over `minimap2`)\n2. running of consensus algorithm across assembly regions\n   (`medaka inference`)\n3. aggregation of the results of 2. to create consensus sequences\n   (`medaka sequence`)\n\nThe three steps are discrete, and can be split apart and run independently. In\nmost cases, Step 2. is the bottleneck and can be trivially parallelized. The\n`medaka consensus` program can be supplied a `--regions`\nargument which will restrict its action to particular assembly sequences from\nthe `.bam` file output in Step 1. Therefore individual jobs can be run for batches\nof assembly sequences simultaneously. In the final step, `medaka stitch`\ncan take as input one or more of the `.hdf` files output by Step 2.\n\nSo in summary something like this is possible:\n\n```\n# align reads to assembly\nmini_align -i basecalls.fasta -r assembly.fasta -P -m \\\n    -p calls_to_draft.bam -t \u003cthreads\u003e\n# run lots of jobs like this:\nmkdir results\nmedaka inference calls_to_draft.bam results/contigs1-4.hdf \\\n    --region contig1 contig2 contig3 contig4\n...\n# wait for jobs, then collate results\nmedaka sequence results/*.hdf polished.assembly.fasta\n```\n\nIt is not recommended to specify a value of `--threads` greater than 2 for\n`medaka inference` since the compute scaling efficiency is poor beyond this.\nNote also that `medaka inference` may been seen to use resources equivalent to\n`\u003cthreads\u003e + 4` as an additional 4 threads are used for reading and preparing\ninput data.\n\n\nOrigin of the draft sequence\n----------------------------\n\nMedaka has been trained to correct draft sequences output from the\n[Flye](https://github.com/fenderglass/Flye) assembler.\n\nProcessing a draft sequence from alternative sources (e.g. the output of\n[canu](https://github.com/marbl/canu) or\n[wtdbg2](https://github.com/ruanjue/wtdbg2)) may lead to different results.\n\n\u003e Historical correction\n\u003e models in medaka were trained to correct draft sequences output from the canu\n\u003e assembler with [racon](https://github.com/lbcb-sci/racon) applied either once,\n\u003e or four times iteratively. For contemporary models this is not the case and\n\u003e medaka should be used directly on the output of Flye.\n\n\n\nAcknowledgements\n----------------\n\nWe thank [Joanna Pineda](https://github.com/jopineda) and\n[Jared Simpson](https://github.com/jts) for providing htslib code samples which aided\ngreatly development of the optimised feature generation code, and for testing the\nversion 0.4 release candidates.\n\nWe thank [Devin Drown](https://github.com/devindrown) for\n[working through](https://github.com/nanoporetech/medaka/issues/70)\nuse of `medaka` with his RTX 2080 GPU.\n\nHelp\n----\n\n**Licence and Copyright**\n\n© 2018- Oxford Nanopore Technologies Ltd.\n\n`medaka` is distributed under the terms of the Oxford Nanopore Technologies PLC. Public License Version 1.0\n\n**Research Release**\n\nResearch releases are provided as technology demonstrators to provide early\naccess to features or stimulate Community development of tools. Support for\nthis software will be minimal and is only provided directly by the developers.\nFeature requests, improvements, and discussions are welcome and can be\nimplemented by forking and pull requests. However much as we would\nlike to rectify every issue and piece of feedback users may have, the\ndevelopers may have limited resource for support of this software. Research\nreleases may be unstable and subject to rapid iteration by Oxford Nanopore\nTechnologies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoporetech%2Fmedaka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanoporetech%2Fmedaka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoporetech%2Fmedaka/lists"}