From e087349252c2bb0ff07ce92951c300128db61172 Mon Sep 17 00:00:00 2001 From: Mike Vella Date: Tue, 4 Oct 2022 21:11:00 +0000 Subject: [PATCH 1/6] Added changelog and updated readme --- CHANGELOG.md | 31 +++++++++++++++++++++ README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..c325d53bd --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,31 @@ +# Changelog + +All notable changes to Dorado will be documented in this file. + +# [0.0.1] (05 Oct 2022) + +We are excited to announce the first binary release of Dorado. This Dorado release introduces important new features such as support for modified base calling, and significant improvements to basecalling performance and usability, taking it to the state of the art for speed and accuracy. + +## Major changes +* d3ddd1f078adc5b52ebfbb7d6aa5ee71acb0b7fb, 37e28f7b3d70dda469f3c498dcbe1ea5df722936, - Support for mod base calling, performance enhancements. +* dd79bf5fb4b005052eb46969cfadd8ef2af8378e, 2a7fc176a5c0075a6fbf95dd3f7a41d52e420963, 465cb4a29e8cfd45b74064f13eb5c152fa2fa1c6, 56482fbd364a8d2cacb608b13b3a7f1792a604e3 - Support for basecalling on M1 family Apple Silicon. +* bd6014edc8de374645ade284dd103eccbfa481db - Support for basecalling on systems with multiple Nvidia GPUs. +* 41fdb1189a4677c6932a4c4467d69c73407dfaaa - Support for POD5 file format. +* 075065447d1a273f3101037c1578647bc2ad8b1e - Addition of new “Quantile” - based read scaling algorithm for higher accuracy. +* 8acf2baa35932a9c42a419b6b620f92e25a87bba - Upgrade to torch 1.12.1 +* 9955d0de71d36e279b44e46545f5dfb6c742f224 - Added fast int8-quantization optimisation for LSTM networks with layer size of 96 or 128 +* f2e993d3961a52072cf43b0f327dbc21029c3aad - New cuBLAS-based implementation for LSTMs leading to state-of-the-art performance. +* 6ec50dc5cecc65f0ff940420c0de152ba561f85c - Major rearchitecture of CUDA model runners for higher basecalling speed and lower GPU memory utilisation. +* a0a197f4950d390221b6ffc82ccd8ce012c3c765 - Accuracy improvements to handling of short reads (<1Kb) with an upgraded padding strategy. +* d01bf04f7dd84b14753790fae83ba20b7776f498 - Ability to download basecalling models from Dorado. +* 7c7e59c6d65464f0eee40bf3d9f6885aae27839b - Support for SAM output + +## Minor Changes +* 0e89d633d66f36256ad437ca0a3b64ff9eb0b1a1 - Automatic selection of batch size if user does not specify. +* 6afceea0195c07b02a40e43e0a395c3d82d44add - Dorado version added to SAM output, including commit hash +* 339b2fc5d7eee5be7f8289d51422a70ad06f6d58 - Scaling information recorded in SAM output +* afbfab92f8207b9a67aae0aa87478c4b95e647b8 - Timestamps added to SAM output +* 9ec2d970a0e5dee739daaafdfd08c20844140cb3 - Support for multi-threaded read scaling, preventing CPU bottlenecks and improving basecall speed. +* 7cbdbe04e76edf7d704e28263d64dddd6ab7d375 - Support for multi-threaded POD5 reading for higher data ingestion rate and improved performance. +* 5a33e83512343e9fd36470fa84fa36c97211672b - Automatic querying of M1 device type for detection of optimal basecalling parameters. +* 42703d0c02638633b44f68c0fc53534a9566b634 - Basecalling progress (Number of reads basecalled) printed out to terminal on Linux. diff --git a/README.md b/README.md index f883d4aa1..d72364409 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,37 @@ # Dorado -This is a *preview version* of Dorado, a Libtorch Basecaller for Oxford Nanopore Reads. This software is in alpha preview stage and being released for early evaluation. It is subject to change. If you encounter any problems building or running Dorado please [report an issue](https://github.com/nanoporetech/dorado/issues). +Dorado is a high-performance, easy-to-use, open source basecaller for Oxford Nanopore reads. -## Downloading Dorado +## Features -We will be publishing pre-built releases in the next few days. +* One executable with sensible defaults, automatic hardware detection and configuration. +* Runs on Apple silicon (M1-family) and Nvidia GPUs including multi-GPU with linear scaling. +* Modified basecalling (Remora models). +* [POD5](https://github.com/nanoporetech/pod5-file-format) support for highest basecalling performance. +* Based on libtorch, the C++ API for pytorch. +* Multiple custom optimisations in CUDA and Metal for maximising inference performance. + +This is an alpha of Dorado . This software is being released for evaluation. If you encounter any problems building or running Dorado please [report an issue](https://github.com/nanoporetech/dorado/issues). + + +## Installation + +TBD. ## Running +To run Dorado, download a model and point it to POD5 files. Fast5 files are supported but will not be as performant. + ``` $ dorado download --model dna_r10.4.1_e8.2_260bps_hac@v3.5.2 -$ dorado basecaller dna_r10.4.1_e8.2_260bps_hac@v3.5.2 pod5/ > calls.sam +$ dorado basecaller dna_r10.4.1_e8.2_260bps_hac@v3.5.2 pod5s/ > calls.sam +``` + +For unaligned BAM output, dorado output can be piped to BAM using samtoools: + +``` +$ dorado basecaller dna_r10.4.1_e8.2_260bps_hac@v3.5.2 pod5s/ | samtools view -Sh > calls.bam + ``` ## Platforms @@ -19,11 +40,46 @@ Dorado has been tested on the following systems: | Platform | GPU/CPU | | -------- | -------------------- | -| Windows | x86 | +| Windows | (G)V100, A100 | | Apple | M1, M1 Max, M1 Ultra | | Linux | (G)V100, A100 | -Other Platforms may work, if you encounter problems with running on your system please [report an issue](https://github.com/nanoporetech/dorado/issues) +Systems not listed above but which have Nvidia GPUs with >=8GB VRAM and architecture from Volta onwards have not been widely tested but are expected to work. If you encounter problems with running on your system please [report an issue](https://github.com/nanoporetech/dorado/issues) + +## Roadmap + +Dorado is still in alpha stage and not feature-complete, the following features form the core of our roadmap: + +1. DNA Barcode multiplexing +2. Duplex basecalling +3. Alignmnet (output aligned BAMs) +4. Python API + +## Performance tips + +1. For optimal performance Dorado requires POD5 file input. Please [convert your Fast5 files](https://github.com/nanoporetech/pod5-file-format) before basecalling. +1. Dorado will automatically detect your GPUs' free memory and select an appropriate batch size. If you know what you're doing, you can use the `--batch` parameter to tune batch size. +2. Dorado will automatically run in multi-GPU (`'cuda:all'`) mode. If you have a hetrogenous collection of GPUs select the faster GPUs using the `--device` flag (e.g `--device "cuda:0,2`). Not doing this will have a detrimental impact on performance. + +## Available basecalling models + +To download all available dorado models run: + +``` +$ dorado download --model all +``` + +The following models are currently available: + +* dna_r10.4.1_e8.2_260bps_fast@v3.5.2 +* dna_r10.4.1_e8.2_260bps_hac@v3.5.2 +* dna_r10.4.1_e8.2_260bps_sup@v3.5.2 +* dna_r10.4.1_e8.2_400bps_fast@v3.5.2 +* dna_r10.4.1_e8.2_400bps_hac@v3.5.2 +* dna_r10.4.1_e8.2_400bps_sup@v3.5.2 +* dna_r9.4.1_e8_fast@v3.4 +* dna_r9.4.1_e8_hac@v3.3 +* dna_r9.4.1_e8_sup@v3.3 ## Developer quickstart @@ -51,3 +107,11 @@ The project uses pre-commit to ensure code is consistently formatted, you can se $ pip install pre-commit $ pre-commit install ``` + +### Licence and Copyright +(c) 2022 Oxford Nanopore Technologies Ltd. + +Dorado 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 From 84968d070ccac0eaa30b8fe8776537a8ab5a6895 Mon Sep 17 00:00:00 2001 From: Chris Seymour Date: Tue, 4 Oct 2022 21:52:02 +0000 Subject: [PATCH 2/6] release links --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d72364409..d84069077 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,9 @@ This is an alpha of Dorado . This software is being released for evaluation. If ## Installation -TBD. + - [dorado-0.0.1-linux-x64](https://nanoporetech.box.com/shared/static/q39qjh0tacym6b467u4gh1p6q3xpyc5l.gz) + - [dorado-0.0.1-osx-arm64](https://nanoporetech.box.com/shared/static/skouz5lp9tpcejdz20s4b5avvrw36cvj.gz) + - [dorado-0.0.1-windows-x64](https://nanoporetech.box.com/shared/static/s0401b23uxca2srtz7s88gsv1puf4chi.zip) ## Running From efa5a48f54e53e3159479fe4bbd2bced14ecbb2e Mon Sep 17 00:00:00 2001 From: Stuart Abercrombie Date: Wed, 5 Oct 2022 10:47:07 +0000 Subject: [PATCH 3/6] Update README.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d84069077..7cf451026 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,11 @@ $ dorado basecaller dna_r10.4.1_e8.2_260bps_hac@v3.5.2 pod5s/ | samtools view -S Dorado has been tested on the following systems: -| Platform | GPU/CPU | -| -------- | -------------------- | -| Windows | (G)V100, A100 | -| Apple | M1, M1 Max, M1 Ultra | -| Linux | (G)V100, A100 | +| Platform | GPU/CPU | +| -------- | ---------------------------- | +| Windows | (G)V100, A100 | +| Apple | M1, M1 Pro, M1 Max, M1 Ultra | +| Linux | (G)V100, A100 | Systems not listed above but which have Nvidia GPUs with >=8GB VRAM and architecture from Volta onwards have not been widely tested but are expected to work. If you encounter problems with running on your system please [report an issue](https://github.com/nanoporetech/dorado/issues) From 759a39fc4b63244d59e4ec658e60ffbaa1ea5664 Mon Sep 17 00:00:00 2001 From: Stuart Abercrombie Date: Wed, 5 Oct 2022 10:48:12 +0000 Subject: [PATCH 4/6] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c325d53bd..6fd85b998 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ We are excited to announce the first binary release of Dorado. This Dorado relea * 9955d0de71d36e279b44e46545f5dfb6c742f224 - Added fast int8-quantization optimisation for LSTM networks with layer size of 96 or 128 * f2e993d3961a52072cf43b0f327dbc21029c3aad - New cuBLAS-based implementation for LSTMs leading to state-of-the-art performance. * 6ec50dc5cecc65f0ff940420c0de152ba561f85c - Major rearchitecture of CUDA model runners for higher basecalling speed and lower GPU memory utilisation. -* a0a197f4950d390221b6ffc82ccd8ce012c3c765 - Accuracy improvements to handling of short reads (<1Kb) with an upgraded padding strategy. +* a0a197f4950d390221b6ffc82ccd8ce012c3c765 - Accuracy improvements to handling of short reads (<1KB) with an upgraded padding strategy. * d01bf04f7dd84b14753790fae83ba20b7776f498 - Ability to download basecalling models from Dorado. * 7c7e59c6d65464f0eee40bf3d9f6885aae27839b - Support for SAM output From 3e7e2c2ebac24ad7a36088dfde504197d5e51760 Mon Sep 17 00:00:00 2001 From: Stuart Abercrombie Date: Wed, 5 Oct 2022 10:49:23 +0000 Subject: [PATCH 5/6] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fd85b998..c325d53bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ We are excited to announce the first binary release of Dorado. This Dorado relea * 9955d0de71d36e279b44e46545f5dfb6c742f224 - Added fast int8-quantization optimisation for LSTM networks with layer size of 96 or 128 * f2e993d3961a52072cf43b0f327dbc21029c3aad - New cuBLAS-based implementation for LSTMs leading to state-of-the-art performance. * 6ec50dc5cecc65f0ff940420c0de152ba561f85c - Major rearchitecture of CUDA model runners for higher basecalling speed and lower GPU memory utilisation. -* a0a197f4950d390221b6ffc82ccd8ce012c3c765 - Accuracy improvements to handling of short reads (<1KB) with an upgraded padding strategy. +* a0a197f4950d390221b6ffc82ccd8ce012c3c765 - Accuracy improvements to handling of short reads (<1Kb) with an upgraded padding strategy. * d01bf04f7dd84b14753790fae83ba20b7776f498 - Ability to download basecalling models from Dorado. * 7c7e59c6d65464f0eee40bf3d9f6885aae27839b - Support for SAM output From 0a0d53deebf7079d1fa9e68dcfade739edfc2945 Mon Sep 17 00:00:00 2001 From: Chris Seymour Date: Wed, 5 Oct 2022 12:24:47 +0000 Subject: [PATCH 6/6] download links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7cf451026..03423ca17 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ This is an alpha of Dorado . This software is being released for evaluation. If ## Installation - - [dorado-0.0.1-linux-x64](https://nanoporetech.box.com/shared/static/q39qjh0tacym6b467u4gh1p6q3xpyc5l.gz) - - [dorado-0.0.1-osx-arm64](https://nanoporetech.box.com/shared/static/skouz5lp9tpcejdz20s4b5avvrw36cvj.gz) - - [dorado-0.0.1-windows-x64](https://nanoporetech.box.com/shared/static/s0401b23uxca2srtz7s88gsv1puf4chi.zip) + - [dorado-0.0.1-linux-x64](https://nanoporetech.box.com/shared/static/h8eqc9htxk938jzpl4fch2rqlm48yeb0.gz) + - [dorado-0.0.1-osx-arm64](https://nanoporetech.box.com/shared/static/e33yelum810yv09mao5mr7tgh8gj2e5f.gz) + - [dorado-0.0.1-windows-x64](https://nanoporetech.box.com/shared/static/vb2zxg30e5jl9dbit4eqtlvkb5p377te.zip) ## Running