dorado
0.8.2
Dorado ist ein leistungsstarker, benutzerfreundlicher Open-Source-Basecaller für Oxford Nanopore-Lesevorgänge.
Eine ausführbare Datei mit sinnvollen Standardeinstellungen, automatischer Hardwareerkennung und -konfiguration.
Läuft auf Apple-Silizium (M1/2-Familie) und Nvidia-GPUs, einschließlich Multi-GPU mit linearer Skalierung (siehe Plattformen).
Modifiziertes Basecalling.
Duplex-Basecalling (sehen Sie sich das folgende Video an, um eine Einführung in Duplex zu erhalten).
Simplex-Barcode-Klassifizierung.
Unterstützung für ausgerichtete Leseausgabe in SAM/BAM.
Erste Unterstützung für die Poly(A)-Tail-Schätzung.
Unterstützung für Single-Read-Fehlerkorrektur.
POD5-Unterstützung für höchste Basecalling-Leistung.
Basierend auf libtorch, der C++-API für Pytorch.
Mehrere benutzerdefinierte Optimierungen in CUDA und Metal zur Maximierung der Inferenzleistung.
Wenn beim Erstellen oder Ausführen von Dorado Probleme auftreten, melden Sie uns bitte.
Laden Sie zunächst das entsprechende Installationsprogramm für Ihre Plattform herunter:
dorado-0.8.2-linux-x64
dorado-0.8.2-linux-arm64
dorado-0.8.2-osx-arm64
dorado-0.8.2-win64
Sobald das entsprechende .tar.gz oder .zip Archiv heruntergeladen wurde, extrahieren Sie das Archiv an den gewünschten Speicherort.
Anschließend können Sie Dorado über den vollständigen Pfad aufrufen, zum Beispiel:
$ /path/to/dorado-x.y.z-linux-x64/bin/dorado basecaller hac pod5s/ > calls.bam
Oder Sie können den bin-Pfad zu Ihrer Umgebungsvariablen $PATH hinzufügen und stattdessen den Befehl dorado ausführen, zum Beispiel:
$ dorado basecaller hac pod5s/ > calls.bam
Weitere Informationen zum Erstellen von Dorado für die Entwicklung finden Sie unter DEV.md.
Dorado ist stark für Nvidia A100- und H100-GPUs optimiert und liefert maximale Leistung auf Systemen mit diesen GPUs.
Dorado wurde ausgiebig getestet und wird auf den folgenden Systemen unterstützt:
| Plattform | GPU/CPU | Mindestanforderungen an die Software |
|---|---|---|
| Linux x86_64 | (G)V100, A100 | CUDA-Treiber ≥450.80.02 |
| H100 | CUDA-Treiber ≥520 | |
| Linux arm64 | Jetson Orin | Linux für Tegra ≥34.1.1 |
| Windows x86_64 | (G)V100, A100 | CUDA-Treiber ≥452.39 |
| H100 | CUDA-Treiber ≥520 | |
| Apfel | Apple Silicon (M1/M2) |
Linux- oder Windows-Systeme, die oben nicht aufgeführt sind, aber über Nvidia-GPUs mit ≥8 GB VRAM und einer Architektur ab Pascal verfügen (außer P100/GP100), wurden nicht ausführlich getestet, funktionieren aber voraussichtlich. Beim Basecalling mit Apple-Geräten empfehlen wir Systeme mit ≥16 GB einheitlichem Speicher.
Wenn bei der Ausführung auf Ihrem System Probleme auftreten, melden Sie bitte ein Problem.
AWS-Benchmarks zu Nvidia-GPUs für Dorado 0.3.0 sind hier verfügbar. Bitte beachten Sie: Die Basecalling-Geschwindigkeit von Dorado verbessert sich kontinuierlich, sodass diese Benchmarks möglicherweise nicht die Leistung der neuesten Version widerspiegeln.
Für eine optimale Leistung benötigt Dorado die Eingabe einer POD5-Datei. Bitte konvertieren Sie Ihre .fast5-Dateien vor dem Basecalling.
Dorado erkennt automatisch den freien Speicher Ihrer GPU und wählt eine geeignete Stapelgröße aus.
Dorado wird automatisch im Multi-GPU- cuda:all Modus ausgeführt. Wenn Sie über eine heterogene Sammlung von GPUs verfügen, wählen Sie die schnelleren GPUs mit dem Flag --device aus (z. B. --device cuda:0,2 ). Wenn Sie dies nicht tun, wirkt sich dies nachteilig auf die Leistung aus.
Im Folgenden finden Sie hilfreiche Befehle für den Einstieg in Dorado. Um alle Optionen und ihre Standardeinstellungen anzuzeigen, führen Sie dorado -h und dorado <subcommand> -h aus.
Dorado kann anhand einer Auswahl der Modellgeschwindigkeit ( fast , hac , sup ) und der Pod5-Daten automatisch ein Basecalling-Modell auswählen. Diese Funktion wird für Fast5-Daten nicht unterstützt. Wenn das Modell nicht lokal vorhanden ist, lädt Dorado das Modell automatisch herunter und verwendet es.
Dorado unterstützt weiterhin Modellpfade.
Weitere Informationen finden Sie im Abschnitt Automatische Modellauswahl.
Um Dorado Basecalling auszuführen, verwenden Sie das automatisch heruntergeladene hac Modell in einem Verzeichnis mit POD5-Dateien oder einer einzelnen POD5-Datei (.fast5-Dateien werden unterstützt, sind aber nicht so leistungsstark) .
$ dorado basecaller hac pod5s/ > calls.bam
Um eine einzelne Datei als Basis aufzurufen, ersetzen Sie einfach das Verzeichnis pod5s/ durch einen Pfad zu Ihrer Datendatei.
Wenn das Basecalling unterbrochen wird, ist es möglich, das Basecalling aus einer BAM-Datei fortzusetzen. Verwenden Sie dazu das Flag --resume-from um den Pfad zur unvollständigen BAM-Datei anzugeben. Zum Beispiel:
$ dorado basecaller hac pod5s/ --resume-from incomplete.bam > calls.bam
calls.bam enthält alle Lesevorgänge aus incomplete.bam sowie die neuen Basisaufrufe ( incomplete.bam kann verworfen werden, nachdem der Basisaufruf abgeschlossen ist) .
Hinweis: Es ist wichtig, einen anderen Dateinamen für die BAM-Datei zu wählen, in die Sie schreiben, wenn Sie --resume-from verwenden . Wenn Sie denselben Dateinamen verwenden, gehen in der unterbrochenen BAM-Datei die vorhandenen Basecalls verloren und Basecalling wird von vorne neu gestartet.
Dorado kann alle Adapter- und/oder Primersequenzen am Anfang und Ende von DNA-Lesevorgängen erkennen und entfernen. Beachten Sie, dass, wenn Sie beabsichtigen, die Lesevorgänge zu einem späteren Zeitpunkt zu demultiplexen, das Trimmen von Adaptern und Primern dazu führen kann, dass einige Teile der flankierenden Bereiche der Barcodes entfernt werden, was die korrekte Demultiplexierung beeinträchtigen könnte.
Standardmäßig versucht dorado basecaller , alle Adapter- oder Primersequenzen am Anfang und Ende von Lesevorgängen zu erkennen und sie aus der Ausgabesequenz zu entfernen.
Diese Funktionalität kann durch die Verwendung der Optionen --trim oder --no-trim mit dorado basecaller geändert werden. Die Option --no-trim verhindert das Trimmen erkannter Barcode-Sequenzen sowie das Erkennen und Trimmen von Adapter- und Primersequenzen.
Die Option --trim akzeptiert als Argument einen der folgenden Werte:
all Dies ist dasselbe wie das Standardverhalten. Alle erkannten Adapter oder Primer werden gekürzt. Wenn Barcode aktiviert ist, werden alle erkannten Barcodes gekürzt.
primers Dies führt dazu, dass alle erkannten Adapter oder Primer gekürzt werden. Wenn die Barcode-Funktion jedoch aktiviert ist, werden die Barcode-Sequenzen nicht gekürzt.
adapters Dies führt dazu, dass alle erkannten Adapter gekürzt werden, Primer werden jedoch nicht gekürzt, und wenn Barcode aktiviert ist, werden auch Barcodes nicht gekürzt.
none Dies ist dasselbe wie die Verwendung der Option --no-trim. Es wird nichts beschnitten.
Wenn das Trimmen von Adaptern/Primern im Einklang mit Basecalling in Kombination mit Demultiplexing erfolgt, stellt die Software automatisch sicher, dass das Trimmen von Adaptern und Primern den Demultiplexing-Prozess nicht beeinträchtigt. Wenn Sie das Demultiplexen jedoch später als separaten Schritt durchführen möchten, wird empfohlen, das Adapter-/Primer-Trimmen beim Basecalling mit der Option --no-trim zu deaktivieren, um sicherzustellen, dass alle Barcode-Sequenzen bei den Lesevorgängen vollständig intakt bleiben.
Vorhandene basenbasierte Datensätze können an beiden Enden nach Adapter- und/oder Primersequenzen durchsucht werden und alle gefundenen Sequenzen werden gekürzt. Führen Sie dazu Folgendes aus:
$ dorado trim <reads> > trimmed.bam
<reads> kann entweder eine Datei im HTS-Format (z. B. FASTQ, BAM usw.) oder ein Stream eines HTS-Formats (z. B. die Ausgabe von Dorado Basecalling) sein.
Die Option --no-trim-primers kann verwendet werden, um das Trimmen von Primersequenzen zu verhindern. In diesem Fall werden nur Adaptersequenzen gekürzt.
Wenn Sie auch beabsichtigen, die Daten zu demultiplexen, wird empfohlen, dass Sie vor dem Trimmen von Adaptern und Primern demultiplexen, da das vorherige Trimmen von Adaptern und Primern die korrekte Barcode-Klassifizierung beeinträchtigen kann.
Bei der Ausgabe von dorado trim handelt es sich immer um nicht ausgerichtete Datensätze, unabhängig davon, ob die Eingabe ausgerichtet/sortiert ist oder nicht.
Die Software sucht automatisch nach Primersequenzen, die in Oxford Nanopore-Kits verwendet werden. Sie können jedoch einen alternativen Satz von Primersequenzen angeben, nach denen beim Trimmen entweder inline mit Basecalling oder in Kombination mit der Option --trim gesucht werden soll. In beiden Fällen erfolgt dies über die Befehlszeilenoption --primer-sequences , gefolgt vom vollständigen Pfad und Dateinamen einer FASTA-Datei, die die Primersequenzen enthält, nach denen Sie suchen möchten. Die Datensatznamen der Sequenzen spielen keine Rolle. Beachten Sie, dass bei Verwendung dieser Option nicht nach den normalen, in der Dorado-Software integrierten Primersequenzen gesucht wird.
Adapter für RNA002- und RNA004-Kits werden beim Basecalling automatisch getrimmt. Allerdings kann der RNA-Adapter im Gegensatz zur DNA nach dem Basecalling nicht gekürzt werden.
Über die herkömmliche A-, T-, C- und G-Basecalling hinaus kann Dorado auch modifizierte Basen wie 5-Methylcytosin (5 mC), 5-Hydroxymethylcytosin (5 hmC) und N 6 -Methyladenosin (6 mA) erkennen. Diese modifizierten Basen spielen eine entscheidende Rolle bei der epigenetischen Regulation.
Um Änderungen aufzurufen, erweitern Sie das Argument „models“ um eine durch Kommas getrennte Liste von Änderungen:
$ dorado basecaller hac,5mCG_5hmCG,6mA pod5s/ > calls.bam
Im obigen Beispiel wird Basecalling mit der Erkennung von 5mC/5hmC in CG-Kontexten und 6mA in allen Kontexten durchgeführt.
In der Spalte „Kompatible Modifikationen“ der Tabelle „DNA-Modelle“ finden Sie verfügbare Modifikationen, die mit der Option --modified-bases aufgerufen werden können.
Modifiziertes Basecalling wird auch mit Duplex-Basecalling unterstützt, wo es Hemimethylierungsaufrufe erzeugt.
Um Duplex-Basecalling auszuführen, führen Sie den folgenden Befehl aus:
$ dorado duplex sup pod5s/ > duplex.bam
Bei Verwendung des duplex -Befehls werden zwei Arten von DNA-Sequenzergebnissen erzeugt: „Simplex“ und „Duplex“. Jede spezifische Position in der DNA, die sich in einem Duplex-Read befindet, ist auch in zwei Simplex-Strängen (Matrize und Komplement) zu sehen. Somit wird jede DNA-Position, die duplexsequenziert wird, durch mindestens drei separate Messwerte in der Ausgabe abgedeckt.
Das dx Tag im BAM-Datensatz für jeden Lesevorgang kann zur Unterscheidung zwischen Simplex- und Duplex-Lesevorgängen verwendet werden:
dx:i:1 für Duplex-Lesevorgänge.
dx:i:0 für Simplex-Lesevorgänge, die keine Duplex-Nachkommen haben.
dx:i:-1 für Simplex-Lesevorgänge, die Duplex-Nachkommen haben.
Dorado gibt die Duplexrate als Anzahl der Nukleotide in den Duplex-Basecalls multipliziert mit zwei und dividiert durch die Gesamtzahl der Nukleotide in den Simplex-Basecalls an. Dieser Wert ist eine gute Näherung für den Anteil der Nukleotide, die an einem Duplex-Basecall beteiligt waren.
Duplex-Basecalling kann mit modifizierter Basenerkennung durchgeführt werden, wodurch Hemimethylierungsaufrufe für Duplex-Reads erzeugt werden:
$ dorado duplex hac,5mCG_5hmCG pod5s/ > duplex.bam
Weitere Informationen zur Darstellung von Hemimethylierungsaufrufen finden Sie auf Seite 7 des SAM-Spezifikationsdokuments (Version aa7440d) und in der Modkit-Dokumentation.
Dorado unterstützt die Ausrichtung vorhandener Basisaufrufe oder die direkte Erstellung ausgerichteter Ausgaben.
Führen Sie Folgendes aus, um vorhandene Basecalls auszurichten:
$ dorado aligner <index> <reads> > aligned.bam
Dabei ist index ein Verweis auf die Ausrichtung im (FASTQ/FASTA/.mmi)-Format und reads ein Ordner oder eine Datei in einem beliebigen HTS-Format.
Beim Lesen aus einem Eingabeordner unterstützt dorado aligner auch die Ausgabe ausgerichteter Dateien an einen Ausgabeordner, wodurch die Dateistruktur der Eingaben erhalten bleibt:
$ dorado aligner <index> <input_read_folder> --output-dir <output_read_folder>
Mit der Option --emit-summary kann eine Ausrichtungszusammenfassung mit Ausrichtungsstatistiken für jeden Lesevorgang generiert werden. Die Datei wird im Ordner --output-dir gespeichert.
Um einen Basisaufruf mit Ausrichtung auf Duplex oder Simplex durchzuführen, führen Sie ihn mit der Option --reference aus:
$ dorado basecaller <model> <reads> --reference <index> > calls.bam
Die Ausrichtung verwendet minimap2 und standardmäßig die Voreinstellung lr:hq . Dies kann überschrieben werden, indem eine Minimap-Optionszeichenfolge, --mm2-opts , mit der Option „-x“ und/oder einzelnen Optionen wie -k und -w übergeben wird, um kmer bzw. Fenstergröße festzulegen. Für eine vollständige Liste der unterstützten Minimap2-Optionen verwenden Sie „--mm2-opts --help“. Zum Beispiel:
$ dorado aligner <index> <input_read_folder> --output-dir <output_read_folder> --mm2-opt "-x splice --junc-bed <annotations_file>" $ dorado aligner <index> <input_read_folder> --output-dir <output_read_folder> --mm2-opt --help $ dorado basecaller <model> <reads> --reference <index> --mm2-opt "-k 15 -w 10" > calls.bam
Der Befehl dorado summary gibt eine durch Tabulatoren getrennte Datei mit Informationen zur Lesestufensequenzierung aus der BAM-Datei aus, die während des Basecalling generiert wurde. Um eine Zusammenfassung zu erstellen, führen Sie Folgendes aus:
$ dorado summary <bam> > summary.tsv
Beachten Sie, dass die Zusammenfassungsgenerierung nur für Lesevorgänge verfügbar ist, die aus POD5-Dateien aufgerufen werden. Basecallte Lesevorgänge aus .fast5-Dateien sind nicht mit dem Zusammenfassungsbefehl kompatibel.
Dorado unterstützt die Barcode-Klassifizierung für bestehende Basecalls sowie die direkte Erstellung klassifizierter Basecalls.
In diesem Modus werden Lesevorgänge während des Basecallings als Teil desselben Befehls in ihre Barcodegruppen klassifiziert. Um dies zu aktivieren, führen Sie Folgendes aus:
$ dorado basecaller <model> <reads> --kit-name <barcode-kit-name> > calls.bam
Dies führt zu einem einzelnen Ausgabestream mit klassifizierten Lesevorgängen. Die Klassifizierung wird sowohl im Lesegruppennamen als auch im BC -Tag des Ausgabedatensatzes widergespiegelt.
Standardmäßig ist Dorado so eingerichtet, dass der Barcode aus den Lesevorgängen entfernt wird. Um das Trimmen zu deaktivieren, fügen Sie --no-trim zur cmdline hinzu.
Die Standardheuristik für doppelendige Barcodes besteht darin, an beiden Enden des Lesevorgangs nach ihnen zu suchen. Dies führt zu einer höheren Klassifizierungsrate, kann aber auch zu einer höheren Anzahl falsch positiver Ergebnisse führen. Um dieses Problem zu beheben, bietet dorado basecaller auch die Option --barcode-both-ends um zu erzwingen, dass doppelseitige Barcodes vor der Klassifizierung an beiden Enden erkannt werden. Dadurch werden Fehlalarme drastisch reduziert, aber auch die Gesamtklassifizierungsraten sinken.
Die Ausgabe von dorado basecaller kann mithilfe von dorado demux in BAMs pro Barcode demultiplext werden. z.B
$ dorado demux --output-dir <output-dir> --no-classify <input-bam>
Dadurch wird pro Barcode eine BAM-Datei im output-dir ausgegeben.
Die Barcode-Informationen spiegeln sich auch im BAM RG Header wider. Daher ist Demultiplexing auch durch samtools split möglich. z.B
$ samtools split -u <output-dir>/unclassified.bam -f "<output-dir>/<prefix>_%!.bam" <input-bam>
Allerdings verwendet samtools split die vollständige RG Zeichenfolge als Dateinamenssuffix, was zu sehr langen Dateinamen führen kann. Wir empfehlen die Verwendung von dorado demux um barcodierte BAMs aufzuteilen.
Vorhandene Basisdatensätze können mithilfe des eigenständigen demux -Befehls in dorado sowohl klassifiziert als auch in BAMs pro Barcode demultiplext werden. Um dies zu verwenden, führen Sie Folgendes aus
$ dorado demux --kit-name <kit-name> --output-dir <output-folder-for-demuxed-bams> <reads>
<reads> kann entweder ein Ordner oder eine einzelne Datei in einer Datei im HTS-Format (z. B. FASTQ, BAM usw.) oder ein Stream eines HTS-Formats (z. B. die Ausgabe von Dorado Basecalling) sein.
Dies führt dazu, dass im Ausgabeordner mehrere BAM-Dateien generiert werden, eine pro Barcode (formatiert als KITNAME_BARCODEXX.bam ) und eine für alle nicht klassifizierten Lesevorgänge. Wie beim Inline-Modus stehen auch --no-trim und --barcode-both-ends als zusätzliche Optionen zur Verfügung.
Wenn die Eingabedatei ausgerichtet/sortiert ist und --no-trim ausgewählt ist, wird jede der ausgegebenen Barcode-spezifischen BAM-Dateien ebenfalls sortiert und indiziert. Wenn das Zuschneiden jedoch aktiviert ist (was die Standardeinstellung ist), werden die Ausrichtungsinformationen entfernt und die Ausgabe-BAMs sind nicht ausgerichtet. Dies geschieht, weil die Alignment-Tags und -Positionen ungültig werden, sobald eine Sequenz geändert wird.
Hier ist ein Beispiel-Ausgabeordner
$ dorado demux --kit-name SQK-RPB004 --output-dir /tmp/demux reads.fastq $ ls -1 /tmp/demux SQK-RPB004_barcode01.bam SQK-RPB004_barcode02.bam SQK-RPB004_barcode03.bam ... unclassified.bam
Mit der Option --emit-summary in dorado demux kann eine Zusammenfassungsdatei erstellt werden, in der jeder Lesevorgang und sein klassifizierter Barcode aufgeführt sind. Die Datei wird im Ordner --output-dir gespeichert.
Wenn die Eingabedatendateien Zuordnungsdaten enthalten, können diese Informationen in den Ausgabedateien beibehalten werden. Dazu müssen Sie die Option --no-trim verwenden. Durch das Trimmen der Barcodes werden alle Zuordnungsinformationen ungültig, die möglicherweise in den Eingabedateien enthalten sind. Daher schließt die Anwendung alle Zuordnungsinformationen aus, wenn --no-trim nicht angegeben ist.
Es ist auch möglich, dorado demux dazu zu bringen, alle ausgegebenen BAM-Dateien zu sortieren und zu indizieren, die zugeordnete Lesevorgänge enthalten. Um dies zu aktivieren, verwenden Sie die Option --sort-bam . Wenn Sie diese Option verwenden, müssen Sie auch die Option --no-trim verwenden, da durch das Trimmen verhindert wird, dass Zuordnungsinformationen in die Ausgabedateien aufgenommen werden. Indexdateien (Erweiterung .bai) werden nur für BAM-Dateien erstellt, die zugeordnete Lesevorgänge enthalten und sortiert wurden. Beachten Sie, dass das Sortieren der Ausgabedateien bei großen Datensätzen einige Minuten dauern kann.
Dorado ist in der Lage, mithilfe eines Beispielblatts die Barcode-Klassifizierungen auf die vorhandenen zu beschränken und Aliase auf die erkannten Klassifizierungen anzuwenden. Dies wird ermöglicht, indem der Pfad zu einem Beispielblatt an das Argument --sample-sheet übergeben wird, wenn die Befehle basecaller oder demux verwendet werden. Weitere Informationen finden Sie hier.
Neben der Unterstützung der Standard-Barcode-Kits von Oxford Nanopore unterstützt Dorado auch die Angabe benutzerdefinierter Barcode-Kit-Anordnungen und -Sequenzen. Dies erfolgt durch Übergabe einer Barcode-Anordnungsdatei über das Argument --barcode-arrangement (entweder an dorado demux oder dorado basecaller ). Benutzerdefinierte Barcode-Sequenzen können optional über die Option --barcode-sequences angegeben werden. Weitere Einzelheiten finden Sie hier.
Dorado bietet erste Unterstützung für die Schätzung der Poly(A)-Schwanzlängen für cDNA (PCS- und PCB-Kits) und RNA. Beachten Sie, dass Oxford Nanopore-cDNA-Reads in zwei verschiedenen Orientierungen sequenziert werden und die Dorado-Poly(A)-Schwanzlängenschätzung beide (A- und T-Homopolymere) verarbeitet. Diese Funktion kann durch Übergabe --estimate-poly-a an den Befehl basecaller aktiviert werden. Es ist standardmäßig deaktiviert. Die geschätzte Schwanzlänge wird im pt:i -Tag des Ausgabedatensatzes gespeichert. Lesevorgänge, für die die Schwanzlänge nicht geschätzt werden konnte, verfügen nicht über das pt:i -Tag. Benutzerdefinierte Primersequenzen und die Schätzung unterbrochener Enden können über die Option --poly-a-config konfiguriert werden. Weitere Einzelheiten finden Sie hier.
Dorado unterstützt die Single-Read-Fehlerkorrektur durch die Integration des HERRO-Algorithmus. HERRO verwendet eine All-vs-All-Ausrichtung, gefolgt von einer Haplotyp-bewussten Korrektur unter Verwendung eines Deep-Learning-Modells, um höhere Einzellesegenauigkeiten zu erreichen. Die korrigierten Lesevorgänge sind in erster Linie für die Generierung von De-novo- Assemblierungen diploider Organismen nützlich.
Um Lesevorgänge zu korrigieren, führen Sie Folgendes aus:
$ dorado correct reads.fastq > corrected_reads.fasta
Dorado Correct unterstützt nur FASTQ(.gz) als Eingabe und generiert eine FASTA-Datei als Ausgabe. Die Eingabe kann unkomprimiert oder mit bgz komprimiert werden. Für die FASTQ-Eingabedatei wird im selben Ordner eine Indexdatei generiert, sofern nicht bereits eine vorhanden ist. Bitte stellen Sie sicher, dass der Ordner mit der Eingabedatei für den dorado -Prozess beschreibbar ist und über ausreichend Speicherplatz verfügt.
Das Fehlerkorrekturtool ist sowohl rechen- als auch speicherintensiv. Daher lässt es sich am besten auf einem System mit mehreren Hochleistungs-CPU-Kernen (>= 64 Kerne), großem Systemspeicher (>= 256 GB) und einer modernen GPU mit großem VRAM (>= 32 GB) ausführen.
Alle erforderlichen Modellgewichte werden von Dorado automatisch heruntergeladen. Allerdings können die Gewichtungen auch vorab heruntergeladen und im Falle einer Offline-Ausführung über die Befehlszeile übergeben werden. Führen Sie dazu Folgendes aus:
$ dorado download --model herro-v1 $ dorado correct -m herro-v1 reads.fastq > corrected_reads.fasta
Dorado Correct bietet jetzt auch eine Funktion zum individuellen Ausführen von Mapping (nur CPU-Stufe) und Inferenz (GPU-intensive Stufe). Dies ermöglicht die Trennung der CPU- und GPU-intensiven Stufen in einzelne Schritte, die sogar auf verschiedenen Knoten mit entsprechenden Recheneigenschaften ausgeführt werden können. Beispiel:
$ dorado correct reads.fastq --to-paf > overlaps.paf $ dorado correct reads.fastq --from-paf overlaps.paf > corrected_reads.fasta
Gzipped PAF wird derzeit für die Option --from-paf nicht unterstützt.
Wenn ein Lauf gestoppt wurde oder fehlgeschlagen ist, bietet Dorado Correct außerdem eine „Fortsetzungs“-Funktion. Die Resume-Funktion nimmt eine Liste zuvor korrigierter Lesevorgänge (z. B. einen .fai Index aus dem vorherigen Lauf) und überspringt die zuvor verarbeiteten Lesevorgänge:
$ samtools faidx corrected_reads.1.fasta # Output from the previously interrupted run. $ dorado correct reads.fastq --resume-from corrected_reads.1.fasta.fai > corrected_reads.2.fasta
Das Eingabedateiformat für die Funktion --resume-from kann eine beliebige Nur-Text-Datei sein, in der die erste durch Leerzeichen getrennte Spalte (oder eine vollständige Zeile) aus zu überspringenden Sequenznamen besteht, einer pro Zeile.
Falls der Prozess zu viel Speicher für Ihr System verbraucht, versuchen Sie, ihn mit einer kleineren Indexgröße auszuführen. Zum Beispiel:
$ dorado correct reads.fastq --index-size 4G > corrected_reads.fasta
Die automatisch berechnete Inferenz-Batchgröße ist möglicherweise immer noch zu hoch für Ihr System. Wenn Warnungen/Fehler bezüglich des verfügbaren GPU-Speichers angezeigt werden, versuchen Sie, die Stapelgröße zu reduzieren bzw. sie manuell auszuwählen. Zum Beispiel:
$ dorado correct reads.fastq --batch-size <number> > corrected_reads.fasta
Falls Ihre FASTA-Ausgabedatei im Vergleich zur Eingabe nur eine sehr geringe Anzahl korrigierter Lesevorgänge enthält, überprüfen Sie bitte Folgendes:
Der Eingabedatensatz hat eine durchschnittliche Leselänge >=10kbp . Dorado Correct ist für lange Lesevorgänge konzipiert und funktioniert nicht bei kurzen Bibliotheken.
Die Eingabeabdeckung ist angemessen, vorzugsweise >=30x .
Überprüfen Sie die durchschnittlichen Basisqualitäten des Eingabedatensatzes. Dorado Correct erwartet genaue Eingaben sowohl für die Zuordnung als auch für die Inferenz.
Um alle verfügbaren Dorado-Modelle herunterzuladen, führen Sie Folgendes aus:
$ dorado download --model all
Die Namen der Dorado-Modelle sind systematisch strukturiert, wobei jedes Segment einem anderen Aspekt des Modells entspricht, der sowohl Chemie als auch Laufeinstellungen umfasst. Nachfolgend finden Sie eine Erläuterung eines Beispielmodellnamens:
Analyttyp ( dna ) : Dies bezeichnet den Typ des zu sequenzierenden Analyten. Bei der DNA-Sequenzierung wird es als dna dargestellt. Wenn Sie ein Direct RNA Sequencing Kit verwenden, ist dies je nach Kit rna002 oder rna004 .
Porentyp ( r10.4.1 ) : Dieser Abschnitt entspricht dem Typ der verwendeten Durchflusszelle. Beispielsweise wird FLO-MIN114/FLO-FLG114 durch r10.4.1 angezeigt, während FLO-MIN106D/FLO-FLG001 durch r9.4.1 gekennzeichnet wird.
Chemietyp ( e8.2 ) : Dies stellt den Chemietyp dar, der dem für die Sequenzierung verwendeten Kit entspricht. Beispielsweise wird die Chemie von Kit 14 mit e8.2 und Kit 10 oder Kit 9 mit e8 bezeichnet.
Translokationsgeschwindigkeit ( 400bps ) : Dieser Parameter, der beim Lauf-Setup in MinKNOW ausgewählt wird, bezieht sich auf die Geschwindigkeit der Translokation. Bevor Sie Ihren Lauf starten, werden Sie gefragt, ob Sie lieber mit 260 bps oder 400 bps laufen möchten. Ersteres liefert genauere Ergebnisse, liefert jedoch weniger Daten. Ab MinKNOW Version 23.04 ist die 260-Bit/s-Option veraltet.
Modelltyp ( hac ) : Dies stellt die Größe des Modells dar, wobei größere Modelle genauere Basecalls liefern, aber mehr Zeit in Anspruch nehmen. Die drei Modelltypen sind fast , hac und sup . Das fast Modell ist das schnellste, sup das genaueste und hac bietet ein Gleichgewicht zwischen Geschwindigkeit und Genauigkeit. Für die meisten Benutzer wird das hac -Modell empfohlen.
Modellversionsnummer ( v5.0.0 ) : Dies gibt die Version des Modells an. Modellaktualisierungen werden regelmäßig veröffentlicht und höhere Versionsnummern bedeuten in der Regel eine höhere Genauigkeit.
Nachfolgend finden Sie eine Tabelle der verfügbaren Basecalling-Modelle und der modifizierten Basecalling-Modelle, die damit verwendet werden können. Die fett gedruckten Modelle gelten für den neuesten veröffentlichten Zustand mit 5-kHz-Daten.
Die Versionierung von Modifikationsmodellen ist an das Basecalling-Modell gebunden. Dies bedeutet, dass die Modifikationsmodellversion bei jeder neuen Simplex-Modellversion zurückgesetzt wird. Beispielsweise ist 6mA@v1 das mit Basecalling-Modellen v4.3.0 kompatibel ist, neuer als 6mA@v2 das mit Basecalling-Modellen v4.2.0 kompatibel ist.
| Basecalling-Modelle | Kompatibel Änderungen | Änderungen Modell Version | Daten Probenahme Frequenz |
|---|---|---|---|
| [email protected] | 5 kHz | ||
| [email protected] | 4mC_5mC 5mCG_5hmCG 5mC_5hmC 6mA | v2 v2 v2 v2 | 5 kHz |
| [email protected] | 4mC_5mC 5mCG_5hmCG 5mC_5hmC 6mA | v2 v2.0.1 v2.0.1 v2 | 5 kHz |
| [email protected] | 5 kHz | ||
| [email protected] | 5mCG_5hmCG 5mC_5hmC 6mA | v1 v1 v2 | 5 kHz |
| [email protected] | 5mCG_5hmCG 5mC_5hmC 6mA | v1 v1 v2 | 5 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 5 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 5 kHz |
| [email protected] | 5mCG_5hmCG 5mC_5hmC 5mC 6mA | v3.1 v1 v2 v3 | 5 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG_5hmCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 5mCG | v2 | 4 kHz |
| [email protected] | 4 kHz | ||
| [email protected] | 5mCG_5hmCG 5mCG | v0 v0.1 | 4 kHz |
| [email protected] | 5mCG_5hmCG 5mCG | v0 v0.1 | 4 kHz |
| [email protected] | 5mCG_5hmCG 5mCG | v0 v0.1 | 4 kHz |
Hinweis: Das BAM-Format unterstützt keine U Basen. Wenn Dorado RNA-Basecalling durchführt, enthalten die resultierenden Ausgabedateien daher T anstelle von U . Dies gilt für alle Ausgabedateitypen.
| Basecalling-Modelle | Kompatibel Änderungen | Änderungen Modell Version | Daten Probenahme Frequenz |
|---|---|---|---|
| [email protected] | 4 kHz | ||
| [email protected] | m5C m6A_DRACH Inosin_m6A pseU | v1 v1 v1 v1 | 4 kHz |
| [email protected] | m5C m6A_DRACH Inosin_m6A pseU | v1 v1 v1 v1 | 4 kHz |
| [email protected] | 4 kHz | ||
| [email protected] | m6A m6A_DRACH pseU | v1 v1 v1 | 4 kHz |
| [email protected] | m6A m6A_DRACH pseU | v1 v1 v1 | 4 kHz |
| [email protected] | 4 kHz | ||
| [email protected] | 4 kHz | ||
| [email protected] | m6A_DRACH | v1 | 4 kHz |
| rna002_70bps_fast@v3 | 3 kHz | ||
| rna002_70bps_hac@v3 | 3 kHz |
Das model in Dorado kann entweder einen Modellpfad oder einen Modellkomplex angeben. Ein Modellkomplex muss mit dem Simplex-Modell speed beginnen und folgt dieser Syntax:
(fast|hac|sup)[@(version|latest)][,modification[@(version|latest)]][,...]
Automatisch ausgewählte Modifikationsmodelle stimmen immer mit der Basisversion des Simplex-Modells überein und sind die neueste kompatible Version, es sei denn, der Benutzer legt eine bestimmte Version fest. Durch die automatische Auswahl des Modifikationsmodells ist das Mischen von Modifikationsmodellen, die an verschiedene Simplex-Modellversionen gebunden sind, nicht möglich.
Hier einige Beispiele für Modellkomplexe:
| Modellkomplex | Beschreibung |
|---|---|
| schnell | Neuestes kompatibles schnelles Modell |
| hac | Neuestes kompatibles HAC- Modell |
| sup | Neuestes kompatibles Sup -Modell |
| hac@latest | Neuestes kompatibles HAC- Simplex-Basecalling-Modell |
| [email protected] | Simplex-Basecalling- HAC- Modell mit Version v4.2.0 |
| [email protected] | Simplex-Basecalling- HAC- Modell mit Version v3.5.0 |
| hac,5mCG_5hmCG | Neuestes kompatibles Hac- Simplex-Modell und neuestes 5mCG_5hmCG- Modifikationsmodell für das ausgewählte Basecall-Modell |
| hac,5mCG_5hmCG@v2 | Neuestes kompatibles Hac- Simplex-Modell und 5mCG_5hmCG- Modifikationsmodell mit Version v2.0.0 |
| sup,5mCG_5hmCG,6mA | Neuestes kompatibles Sup- Modell und neueste kompatible 5mCG_5hmCG- und 6mA- Modifikationsmodelle |
Sobald der automatische Modellauswahlprozess anhand der Eingabedaten das passende Modell gefunden hat, sucht er nach vorhandenen Modellverzeichnissen, um ein unnötiges Herunterladen von Modellen zu vermeiden. Das Verhalten dieser Suche kann wie folgt gesteuert werden:
Festlegen des CLI-Arguments --models-directory – Das Argument --models-directory kann verwendet werden, um ein Verzeichnis anzugeben, in dem nach Modellen gesucht wird.
Festlegen der Umgebungsvariablen DORADO_MODELS_DIRECTORY – Dies entspricht dem Festlegen von --models-directory , hat jedoch eine niedrigere Priorität als das CLI-Äquivalent.
Wenn weder --models-directory noch DORADO_MODELS_DIRECORY festgelegt sind, wird das aktuelle Arbeitsverzeichnis durchsucht.
Wenn --models-directory oder DORADO_MODELS_DIRECTORY automatisch festgelegt ist, bleiben heruntergeladene Modelle bestehen, andernfalls werden Modelle in ein lokales temporäres Verzeichnis heruntergeladen und gelöscht, nachdem Dorado fertig ist.
Dorado ist mit den für die Ausführung erforderlichen Bibliotheken (z. B. CUDA) ausgestattet. Bei einigen Betriebssystemen werden jedoch möglicherweise die Systembibliotheken den Dorado-Bibliotheken vorgezogen. Diese Diskrepanz kann zu verschiedenen Fehlern führen, zum Beispiel zum CuBLAS error 8 .
Um dieses Problem zu beheben, müssen Sie LD_LIBRARY_PATH so einstellen, dass es auf die Bibliotheken von Dorado verweist. Verwenden Sie unter Linux einen Befehl wie den folgenden (ändern Sie den Pfad entsprechend):
$ export LD_LIBRARY_PATH=<PATH_TO_DORADO>/dorado-x.y.z-linux-x64/lib:$LD_LIBRARY_PATH
Unter macOS wäre der entsprechende Export (Pfad entsprechend ändern):
$ export DYLD_LIBRARY_PATH=<PATH_TO_DORADO>/dorado-x.y.z-osx-arm64/lib:$DYLD_LIBRARY_PATH
Duplex-Basecalling ist ein E/A-intensiver Prozess und kann bei Verwendung von Netzwerkspeicher oder Festplatte eine schlechte Leistung erbringen. Dies kann im Allgemeinen durch eine entsprechende Aufteilung der POD5-Dateien verbessert werden.
Installieren Sie zunächst die POD5-Python-Tools:
Die POD5-Dokumentation finden Sie hier.
$ pip install pod5
Führen Sie dann pod5 view aus, um eine Tabelle mit Informationen zu generieren, nach denen insbesondere die „Kanal“-Informationen aufgeteilt werden sollen.
$ pod5 view /path/to/your/dataset/ --include "read_id, channel" --output summary.tsv
Dadurch wird die Datei „summary.tsv“ erstellt, die wie folgt aussehen sollte:
read_id channel 0000173c-bf67-44e7-9a9c-1ad0bc728e74 109 002fde30-9e23-4125-9eae-d112c18a81a7 463 ...
Führen Sie nun pod5 subset aus, um Datensätze aus Ihren Quelldaten in Ausgaben pro Kanal zu kopieren. Dies kann je nach Größe Ihres Datensatzes einige Zeit dauern
$ pod5 subset /path/to/your/dataset/ --summary summary.tsv --columns channel --output split_by_channel
Der obige Befehl erstellt das Ausgabeverzeichnis split_by_channel und schreibt darin eine pod5-Datei pro eindeutigem Kanal. Das Duplex-Basecalling dieser geteilten Lesevorgänge wird jetzt viel schneller sein.
Wenn Sie Duplex-Basecalling verteilt ausführen (z. B. auf einem SLURM- oder Kubernetes-Cluster), ist es wichtig, POD5-Dateien wie oben beschrieben aufzuteilen. Der Grund dafür ist, dass Duplex-Basecalling eine Aggregation von Lesevorgängen aus einem gesamten Sequenzierungslauf erfordert, die über mehrere POD5-Dateien verteilt werden. Die oben beschriebene Aufteilungsstrategie stellt sicher, dass sich alle Lesevorgänge, die aggregiert werden müssen, in derselben POD5-Datei befinden. Sobald die Aufteilung durchgeführt wurde, kann man mehrere Jobs für kleinere Teilmengen von POD5 ausführen (z. B. einen Job pro 100 Kanäle). Dadurch kann Basecalling auf alle Knoten in einem Cluster verteilt werden. Dadurch werden mehrere BAMs generiert, die zusammengeführt werden können. Dieser Ansatz bietet auch eine gewisse Ausfallsicherheit, denn wenn ein Job fehlschlägt, kann er neu gestartet werden, ohne dass Basecalling für den gesamten Datensatz erneut ausgeführt werden muss.
Dorado läuft auf einer breiten Palette von GPUs, wurde jedoch hauptsächlich für Nvidia A100/H100 und Apple Silicon entwickelt. Dorado versucht, die optimale Batch-Größe für Basecalling zu finden. Dennoch kann es bei einigen GPUs mit wenig RAM zu Abstürzen aufgrund von Speichermangel kommen.
Eine mögliche Lösung für dieses Problem könnte darin bestehen, mithilfe des folgenden Befehls eine manuelle Stapelgröße festzulegen:
dorado basecaller --batchsize 64 ...
Hinweis: Die Reduzierung des Speicherverbrauchs durch Ändern des chunksize -Parameters wird nicht empfohlen, da dies die Basecalling-Ergebnisse beeinflusst.
Eine geringe GPU-Auslastung kann zu einer verringerten Basecalling-Geschwindigkeit führen. Dieses Problem kann mit Tools wie nvidia-smi und nvtop identifiziert werden. Eine niedrige GPU-Auslastung ist häufig auf E/A-Engpässe beim Basecalling zurückzuführen. Hier sind einige Schritte, die Sie unternehmen können, um die Situation zu verbessern:
Entscheiden Sie sich für POD5 anstelle von .fast5: POD5 bietet eine überlegene I/O-Leistung und erhöht die Basisaufrufgeschwindigkeit in Umgebungen mit eingeschränkter I/O.
Übertragen Sie Daten vor dem Basecalling auf die lokale Festplatte: Langsames Basecalling kommt häufig vor, weil Netzwerkfestplatten Dorado nicht mit ausreichender Geschwindigkeit versorgen können. Um dies zu verhindern, stellen Sie sicher, dass sich Ihre Daten so nah wie möglich an Ihrem Host-Computer befinden.
Wählen Sie SSD statt HDD: Insbesondere beim Duplex-Basecalling kann die Verwendung einer lokalen SSD erhebliche Geschwindigkeitsvorteile bieten. Dies ist darauf zurückzuführen, dass der Duplex-Basecalling-Algorithmus auf starken Direktzugriff auf Daten angewiesen ist.
Bei der Ausführung in PowerShell unter Windows ist Vorsicht geboten, da die Standardkodierung für die Anwendungsausgabe normalerweise UTF-16LE ist. Dies führt zu einer Dateibeschädigung, wenn die Standardausgabe in eine Datei umgeleitet wird. Es wird empfohlen, das Argument --output-dir zum Ausgeben von BAM-Dateien zu verwenden, wenn PowerShell verwendet werden muss. Der folgende Befehl erzeugt beispielsweise eine beschädigte Ausgabe, die von samtools nicht gelesen werden kann:
PS > dorado basecaller <args> > out.bam
Verwenden Sie stattdessen:
PS > dorado basecaller <args> --output-dir .
Bei textbasierten Ausgabeformaten (SAM oder FASTQ) ist es möglich, die Kodierung bei der Ausgabe mit dem Befehl out-file zu überschreiben. Dieser Befehl erstellt eine wohlgeformte ASCII-SAM-Datei:
PS > dorado basecaller <args> --emit-sam | out-file -encoding Ascii out.sam
Beachten Sie, dass out-file mit Ascii -Kodierung keine wohlgeformten BAM-Dateien erzeugt.
Lesen Sie hier mehr über die Powershell-Ausgabekodierung.
(c) 2024 Oxford Nanopore Technologies PLC.
Dorado wird unter den Bedingungen der Oxford Nanopore Technologies PLC vertrieben. Öffentliche Lizenz, Version 1.0. Wenn mit dieser Datei keine Kopie der Lizenz verteilt wurde, können Sie eine unter http://nanoporetech.com erhalten
