The Medaka polishing model¶

Why BacFlux polishes an ONT assembly with a bacterial methylation model when Dorado basecalled it with a canonical one.

If you read nothing else

You do not have to do anything. medaka_model: auto is the default and resolves to the bacterial methylation model. Confirmed on real R10.4.1 sup reads: it selects r1041_e82_400bps_bacterial_methylation_model.
It is worth about 4x. Against the standard model on the same ten genomes, 26 residual errors versus 100.
It is not a mismatch. Methylation distorts the signal, so the canonical basecaller makes the errors; the polisher corrects them. You polish with a methylation-aware model because basecalling was not one.
Polish only structurally sound assemblies. A missing plasmid makes its reads misalign elsewhere, and Medaka then introduces errors rather than removing them.
Override in one case: amplified DNA. PCR or whole-genome amplification erases methylation, so pin the standard model instead — at roughly four times the residual errors, which is the right trade there and nowhere else.
If you find advice to skip Medaka on sup reads, it predates the bacterial model and does not apply. See below.

Everything after this is the evidence for those six points, with sources, and a final section separating what is documented from what is inference.

Terms used on this page


ONT	Oxford Nanopore Technologies, the long-read sequencing platform

What BacFlux does¶

In long-read modes (nanopore, hybrid) with medaka_model: auto, BacFlux asks Medaka to resolve the model from the reads themselves, requesting the bacterial variant — workflow/scripts/12_medaka_check/medaka_model_check.py:

medaka tools resolve_model --auto_model consensus_bacteria <reads>

Medaka reads the basecall_model_version_id tag out of the FASTQ headers, maps it to the matching consensus model, and then substitutes the bacterial model — but only if the detected basecaller is on its compatibility list. On a typical R10.4.1 sup run this resolves to r1041_e82_400bps_bacterial_methylation.

That command is character-for-character what medaka_consensus itself runs for its --bacteria flag, so auto really does get the bacterial model — this is verified against the installed Medaka source, not inferred. If resolution fails (no basecaller tag, or a tag Medaka's lookup does not know) the check exits 1 with a suggestion table; it never falls back to a non-bacterial model. Model choice is worth that strictness: across ten genomes it was the difference between 26 and 100 residual errors (Wick 2025).

This happens in check_medaka_model (workflow/rules/shared/12_medaka_check.smk), which runs before assembly so a bad or incompatible model fails in seconds rather than after the assembler has spent an hour.

Naming drift: dorado polish --bacteria

Wick's 2026 posts recommend dorado polish --bacteria in place of Medaka. As of his 2025-02-07 measurement the two shipped identical model weights, though he hedged that with "At the time of writing" and nobody has re-checked since. Noted only so the tool names in those posts do not read as a contradiction of this page; BacFlux stays on Medaka.

Why this is not a mismatch¶

The objection assumes "methylation model" means the same thing at both stages. It does not — the two are different tools doing different jobs:

	Dorado modified-base model	Medaka bacterial model
Stage	basecalling	consensus polishing
Job	reports methylation (`MM`/`ML` tags, per-base 5mC/6mA)	corrects errors caused by methylation
Effect on the A/C/G/T sequence	none	changes it
Output	an epigenetic annotation	a more accurate consensus

The Medaka bacterial model is not the polishing counterpart of a Dorado modified-base model. It is a consensus model for ordinary canonical basecalls, specialised for the case where the template DNA is methylated.

The model-matching rule is still satisfied. Medaka models must match the error profile of the basecaller that produced the reads — ONT states this directly:

"it is important to specify the correct inference model, according to the basecaller used." — Medaka README (nanoporetech/medaka, v2.2.1)

The bacterial model declares compatibility with nine canonical basecaller models (hac and sup, v4.2.0 → v6.0.0; medaka/options.py, bact_methyl_compatible_models). There are no modified-base models on that list. If it required methylation-aware basecalling, it would name those instead. Medaka enforces this: an incompatible basecaller raises RuntimeError rather than silently polishing with the wrong model (medaka/models.py).

The point that resolves the paradox¶

The methylation errors exist because the basecaller was not methylation-aware. Bacteria methylate their own genomes (6mA, 5mC, 4mC, largely via restriction–modification systems). A modified base shifts the raw nanopore current away from the canonical signal, so a canonical basecaller — which can only emit A/C/G/T — misreads those positions systematically, at the same sequence motifs every time. Because the errors are systematic rather than random, more coverage does not remove them.

Those errors are already in the basecalls. The bacterial polishing model is trained to correct exactly that residue, which is why ONT scopes it to native material:

"For native data with bacterial modifications, such as bacterial isolates, metagenomic samples, or plasmids expressed in bacteria, there is a research model that shows improved consensus accuracy." — Medaka README (nanoporetech/medaka, v2.2.1)

ONT's own words: a research model, whose compatibility is deliberately broad — "compatible with several basecaller versions for the R10 chemistries".

Corollary. Had the run been basecalled with modified-base models, the A/C/G/T sequence would be unchanged. Dorado documents modified basecalling as "an extension to the normal simplex and duplex basecalling subcommands" whose output is "annotated in the SAM/BAM/CRAM output" through MM/ML tags — an annotation layer over the canonical calls rather than a re-derivation of them. You would gain methylation calls and keep exactly the same methylation-induced errors, so the same Medaka model would still be the right choice.

Does it actually help?¶

The peer-reviewed measurement is Nagy et al. / NEKSUS Consortium (2026): 92 clinical Enterobacterales, R10.4.1 chemistry, Dorado sup v5.0.0 basecalls, assembled with Flye, Hybracter and Autocycler and polished with Medaka v2.

"Medaka polishing with un-subsampled long-reads resulted in small improvements in indels, but not SNVs for both Flye and Autocycler assemblies."

"Seven-locus multi-locus sequence type, antimicrobial resistance, virulence and stress gene annotation was equivalent across assembler/polisher combinations."

— Nagy et al. / NEKSUS Consortium (2026), Microbial Genomics 12(2):001631. https://www.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.001631

It is the only published benchmark run on the configuration BacFlux actually uses: Wick's polishing comparisons are all on Autocycler assemblies or on deliberately degraded Raven drafts, never on Flye. In practice, expect Medaka to take out indels, and expect typing, AMR and virulence calls to come out the same either way.

A smaller and earlier observation, on two bacterial genomes, compared Medaka v2 with the bacterial model against the previous release:

Genome	Errors before	Errors after
Campylobacter lari	18	2
Enterobacter cloacae	11	10

Wick RR (2024) Medaka v2: progress and potential pitfalls. https://rrwick.github.io/2024/10/17/medaka-v2.html

Two genomes is a small sample, and the gain is variable — large on one, marginal on the other. Expect it to scale with how heavily methylated the organism is, not to be a fixed benefit.

The largest tally is 147 assemblies, where the bacterial model improved 129 and made 6 worse (Wick 2026). A strong default, not a guarantee: the cases that get worse are the ones covered by the structural warning below.

An older recommendation said the opposite, and is still findable

In October 2023, Wick tested Medaka on sup basecalls and concluded: "it performed erratically with the sup/res assemblies, making things worse more often than better", recommending "Use Medaka if you are assembling hac reads but skip it for sup/res reads" (post).

That test used r1041_e82_400bps_sup_v4.2.0 — the standard model. The bacterial model did not exist yet. Measured against each other on the same ten genomes, the standard model left 100 residual errors and the bacterial model 26, which is the gap that reverses the advice. Polishing sup reads with the standard model is still a bad idea; polishing them with the bacterial model is the current recommendation.

A separate pitfall worth knowing¶

Unrelated to model choice: polish only structurally sound assemblies. In the 2024 post above, where small plasmids were absent from the assembly, their reads misaligned elsewhere and Medaka introduced over 100 erroneous changes. A missing replicon is therefore not merely an omission: it corrupts the sequence that is present.

Wick broadened the warning in a 2025-02-25 revision of his assembly guide:

"Structural errors in your assembly (such as missing plasmids or start-end overlap of circular contigs) can sometimes lead to Medaka increa[s]ing the number of errors." — https://rrwick.github.io/2020/10/30/guide-to-bacterial-genome-assembly.html

So a missing plasmid is one case of a wider problem: an unresolved start–end overlap on a circular contig does the same. BacFlux's reorientation, plasmid-recovery and replicon-audit steps run before polishing partly for this reason.

Overriding the model¶

The bacterial model assumes native, unamplified DNA. Amplification — ONT's PCR barcoding kit (SQK-RPB114.24) or a whole-genome amplification protocol — copies the template with unmodified bases, so the methylation the model corrects for is no longer there. If a library was amplified, pin the matched standard model instead of auto:

parameters:
  nanopore:            # or: hybrid
    medaka_model: r1041_e82_400bps_sup_v4.2.0

That is the standard, non-bacterial model, and on Wick's measurements it leaves roughly four times the residual errors the bacterial one does — still the right choice on amplified DNA, but a real cost.

check_medaka_model validates any explicit name against the installed Medaka's model list and fails early with a suggestion table if it is wrong. Amplification status cannot be read from the reads; it has to come from the lab record.

Sourcing: what is documented, what is inference¶

Stated so the claims above can be defended or challenged individually.

Verified from primary sources

The consensus_bacteria call, and the early-validation rule — read from this repository (medaka_model_check.py, 12_medaka_check.smk).
The nine compatible canonical basecaller models, the substitution logic, and the RuntimeError on incompatibility — read from the installed Medaka 2.2.2 source (options.py, models.py).
"native data with bacterial modifications… improved consensus accuracy", "research model", "compatible with several basecaller versions", and the model-matching requirement — quoted from ONT's Medaka README (v2.2.1).
That --auto_model consensus_bacteria is the same call medaka_consensus makes for its --bacteria flag, and the exit-1-on-failure behaviour — read from the installed Medaka source and from medaka_model_check.py.
The 92-isolate Flye/Hybracter/Autocycler result and the annotation-equivalence statement — quoted verbatim from Nagy et al. (2026), cited above.
The error counts for C. lari and E. cloacae, and the small-plasmid pitfall — Wick (2024), cited above.
The broadened structural-error warning, and the 26-versus-100 residual-error figure for model choice — Wick (2025), cited above.

Inference, not quoted from documentation

The biological mechanism (6mA/5mC/4mC, restriction–modification systems, signal deviation at modified bases, motif-systematic errors that coverage cannot average out). Standard domain knowledge, but not taken from the sources above.
That amplified DNA is a contraindication. ONT scopes the model to "native data" but does not explicitly warn against amplified input. The caution above is read off that scoping, not quoted from a warning.
That methylation-induced errors are predominantly indels, and that frameshifted or pseudogene counts in the annotation are therefore a good readout for testing the model's benefit.

Not re-checked: whether dorado polish --bacteria still ships the same model weights as Medaka's bacterial model. Wick reported that in February 2025 and hedged it with "At the time of writing"; nothing here verifies it since.

Verified against Dorado 2.1.1, 2026-08-21. Modified-base calling does not feed back into which base is called, so it cannot repair a methylation-induced miscall and does not remove the need for this consensus model. Three independent lines establish it:

Dorado's basecall decoder emits only four symbols — alphabet = {'A','C','G','T'} in basecall/decode/beam_search.cpp. There is no symbol for a modified base. The modbase node reads the called sequence and writes only modification probabilities beside it; it never assigns to the sequence.
ONT's maintainers state the invariant outright, and treat it as a design constraint: "modification calling has no effect on the canonical basecall — you should get exactly the same sequence whether you do modbase or not. This is intentional" (dorado#1494, given as the reason for refusing a feature that would have let a modification probability alter the emitted base).
The SAM specification makes it structural rather than a matter of implementation: base modifications are "a series of edits from the primary unmodified sequence as originally reported by the sequencing instrument" (SAMtags), counted against a SEQ field whose 4-bit alphabet has no code point for 5mC or 6mA.

ONT's own documentation does not say this in words — it describes modified basecalling only as "an extension to the normal simplex and duplex basecalling subcommands" (https://software-docs.nanoporetech.com/dorado/latest/basecaller/mods/).

Two limits on the claim. It says no information flows back into base determination, not that output is byte-identical: enabling modification models changes GPU memory use and can shift the auto-selected batch size, and Dorado is not bit-reproducible across batch sizes — a difference that is non-determinism rather than feedback, and cannot systematically correct motif-specific errors. And it is specific to Dorado's split architecture; it does not hold for older basecallers where basecalling and modification calling happened inside one model.