richardstoeckl/basecallNanopore

Snakemake Pipeline to automatically basecall Nanopore sequencing data with hybrid approach of simplex and duplex basecalling

Overview

Latest release: v2.0.0, Last update: 2026-09-21

Share link: https://snakemake.github.io/snakemake-workflow-catalog?wf=richardstoeckl/basecallNanopore

Quality control: linting: failed formatting: failed

Deployment

Step 1: Install Snakemake and Snakedeploy

Snakemake and Snakedeploy are best installed via the Conda package manager. It is recommended to install conda via Miniforge. Run

conda create -c conda-forge -c bioconda -c nodefaults --name snakemake snakemake snakedeploy

to install both Snakemake and Snakedeploy in an isolated environment. For all following commands ensure that this environment is activated via

conda activate snakemake

For other installation methods, refer to the Snakemake and Snakedeploy documentation.

Step 2: Deploy workflow

With Snakemake and Snakedeploy installed, the workflow can be deployed as follows. First, create an appropriate project working directory on your system and enter it:

mkdir -p path/to/project-workdir
cd path/to/project-workdir

In all following steps, we will assume that you are inside of that directory. Then run

snakedeploy deploy-workflow https://github.com/richardstoeckl/basecallNanopore . --tag v2.0.0

Snakedeploy will create two folders, workflow and config. The former contains the deployment of the chosen workflow as a Snakemake module, the latter contains configuration files which will be modified in the next step in order to configure the workflow to your needs.

Step 3: Configure workflow

To configure the workflow, adapt config/config.yml to your needs following the instructions below.

Step 4: Run workflow

The deployment method is controlled using the --software-deployment-method (short --sdm) argument.

To run the workflow with automatic deployment of all required software via conda/mamba, use

snakemake --cores all --sdm conda

Snakemake will automatically detect the main Snakefile in the workflow subfolder and execute the workflow module that has been defined by the deployment in step 2.

For further options such as cluster and cloud execution, see the docs.

Step 5: Generate report

After finalizing your data analysis, you can automatically generate an interactive visual HTML report for inspection of results together with parameters and code inside of the browser using

snakemake --report report.zip

Configuration

The following section is imported from the workflow’s config/README.md.

Configuration

The workflow does not load a default configuration. Run it from the repository root and pass your configuration explicitly:

snakemake --configfile config/my-config.yaml --use-conda --cores 16

--use-conda provides POD5, SAMtools, and legacy Guppy helper packages. Dorado and Guppy themselves are external ONT programs and must be installed separately.

Minimal Dorado example

main:
  log_path: logs
  interim_path: interim
  result_path: results

tool_profiles:
  dorado_2_1_2:
    basecaller: dorado
    executable: /opt/dorado-2.1.2/bin/dorado
    expected_version: 2.1.2
    models_directory: models/dorado-2.1.2
    device: cuda:all
    threads: 16

runs:
  - id: run42
    input: /data/run42/pod5
    tool_profile: dorado_2_1_2
    strategy: duplex_replacement
    model: sup@v5.2.0,5mCG_5hmCG@v2
    barcode_kit: SQK-NBD114-96
    fastq_min_qscore: 10

tool_profile determines the basecaller, so a run does not repeat basecaller. Dorado input must be POD5; Guppy input must be FAST5.

Paths

When run as shown above, relative log, interim, and result paths start at the repository root. Relative input, executable, duplex_executable, and models_directory paths are also resolved against that root. ~ and environment variables such as $HOME are expanded for these latter paths.

Executable settings must be paths such as /opt/dorado/bin/dorado or tools/dorado; bare command names such as dorado are rejected. This prevents the workflow from silently using a different installation found on PATH.

Tool profiles

Every profile contains:

  • basecaller: dorado or guppy

  • executable: explicit path to the basecaller

  • expected_version: exact X.Y.Z version expected from --version

  • device: tool device selector, such as cuda:all or cuda:0

  • threads: requested CPU allocation per job. Snakemake may reduce it when --cores is lower. Commands with a thread option receive that allocation; Dorado simplex and Guppy basecalling manage their CPU workers internally. This is a scheduling allowance, not a strict limit on operating-system threads.

Dorado additionally requires models_directory. The workflow creates this directory when needed; Dorado searches it and downloads missing models.

Guppy requires simplex_chunks_per_runner. Duplex replacement also requires duplex_executable and duplex_chunks_per_runner.

--cores is the total CPU budget for the workflow; profile threads is the requested share for one job. For example, --cores 16 with threads: 8 allows two eight-thread CPU jobs, subject to other resource limits. Commands connected by a pipe also have helper processes, so observed CPU use can exceed the stated thread count. These settings do not change the number of GPUs used by Dorado.

There is no YAML GPU-count option. Every basecalling rule requests one Snakemake gpu token, and the workflow supplies a safe global default of one. Setting --resources gpu=2 permits two basecalling jobs; it does not assign them to different devices. Use separate profiles with cuda:0, cuda:1, and so on when deliberately running jobs concurrently.

Runs

Required fields:

  • id: unique filesystem-safe run name

  • input: raw POD5 path for Dorado or FAST5 path for Guppy

  • tool_profile: one configured profile

  • strategy: simplex or duplex_replacement

  • model: Guppy config name (.cfg optional) or strict Dorado model expression

  • barcode_kit: standard ONT barcode kit name

Optional fields:

  • sequencing_kit: Dorado duplex trimming kit; defaults to barcode_kit

  • sample_sheet: optional path to an ONT CSV sample sheet, for Dorado only. Restricts classification to the barcodes listed in its barcode column; optional sample aliases become output folder names. Relative paths start at the repository root. The file is a workflow input, so editing it triggers the affected classification step again.

  • fastq_min_qscore: publish pass FASTQ at this threshold for Dorado; required for Guppy

  • channels_per_shard: positive number of nanopore channels per Dorado duplex job; valid only for duplex_replacement. Omit it to process the run in one job

Unclassified pass reads are always published when FASTQ is enabled. Fail FASTQ is never published. The all-Q-score Dorado BAM remains available.

For example, add sample_sheet: config/run42_samples.csv to a run. Use the ONT sample-sheet format. Omitting this option keeps classification against the full configured kit.

Dorado models and modified bases

Dorado uses one model expression for all required simplex, stereo, and modified-base models:

model: sup@v5.2.0
model: sup@v5.2.0,5mCG_5hmCG@v2

Every component must have an explicit @v... version. @latest and omitted versions are rejected. The same interface applies to simplex and duplex. Dorado records the fully resolved model names in the BAM header.

Output names and archive

Every per-barcode filename contains both run and barcode, for example run42_barcode01_all.bam and run42_barcode01_pass.fastq.gz.

<run>_run_settings.json records the normalized run configuration, complete basecaller --version output, read-decision schema version and workflow source SHA-256 fingerprint (including local edits). Configured sample-sheet records are embedded alongside its original path.

The run’s <run>_read_decisions.tsv.gz is the compressed read-to-barcode and decision record. Full sequencing summaries remain under interim, including both simplex and duplex summaries for Guppy. <run>_metrics.txt counts reads and bases from the final BAMs (Dorado) or pass FASTQs (Guppy), overall and per barcode, with a simplex-versus-duplex comparison for duplex replacement runs. Dorado quality values come from the BAM’s basecaller-reported scores; Guppy quality values are recalculated from the final FASTQ base qualities. The report states which definition it uses. For Dorado duplex runs, it also reports how many final consensuses were rescued, reassigned, supported by agreeing evidence, assigned directly, or left unclassified. Counts are shown for all qualities and, when configured, the pass threshold. The same information appears in the final log and terminal.

Use a fresh result path when changing settings or input data for an existing run. Previously published barcode files are not automatically removed when they are no longer part of the new output. Resuming an unchanged analysis does not require a fresh path.

Read-decision table

<run>_read_decisions.tsv.gz is a gzip-compressed TSV with schema version 1. Each row describes one emitted basecalled record considered by the workflow, including replaced simplex parents and Guppy records rejected by its pass filter. The identity is (read_id, read_type): Guppy can reuse a simplex parent’s ID for its duplex consensus. Rows are not ordered by identity or sequencing time.

Column

Meaning

read_id

Basecalled record identifier.

read_type

simplex or duplex; removed duplex parents are simplex records.

source_read_id

Original signal-read ID for a simplex record, following its splitting metadata. Dorado uses pi when present, otherwise the record ID. Empty when a legacy Guppy summary lacks this information.

parent_1_id, parent_2_id

Duplex parents; join each to a simplex row, then follow source_read_id to the signal data. Empty for simplex.

barcode_before

Direct assignment before workflow reconciliation, including the assignments of removed parents. Empty if a Guppy summary lacks the assignment.

barcode_final

Published barcode/sample bin. Empty for removed records.

barcode_decision

Source or reason for the barcode decision; values below.

read_decision

retained, replaced_by_duplex, or filtered_by_basecaller (Guppy).

length_before

Dorado length in the original basecaller BAM, before demux/publication trimming. Guppy length from its corresponding basecaller summary, which may already reflect basecaller trimming.

length_final

Length in the published BAM or FASTQ; empty for removed records.

mean_qscore_final

Dorado’s final BAM qs, or mean error-probability Q recalculated from the published Guppy FASTQ. Empty for removed records.

fastq_status

exported, below_threshold, export_disabled, or removed_upstream.

Barcode labels unknown and unclassified are normalized to unclassified; kit prefixes are removed from standard barcode labels, while sample aliases are preserved. Empty cells mean unavailable or not applicable, not unclassified. For a sample’s published read set, select read_decision=retained and its barcode_final. To match its pass FASTQ, also select fastq_status=exported. Dorado’s FASTQ decision uses the actual BAM Q-score and configured threshold, not the sequencing summary’s passes_filtering column. Guppy export membership comes from the delivered pass FASTQs, not a new threshold on rounded qualities.

Dorado barcode decisions are:

  • simplex_direct: use the simplex assignment.

  • parent_both: both parents have the same assigned barcode; use it even if the direct consensus assignment differs.

  • parent_one: one parent is assigned and the other unclassified; inherit it unless the consensus has a conflicting assigned barcode.

  • parent_conflict: assigned parents disagree; retain the consensus as unclassified.

  • parent_duplex_conflict: the sole assigned parent and assigned consensus disagree; retain the consensus as unclassified.

  • duplex_direct: neither parent is assigned; keep the direct consensus assignment, which can itself be unclassified.

Guppy uses simplex_direct or duplex_direct; its existing workflow does not reconcile parental barcode evidence. Only an actually emitted passing consensus replaces its parents. Failed consensuses remain recorded as filtered, with their parents retained if those parents passed. A shared Dorado parent has one row and can be referenced by multiple consensus rows.

The table is built from intermediate evidence and the published reads, joined by identity using a temporary disk index. This keeps memory bounded; temporary disk space beside the results is needed during generation and is released afterwards. Dorado reconciliation saves demux/removed_parents.tsv.gz before dropping parents. An older duplex run without that file must rerun reconciliation to generate a complete decision table; the corrected sequencing summary alone is insufficient.

The table explains observable workflow decisions, not internal basecaller scores, pairing attempts that produced no read, or nucleotide-by-nucleotide edits. Detailed sequencing diagnostics remain in the intermediate summaries/BAMs. Length changes record trimming effects, not the exact sequence removed. The workflow fingerprint identifies the code but does not archive a copy of it.

Workflow parameters

The following table is automatically parsed from the workflow’s config.schema.y(a)ml file.

Parameter

Type

Description

Required

Default

main

yes

. log_path

string

yes

. interim_path

string

yes

. result_path

string

yes

tool_profiles

yes

runs

array

yes

Linting and formatting

Linting results
1/home/runner/work/snakemake-workflow-catalog/snakemake-workflow-catalog/.pixi/envs/default/lib/python3.13/site-packages/google/auth/transport/grpc.py:43: FutureWarning: grpcio < 1.83.0 does not support Post-Quantum Cryptography (PQC). Support for non-PQC environments is deprecated. In April 2027, google-auth will raise its minimum requirements to enforce grpcio >= 1.83.0. For more details on Google Cloud's post-quantum security migration, visit: https://cloud.google.com/security/resources/post-quantum-cryptography
2  warnings.warn(
3WorkflowError in file "/tmp/tmpzoyjkeau/richardstoeckl-basecallNanopore-ff28794/workflow/Snakefile", line 21:
4A configuration file is required; use --configfile FILE.yaml
5  File "/tmp/tmpzoyjkeau/richardstoeckl-basecallNanopore-ff28794/workflow/Snakefile", line 21, in <module>
Formatting results
 1[DEBUG] 
 2[DEBUG] 
 3[DEBUG] 
 4[DEBUG] 
 5[DEBUG] 
 6[DEBUG] In file "/tmp/tmpzoyjkeau/richardstoeckl-basecallNanopore-ff28794/workflow/rules/dorado.smk":  Formatted content is different from original
 7[INFO] 1 file(s) would be changed 😬
 8[INFO] 4 file(s) would be left unchanged 🎉
 9
10snakefmt version: 0.11.5