From af75797867c529652ec22de973b747d96ba7fcb3 Mon Sep 17 00:00:00 2001 From: Nils Homer Date: Mon, 20 Jul 2026 18:44:57 -0700 Subject: [PATCH] docs(codec): document the CODEC model and its quality-masking options `fgumi codec --help` had `long_about = None`, so it showed only the one-line about. Nothing explained CODEC's defining property -- that both strands of a source duplex molecule arrive in a single read pair, R1 carrying one strand and R2 the other, so duplex evidence comes from comparing the two reads rather than from grouping reads across the file the way `duplex` does. That is what a user needs in order to know when this command applies. Nor was anything documented about --single-strand-qual, --outer-bases-qual / --outer-bases-length, --min-duplex-length, or the two --max-duplex-disagreement* flags -- several of which mask quality rather than discard bases, which is not guessable from the flag name. The same hole appeared in the generated Tool Reference. The new text also notes that --methylation-mode is unsupported for CODEC; the flag is absent from the command entirely. --- src/lib/commands/codec.rs | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/src/lib/commands/codec.rs b/src/lib/commands/codec.rs index 641a8281c..49bebd733 100644 --- a/src/lib/commands/codec.rs +++ b/src/lib/commands/codec.rs @@ -166,7 +166,40 @@ struct CollectedCodecMetrics { #[command( name = "codec", about = "\x1b[38;5;180m[CONSENSUS]\x1b[0m \x1b[36mCall CODEC consensus reads from grouped BAM\x1b[0m", - long_about = None + long_about = r#" +Calls consensus reads from CODEC (Concatenating Original Duplex for Error Correction) data. CODEC +libraries place both strands of a source duplex molecule into a single read pair, so unlike `duplex` +-- which combines two separately sequenced single-strand consensus reads -- the two strands arrive +already paired: R1 carries one strand and R2 carries the other. + +Consequently each input read pair yields at most one consensus fragment, and the duplex evidence +comes from comparing R1 against R2 rather than from grouping reads across the file. Prior to running +this tool, reads must have been grouped with `group`. + +The consensus reads produced are unaligned fragments, so they should be aligned afterwards. + +Quality masking +--------------- + +Several options reduce base qualities in regions where the duplex evidence is weaker, rather than +discarding the bases outright: + + --single-strand-qual caps quality in regions covered by only one strand, where there is + no duplex confirmation + --outer-bases-qual / caps quality for the first and last --outer-bases-length bases (5 by + --outer-bases-length default) of the fragment, which are the most error-prone + +Duplex agreement filters +------------------------ + + --min-duplex-length minimum overlap, in bases, between the two strands for a fragment to + be emitted (default 1) + --max-duplex-disagreement-rate maximum fraction of overlapping positions where the strands may + disagree (default 1.0, i.e. no limit) + --max-duplex-disagreements maximum absolute count of such disagreements + +Note that `--methylation-mode` is not supported for CODEC data. +"# )] pub struct Codec { /// Input/output BAM options