Dorado
Dorado 是一个用于 Oxford Nanopore 读取的高性能、易于使用的开源基序识别器。
特性
- 一个可执行文件，具有合理的默认设置，自动硬件检测和配置。
- 支持在 Apple 硅片（M1/2 系列）和 Nvidia GPU 上运行，包括多 GPU 线性扩展（见平台）。
- 改进的基序识别。
- 双链基序识别（观看以下视频了解双链的介绍）。
- 简单条形码分类。
- 支持对齐读取输出的 SAM/BAM 格式。
- 初始支持 poly(A) 尾部估计。
- POD5 支持最高基序识别性能。
- 基于 libtorch，即 Pytorch 的 C++ API。
- 在 CUDA 和 Metal 中进行了多项自定义优化，以最大化推理性能。
- 如果您在构建或运行 Dorado 时遇到任何问题，请报告问题。
安装
- dorado-0.6.1-linux-x64
- dorado-0.6.1-linux-arm64
- dorado-0.6.1-osx-arm64
- dorado-0.6.1-win64
平台
Dorado 针对 Nvidia A100 和 H100 GPU 进行了大量优化，并将在这些 GPU 系统上提供最大性能。
Dorado 已在以下系统上进行了广泛测试和支持：
| 平台 | GPU/CPU | 最低软件要求 |
|---|---|---|
| Linux x86_64 | (G)V100, A100 | CUDA 驱动 ≥450.80.02 |
| H100 | CUDA 驱动 ≥520 | |
| Linux arm64 | Jetson Orin | Linux for Tegra ≥34.1.1 |
| Windows x86_64 | (G)V100, A100 | CUDA 驱动 ≥452.39 |
| H100 | CUDA 驱动 ≥520 | |
| Apple | Apple 硅片 (M1/M2) |
未在上述列表中列出的 Linux 或 Windows 系统，但具有 Nvidia GPU 且具有 ≥8 GB VRAM 以及从 Pascal 起的架构（除 P100/GP100）尚未广泛测试，但预计可以工作。在使用 Apple 设备进行基序识别时，我们建议使用具有 ≥16 GB 统一内存的系统。
如果您在使用系统时遇到问题，请报告问题。
Dorado 0.3.0 在 Nvidia GPU 上的 AWS 基准测试可以在此处获得。请注意：Dorado 的基序识别速度正在持续改进，因此这些基准测试可能不反映最新版本的表现。
性能提示
为了获得最佳性能，Dorado 需要 POD5 文件输入。请在基序识别之前转换您的 .fast5 文件。
Dorado 将自动检测您的 GPU 的空闲内存，并选择适当的批次大小。
Dorado 将自动在多 GPU cuda:all 模式下运行。如果您有一系列异构 GPU，请使用 --device 标志选择更快的 GPU（例如 --device cuda:0,2）。不这样做将对性能产生不利影响。
运行
以下是一些有助于开始使用 Dorado 的命令。
要查看所有选项及其默认值，请运行 dorado -h 和 dorado <子命令> -h。
模型选择前言
Dorado 可以自动使用模型速度（fast, hac, sup）和 pod5 数据选择一个基序识别模型。此功能不支持 fast5 数据。如果本地不存在模型，则 Dorado 将自动下载模型并在完成后删除它。要重复使用下载的模型，请使用 dorado download 手动下载模型。
Dorado 继续支持模型路径。
有关详细信息，请阅读 自动模型选择复杂。
简单基序识别
要运行 Dorado 基序识别，请使用自动下载的 hac 模型对一个 POD5 文件目录或单个 POD5 文件进行基序识别（支持 .fast5 文件，但性能不会那么好）。
$ dorado basecaller hac pod5s/ > calls.bam
要对单个文件进行基序识别，只需将目录 pod5s/ 替换为您的数据文件路径。
如果基序识别被中断，可以恢复基序识别，从 BAM 文件开始。为此，请使用 --resume-from 标志指定不完整的 BAM 文件的路径。例如：
$ dorado basecaller hac pod5s/ --resume-from incomplete.bam > calls.bam
calls.bam 将包含 incomplete.bam 中的所有读取加上新的基序识别（完成基序识别后可以丢弃 incomplete.bam）。
注意：在使用 --resume-from 时，选择一个不同的 BAM 文件名来写入非常重要。如果您使用相同的文件名，中断的 BAM 文件将丢失现有的基序识别，并且将从一开始就重新开始基序识别。
DNA 适配器和引物修剪
Dorado 可以检测并移除 DNA 读取的开头和结尾的任何适配器和/或引物序列。请注意，如果您打算在某个时候对读取进行去多重化，修剪适配器和引物可能会导致条形码的某些部分被移除，这可能会干扰正确的去多重化。
与基序识别内联
默认情况下，dorado basecaller 将尝试检测读取开头和结尾的任何适配器或引物序列，并将其从输出序列中移除。
此功能可以通过使用 dorado basecaller 的 --trim 或 --no-trim 选项来更改。–no-trim 选项将防止检测到的条形码序列以及适配器和引物序列的修剪。
–trim 选项需要以下值之一作为其参数：
- all 这与默认行为相同。任何检测到的适配器或引物都将被修剪，如果启用了条形码，则任何检测到的条形码也将被修剪。
- primers 这将导致任何检测到的适配器或引物被修剪，但如果启用了条形码，则条形码序列不会被修剪。
- adapters 这将导致任何检测到的适配器被修剪，但引物不会被修剪，如果启用了条形码，则条形码也不会被修剪。
- none 这与使用 --no-trim 选项相同。什么都不会被修剪。
如果与去多重化结合使用的适配器/引物修剪与基序识别内联进行，则软件将自动确保适配器和引物的修剪不会干扰去多重化过程。但是，如果您打算稍后将去多重化作为单独的步骤进行，则建议在基序识别时使用 --no-trim 选项禁用适配器/引物修剪，以确保任何条形码序列在读取中保持完整。
修剪现有数据集
现有的基序识别数据集可以在任一端扫描适配器和/或引物序列，并修剪任何发现的序列。为此，请运行：
$ dorado trim <reads> > trimmed.bam
可以是 HTS 格式文件（例如 FASTQ、BAM 等）或 HTS 格式的流（例如 Dorado 基序识别的输出）。
可以使用 --no-trim-primers 选项来防止修剪引物序列。在这种情况下，只有适配器序列将被修剪。
如果您还打算对数据进行去多重化，则建议在修剪任何适配器和引物之前进行去多重化，因为首先修剪适配器和引物可能会干扰正确的条形码分类。
dorado trim 的输出始终是未对齐的记录，无论输入是已对齐/排序还是未排序。
自定义引物修剪
软件会自动搜索 Oxford Nanopore 试剂盒中使用的引物序列。但是，当在基序识别内联时修剪或与 --trim 选项结合使用时，您可以指定要搜索的另一组引物序列。在这两种情况下，这是通过使用 --primer-sequences 命令行选项完成的，后跟包含要搜索的引物序列的 FASTA 文件的完整路径和文件名。序列的记录名称不重要。请注意，如果使用此选项，则不会搜索内置于 dorado 软件中的常规引物序列。
RNA 适配器修剪
RNA002 和 RNA004 试剂盒的适配器在基序识别期间会自动修剪。然而，与 DNA 不同，RNA 适配器不能在基序识别后修剪。
改进的基序识别
除了传统的 A、T、C 和 G 基序识别外，Dorado 还可以检测修饰基，如 5-甲基胞嘧啶（5mC）、5-羟甲基胞嘧啶（5hmC）和 N6-甲基腺嘌呤（6mA）。这些修饰基在表观遗传调控中扮演着至关重要的角色。
要调用修饰，将模型参数扩展为修饰的逗号分隔列表：
$ dorado basecaller hac,5mCG_5hmCG pod5s/ > calls.bam
请参阅 DNA 模型表的“兼容修饰”列，以查看可与 --modified-bases 选项一起调用的可用修饰。
改进的基序识别也支持双链基序识别，其中它产生半甲基化调用。
双链
要运行双链基序识别，请运行命令：
$ dorado duplex sup pod5s/ > duplex.bam
当使用 duplex 命令时，将产生两种类型的 DNA 序列结果：‘simplex’
和 ‘duplex’。在双链读取中的任何特定 DNA 位置也会在两个单链（模板和互补链）中看到。因此，每个通过双链测序的 DNA 位置将由输出中至少三次独立的读取所覆盖。
BAM 记录中每个读取的 dx 标签可以用来区分单链和双链读取：
- dx:i:1 用于双链读取。
- dx:i:0 用于没有双链后代的单链读取。
- dx:i:-1 用于有双链后代的单链读取。
Dorado 将报告双链率，计算方式是双链基序识别中的核苷酸数量乘以二，然后除以单链基序识别中的总核苷酸数量。这个值是参与双链基序识别的核苷酸比例的近似值。
双链基序识别也可以与修饰基检测一起执行，为双链读取产生半甲基化调用：
$ dorado duplex hac,5mCG_5hmCG pod5s/ > duplex.bam
有关半甲基化调用如何表示的更多信息可以在 SAM 规范文档（版本 aa7440d）和 Modkit 文档的第 7 页找到。
对齐
Dorado 支持对现有的基序识别或直接产生对齐输出进行对齐。
要对现有的基序识别进行对齐，请运行：
$ dorado aligner <index> <reads> > aligned.bam
其中 index 是要对齐的参考（FASTQ/FASTA/.mmi）格式，reads 是任何 HTS 格式的文件夹或文件。
当从输入文件夹读取时，dorado aligner 还支持将对齐的文件发出到输出文件夹，这将保留输入的文件结构：
$ dorado aligner <index> <input_read_folder> --output-dir <output_read_folder>
可以使用 --emit-summary 选项生成包含每个读取的对齐统计信息的对齐摘要。该文件将保存在 --output-dir 文件夹中。
要使用双链或单链进行基序识别和对齐，请使用 --reference 选项运行：
$ dorado basecaller <model> <reads> --reference <index> > calls.bam
对齐使用 minimap2，默认使用 map-ont 预设。这可以通过 -k 和 -w 选项分别设置 kmer 和窗口大小来覆盖。
测序摘要
dorado summary 命令从基序识别期间生成的 BAM 文件输出带有读取级别测序信息的制表符分隔文件。要创建摘要，请运行：
$ dorado summary <bam> > summary.tsv
请注意，摘要生成仅适用于从 POD5 文件基序识别的读取。从 .fast5 文件基序识别的读取与 summary 命令不兼容。
条形码分类
Dorado 支持对现有基序识别的读取进行条形码分类，以及直接产生分类的基序识别。
与基序识别内联
在此模式下，读取在基序识别期间作为同一命令的一部分被分类到它们的条形码组中。要启用此功能，请运行：
$ dorado basecaller <model> <reads> --kit-name <barcode-kit-name> > calls.bam
这将在单个输出流中生成分类的读取。分类将反映在读取组名称以及输出记录的 BC 标签中。
默认情况下，Dorado 设置为从读取中修剪条形码。要禁用修剪，请在命令行中添加 --no-trim。
双端条形码的默认启发式方法是在读取的任一端查找它们。这可以提高分类率，但也可能导致更高的误报计数。为了解决这个问题，dorado basecaller 还提供了 --barcode-both-ends 选项，以强制在分类之前在两端都检测到双端条形码。这将大幅度降低误报，但也会降低总体分类率。
dorado basecaller 的输出可以使用 dorado demux 被去多重化到每个条形码的 BAM 文件中。例如：
$ dorado demux --output-dir <output-dir> --no-classify <input-bam>
这将在 output-dir 中输出每个条形码的 BAM 文件。
分类现有数据集
现有的基序识别数据集也可以使用 dorado 中的独立 demux 命令进行分类和去多重化到每个条形码的 BAM 文件中。要使用此功能，请运行：
$ dorado demux --kit-name <kit-name> --output-dir <output-folder-for-demuxed-bams> <reads>
可以是 HTS 格式文件的文件夹或单个文件（例如 FASTQ、BAM 等），或 HTS 格式的流（例如 dorado 基序识别的输出）。
这将在输出文件夹中生成多个 BAM 文件，每个条形码一个（格式化为 KITNAME_BARCODEXX.bam），以及一个用于所有未分类读取的文件。与内联模式一样，–no-trim 和 --barcode-both-ends 也是可用的附加选项。
如果输入文件是已对齐/排序的，并且选择了 --no-trim，则每个输出特定条形码的 BAM 文件也将被排序和索引。然而，如果启用了修剪（这是默认设置），则对齐信息将被移除，输出的 BAM 文件将未对齐。这是因为一旦序列被更改，对齐标签和位置就会失效。
以下是示例输出文件夹
$ 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
可以使用 dorado demux 中的 --emit-summary 选项生成列出每个读取及其分类条形码的摘要文件。该文件将保存在 --output-dir 文件夹中。
去多重化已映射读取
如果输入数据文件包含映射数据，这些信息可以在输出文件中保留。为此，您必须使用 --no-trim 选项。修剪条形码将使输入文件中可能包含的任何映射信息无效，因此如果未指定 --no-trim，则应用程序将排除任何映射信息。
还可以让 dorado demux 对任何包含已映射读取的输出 bam 文件进行排序和索引。要启用此选项，请使用 --sort-bam 选项。如果您使用此选项，则还必须使用 --no-trim 选项，因为修剪将防止任何映射信息被包含在输出文件中。索引文件（.bai 扩展名）只会为包含已排序的已映射读取的 BAM 文件创建。请注意，对于大型数据集，对输出文件进行排序可能需要几分钟。
使用样本表
Dorado 能够使用样本表将条形码分类限制为仅出现在其中的条形码，并对检测到的分类应用别名。这是通过在使用 basecaller 或 demux 命令时将样本表的路径传递给 --sample-sheet 参数来启用的。有关更多信息，请参见此处。
自定义条形码
除了支持 Oxford Nanopore 的标准条形码试剂盒外，Dorado 还支持指定自定义条形码试剂盒的排列和序列。这是通过将条形码排列文件传递给 --barcode-arrangement 参数（可以是 dorado demux 或 dorado basecaller）来完成的。可以通过 --barcode-sequences 选项选择性地指定自定义条形码序列。有关更多详细信息，请参见此处。
Poly(A) 尾部估计
Dorado 初始支持估算 cDNA（PCS 和 PCB 试剂盒）和 RNA 的 poly(A) 尾部长度。请注意，Oxford Nanopore cDNA 读取以两种不同的方向进行测序，Dorado poly(A) 尾部长度估计处理两者（A 和 T 同聚物）。此功能可以通过向 basecaller 命令传递 --estimate-poly-a 来启用。默认情况下它是禁用的。估计的尾部长度存储在输出记录的 pt:i 标签中。无法估算尾部长度的读取将不包含 pt:i 标签。
请注意，如果使用此选项，则 DNA 的适配器/引物/条形码修剪将自动禁用。
可用的基序识别模型
要下载所有可用的 Dorado 模型，请运行：
$ dorado download --model all
解码 Dorado 模型名称
Dorado 模型的名称是系统化构建的，每个部分对应模型的不同方面，包括化学和运行设置。以下是样本模型名称的解释：
dna_r10.4.1_e8.2_400bps_hac@v4.3.0
- 分析物类型 (dna)：这表示正在测序的分析物类型。对于 DNA 测序，它表示为 dna。如果您使用的是 Direct RNA Sequencing Kit，则根据试剂盒可能是 rna002 或 rna004。
- 孔型 (r10.4.1)：这一部分对应使用的流动池类型。例如，FLO-MIN114/FLO-FLG114 表示为 r10.4.1，而 FLO-MIN106D/FLO-FLG001 表示为 r9.4.1。
- 化学类型 (e8.2)：这代表化学类型，对应于测序所用的试剂盒。例如，Kit 14 化学被表示为 e8.2，而 Kit 10 或 Kit 9 被表示为 e8。
- 跨位速度 (400bps)：这个参数在 MinKNOW 中的运行设置中选择，指的是跨位速度。开始运行之前，系统会提示您是否希望以 260 bps 或 400 bps 运行。前者产生更准确的结果，但提供的数据较少。截至 MinKNOW 版本 23.04，260 bps 选项已被弃用。
- 模型类型 (hac)：这代表模型的大小，较大的模型产生更准确的基序识别，但需要更多时间。三种类型的模型是 fast、hac 和 sup。fast 模型最快，sup 最准确，hac 在速度和准确性之间提供平衡。对于大多数用户，推荐使用 hac 模型。
- 模型版本号 (v4.3.0)：这表示模型的版本。模型更新定期发布，更高的版本号通常意味着更高的准确性。
DNA 模型：
以下是可用的基序识别模型和可与它们一起使用的修饰基序识别模型的表格。加粗的模型是针对最新发布条件的 5 kHz 数据。
修饰模型的版本控制与基序识别模型绑定。这意味着每个新的单链模型发布，修饰模型的版本都会重置。例如，与 v4.3.0 基序识别模型兼容的 6mA@v1 比与 v4.2.0 基序识别模型兼容的 6mA@v2 更新。
| 基序识别模型 | 兼容修饰 | 修饰模型版本 | 数据采样频率 |
|---|---|---|---|
| dna_r10.4.1_e8.2_400bps_fast@v4.3.0 | 5 kHz | ||
| dna_r10.4.1_e8.2_400bps_hac@v4.3.0 | 5mCG_5hmCG5mC_5hmC6mA | v1v1v2 | 5 kHz |
| dna_r10.4.1_e8.2_400bps_sup@v4.3.0 | 5mCG_5hmCG5mC_5hmC6mA | v1v1v2 | 5 kHz |
| … |
RNA 模型：
| 基序识别模型 | 兼容修饰 | 修饰模型版本 | 数据采样频率 |
|---|---|---|---|
| rna004_130bps_fast@v3.0.1 | N/A | N/A | 4 kHz |
| rna004_130bps_hac@v3.0.1 | N/A | N/A | 4 kHz |
| rna004_130bps_sup@v3.0.1 | m6A_DRACH | v1 | 4 kHz |
| rna002_70bps_fast@v3 | N/A | N/A | 3 kHz |
| rna002_70bps_hac@v3 | N/A | N/A | 3 kHz |
自动模型选择复杂性
dorado 中的模型参数可以指定一个模型路径或一个模型复合体。模型复合体必须以单链模型速度开始，并遵循以下语法：
(fast|hac|sup)[@(version|latest)][,modification[@(version|latest)]][,…]
自动选择的修饰模型将始终与基础单链模型版本匹配，并且将是兼容的最新版本，除非用户设置了特定版本。自动修饰模型选择不允许混合不同单链模型版本绑定的修饰模型。
以下是一些模型复合体的示例：
开发者快速入门
Linux 依赖
在裸机环境中构建 Dorado（例如官方的 ubuntu:jammy docker 镜像）所需的以下软件包：
$ apt-get update && apt-get install -y --no-install-recommends \
curl \
git \
ca-certificates \
build-essential \
nvidia-cuda-toolkit \
libhdf5-dev \
libssl-dev \
libzstd-dev \
cmake \
autoconf \
automake
克隆和构建
$ git clone https://github.com/nanoporetech/dorado.git dorado
$ cd dorado
$ cmake -S . -B cmake-build
$ cmake --build cmake-build --config Release -j
$ ctest --test-dir cmake-build
-j 标志将使用所有可用的线程来构建 Dorado，每个线程的使用量约为 1-2 GB。如果您的系统受到可用内存数量的限制，可以减少线程数量，例如 -j 4。
构建完成后，您可以从构建目录 ./cmake-build/bin/dorado 运行 Dorado，或者将其安装在系统的其他位置（例如 /opt，注意：您将需要目标安装目录的相关权限）。
$ cmake --install cmake-build --prefix /opt
预提交
该项目使用 pre-commit 确保代码格式一致；您可以使用 pip 设置：
$ pip install pre-commit
$ pre-commit install
故障排除指南
库路径错误
Dorado 配备了必要的库（如 CUDA）以供执行。然而，在某些操作系统上，系统库可能会被优先选择，这可能导致各种错误，例如 CuBLAS 错误 8。
要解决这个问题，您需要将 LD_LIBRARY_PATH 设置为指向 Dorado 的库。在 Linux 上使用以下命令（根据需要更改路径）：
$ export LD_LIBRARY_PATH=<PATH_TO_DORADO>/dorado-x.y.z-linux-x64/lib:$LD_LIBRARY_PATH
在 macOS 上，等效的导出将是（根据需要更改路径）：
$ export DYLD_LIBRARY_PATH=<PATH_TO_DORADO>/dorado-x.y.z-osx-arm64/lib:$DYLD_LIBRARY_PATH
提高双链基序识别的速度
双链基序识别是一个 I/O 密集型过程，如果使用网络存储或 HDD，可能会表现不佳。这通常可以通过适当地分割 POD5 文件来改善。
首先安装 POD5 python 工具：
$ pip install pod5
然后运行 pod5 view 以生成包含特定分割信息的表格，特别是“通道”信息。
$ pod5 view /path/to/your/dataset/ --include "read_id, channel" --output summary.tsv
这将创建一个“summary.tsv”文件，看起来应该像：
read_id channel
0000173c-bf67-44e7-9a9c-1ad0bc728e74 109
002fde30-9e23-4125-9eae-d112c18a81a7 463
...
现在运行 pod5 subset 将源数据中的记录复制到每个通道的输出中。根据您的数据集大小，这可能需要一些时间。
$ pod5 subset /path/to/your/dataset/ --summary summary.tsv --columns channel --output split_by_channel
上述命令将创建输出目录 split_by_channel，并在其中为每个唯一通道写入一个 pod5 文件。现在对这些分割的读取进行双链基序识别将快得多。
分布式运行双链基序识别
如果在分布式方式下运行双链基序识别（例如在 SLURM 或 Kubernetes 集群上），重要的是按照上述描述分割 POD5 文件。原因是双链基序识别需要聚合整个测序运行中的读取，这些读取将分布在多个 POD5 文件中。
上述分割策略确保了所有需要聚合的读取都在同一个 POD5 文件中。一旦完成分割，就可以对较小的 POD5 子集执行多个作业（例如每个作业处理 100 个通道）。这将允许在集群的节点上分布式进行基序识别。
这将生成多个 BAM 文件，可以合并。这种方法还提供了一些弹性，因为如果任何作业失败，可以重新启动而不必重新对整个数据集进行基序识别。
GPU 内存不足错误
Dorado 在广泛的 GPU 上运行，但主要是为 Nvidia A100/H100 和 Apple Silicon 开发的。Dorado 试图找到最佳的基序识别批次大小。然而，在一些低 RAM GPU 上，用户可能会遇到内存不足的崩溃。
解决这个问题的一个潜在解决方案是使用以下命令设置手动批次大小：
dorado basecaller --batchsize 64 ...
注意：通过修改 chunksize 参数来减少内存消耗是不推荐的，因为它会影响基序识别结果。
低 GPU 利用率
低 GPU 利用率可能导致基序识别速度降低。这个问题可以使用 nvidia-smi 和 nvtop 等工具来识别。低 GPU 利用率通常源于基序识别中的 I/O 瓶颈。以下是您可以采取的一些步骤来改善这种情况：
-
选择 POD5 而不是 .fast5：POD5 具有更好的 I/O 性能，将提高 I/O 受限环境中的基序识别速度。
-
在基序识别之前将数据传输到本地磁盘：缓慢的基序识别通常是由于网络磁盘无法以足够速度供应 Dorado
所需的数据。为了缓解这种情况，请确保您的数据尽可能靠近您的主机。 -
选择 SSD 而不是 HDD：特别是对于双链基序识别，使用本地 SSD 可以提供显著的速度优势。这是由于双链基序识别算法依赖于数据的重随机访问。
415
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
