codec
Category: CONSENSUS
Call CODEC consensus reads from grouped BAM
Description
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. fgumi realign
aligns them, preferring the region each molecule’s raw reads aligned to, when the input was grouped with
fgumi group --realign-window.
Quality masking
Several options overwrite base qualities in regions where the duplex evidence is weaker, rather than discarding the bases outright. Each assigns its value unconditionally, so a position whose quality is already lower is raised to it:
–single-strand-qual sets quality to this value in regions covered by only one strand, where there is no duplex confirmation –outer-bases-qual / sets quality to this value for the first and last –outer-bases-length –outer-bases-length bases (5 by 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
–legacy-overlap-window use fgbio’s legacy [neg.start, pos.end] overlap window, which
rejects dovetailed short-insert pairs as dovetails and matches
fgbio’s current-release consensus output (off by default; the
corrected intersection window admits those pairs)
Note that --methylation-mode is not supported for CODEC data.
Arguments
| Flag | Description | Default |
|---|---|---|
-i, --input <INPUT> | Input BAM file | required |
-o, --output <OUTPUT> | Output BAM file | required |
--async-reader <ASYNC_READER> | Enable async userspace prefetch on the input BAM | false |
--check-crc <CHECK_CRC> | Verify each BGZF block’s CRC32 checksum while decoding the input | false |
--no-check-crc <NO_CHECK_CRC> | Skip CRC32 verification while decoding the input | false |
-r, --rejects <REJECTS> | Optional output BAM file for rejected reads | |
-s, --stats <STATS> | Optional output file for statistics | |
-p, --read-name-prefix <READ_NAME_PREFIX> | Prefix for consensus read names | |
-R, --read-group-id <READ_GROUP_ID> | Read group ID for consensus reads | A |
-1, --error-rate-pre-umi <ERROR_RATE_PRE_UMI> | Phred-scaled error rate prior to UMI integration | 45 |
-2, --error-rate-post-umi <ERROR_RATE_POST_UMI> | Phred-scaled error rate post UMI integration | 40 |
-m, --min-input-base-quality <MIN_INPUT_BASE_QUALITY> | Minimum base quality in raw reads to use for consensus | 10 |
| `-B, –output-per-base-tags <true | false>` | Produce per-base tags (cd, ce) in addition to per-read tags. The default (true) matches fgbio, which always writes per-base tags; setting this to false drops per-base tags that fgbio emits unconditionally |
--tie-rule <TIE_RULE> | How to resolve a near-tie between the two most likely consensus bases | fgbio-compat |
--threads <THREADS> | Number of worker threads for the processing pipeline | |
--compression-level <COMPRESSION_LEVEL> | Compression level for output BAM (0-12) | 1 |
-M, --min-reads <MIN_READS> | Minimum read pairs per strand to form consensus (fgbio’s --min-read-pairs) | 1 |
--max-reads <MAX_READS> | Maximum read pairs per strand, downsample if exceeded (fgbio’s --max-read-pairs) | |
-d, --min-duplex-length <MIN_DUPLEX_LENGTH> | Minimum duplex overlap length in bases | 1 |
--legacy-overlap-window <LEGACY_OVERLAP_WINDOW> | Use fgbio’s legacy [negative.start, positive.end] duplex overlap window instead of the corrected intersection window (fgumi#761) | |
--single-strand-qual <SINGLE_STRAND_QUAL> | Set single-strand region quality to this value (0-93). Assigned unconditionally, so a lower quality is raised to it. Note: This uses a different short flag than duplex’s -q for min-base-quality | |
-Q, --outer-bases-qual <OUTER_BASES_QUAL> | Set outer bases quality to this value (0-93). Assigned unconditionally, so a lower quality is raised to it | |
-O, --outer-bases-length <OUTER_BASES_LENGTH> | Number of outer bases to set the quality of | 5 |
-x, --max-duplex-disagreement-rate <MAX_DUPLEX_DISAGREEMENT_RATE> | Maximum duplex disagreement rate (0.0-1.0) | 1.0 |
-X, --max-duplex-disagreements <MAX_DUPLEX_DISAGREEMENTS> | Maximum number of duplex disagreements | |
--metrics <METRICS> | Optional prefix for inline consensus QC metrics — the same duplex-shaped file set duplex-metrics writes (CS/SS/DS family sizes, UMI counts, downsampling yield curve), since codec is DS-capable and shares the Duplex inline-collector variant. Computed inline with no second BAM read. As with duplex --metrics, the inline path does not emit <prefix>.duplex_umi_counts.txt (the tally duplex-metrics gates behind --duplex-umi-counts); run duplex-metrics separately if you need that file | |
--intervals <INTERVALS> | Optional interval file (BED or Picard interval list) restricting which templates contribute to --metrics output. Ignored if --metrics is not set | |
| `–allow-unmapped <true | false>` | Process unmapped reads. By default (fgbio parity, ConsensusCallingIterator.scala:56-58) an unmapped read is dropped before consensus calling whether or not its mate is mapped, as are all secondary/supplementary alignments. Enable for consensus on unmapped input (e.g. ribosome/protein display), mirroring fgumi group --allow-unmapped. Note that codec requires a mapped FR pair, so it emits no consensus for an unmapped pair even with this flag |
--scheduler <SCHEDULER> | Inert scheduler strategy (see [SchedulerStrategy]); the chain engine does not use it to assign thread work. Retained for backward compatibility only — the values below describe what each once meant to the removed legacy engine: | balanced-chase-drain |
--pool-scheduler <POOL_SCHEDULER> | Override for the chain-builder pool dispatch scheduler (hidden; A/B knob) | auto |
| `–pipeline-stats <true | false>` | Print detailed pipeline statistics at completion |
--pipeline-trace <PIPELINE_TRACE> | Per-edge instrumentation level: off | summary | timeline | deep | off |
--pipeline-trace-out <PIPELINE_TRACE_OUT> | Path for the --pipeline-trace timeline per-tick TSV (default pipeline-trace.tsv in the working directory) | |
--deadlock-timeout <SECONDS> | Seconds without progress before the deadlock watchdog reports a stall | 10 |
| `–deadlock-recover <true | false>` | Enable automatic deadlock recovery (default: false, detection only) |
--pipeline-telemetry-out <PIPELINE_TELEMETRY_OUT> | File stem for the per-tick thread-telemetry TSVs — six files, <stem>.ticks.{summary,edges,workers,steps,counters,counter_names}.tsv (summary/edges/workers/counters carry a row per tick; steps/counter_names are written once). Setting this (or the FGUMI_PIPELINE_TELEMETRY_OUT env var) enables telemetry; the default stem when neither is set but telemetry is otherwise requested is pipeline-telemetry | |
--pipeline-telemetry-interval <PIPELINE_TELEMETRY_INTERVAL> | Sample/emit cadence for thread telemetry, e.g. 2ms, 500us, 1s (default: 2ms). Also settable via FGUMI_PIPELINE_TELEMETRY_INTERVAL | |
--max-memory <MAX_MEMORY> | Maximum total memory for the pipeline queues | 768 |
--memory-reserve <MEMORY_RESERVE> | Memory to reserve for other processes when –max-memory=auto | auto |
| `–memory-per-thread <true | false>` | Scale the memory limit by thread count |