Upgrading from 2.x

FiberHMM 3.0 is the third generation of the FiberHMM family, released together with FiberBrowser 3.0 (which requires fiberhmm>=3.0,<4). This page lists what 2.x users need to act on. The full list of changes is in the Changelog.

pip install --upgrade fiberhmm      # Python 3.10 to 3.14

Check which outputs need re-running

fiberhmm-check reads what each output records about how it was made and lists the fixes below that apply to it, with the exact command to re-run:

fiberhmm-check data/*.bam qc/*.qc.json consensus_out/

It exits 0 when nothing needs re-running, 3 when something does, 4 when a file holds calls without FiberHMM provenance, which cannot be checked (re-run them if they came from FiberHMM < 3.0), and 2 when a path cannot be checked; --json gives the same result for scripts. fiberhmm-check --list prints every advisory it knows. BAMs record the digests of the tables they were called with since 3.0, so later releases can tell exactly; for 2.x BAMs the check uses the version and command line, and says so when that cannot decide (development builds reported 2.16.8 on both sides of some fixes). See Checking outputs for re-runs.

Re-run Nanopore Hia5 and DddB calls

Updated emission tables

The Nanopore Hia5 and DddB emission tables have been updated (re-calibrated). The Nanopore Hia5 table is rebuilt from matched naked-DNA and untreated controls, and 3.0 nucleosome recall also changed (see the changelog).

Re-run Nanopore Hia5 and DddB calls made with 2.x. Nucleosome, MSP and footprint calls all change. The PacBio Hia5 table is unchanged. fiberhmm-check lists the affected files.

The 2.x tables are kept as fiberhmm/models/legacy/hia5_nanopore_gt_swapped_legacy.json and legacy/dddb_nanopore_gt_swapped_legacy.json to reproduce old calls (Bundled models). The model builder now always numbers contexts in encoder order (A, C, T, G); rebuild custom m6A tables made with the 2.x builder with fiberhmm-probs from 3.0.

Re-train models built with --base-model

fiberhmm-train --base-model keeps the base model's transitions and replaces its emissions. With a base whose state 0 is the footprint, such as the Nanopore Hia5 model bundled in 2.x, every 2.x release paired the inherited transitions with inverted states, so the resulting model called accessible DNA as footprint. 3.0 matches the new emission rows to the base model's accessible state. Re-train models built this way with 2.x; fiberhmm-check does not flag them.

Defaults that change numbers

Change	2.x	3.0	To get the 2.x behaviour
ML threshold for Hia5 Nanopore (call, apply, recall-tfs/-nucs, extract, qc, posteriors)	128 / 125	248	--prob-threshold 128 (or 125)
Alignments called by call/apply	all (DAF: primary only)	primary + supplementary (supplementary: aligned bases only)	--no-primary (all), --primary (primary only)
DAF insertion / soft-clip / SNP-masked bases	counted as protected	no evidence; unaligned stretches >= 50 bp uncalled	--no-daf-mask-unaligned
fiberhmm-pipeline DAF soft clips	hard-clipped	kept on linear contigs (hard-clipped on circular ones); supplementary records kept	--hard-clip, --alignments primary
Bases trimmed at read ends by posteriors	100	10 (as call/apply)	--edge-trim 100
DddA CpG-aware calling: first-pass HMM and recall in call (and pipeline), recall in recall-tfs/-nucs, HMM in apply/posteriors and the qc light call, joint HMM and recall in pair/merge	off	on (ddda_ucg islands exempt)	--no-use-m5c
DAF tools reading MM/ML dU (dedup, pair, merge)	ML 0	ML 128	--prob-threshold 0
DAF duplicate grouping	by alignment orientation	by deamination flavour (more duplicates found; for example 5.8% → 9.9% on one DddA data set)	none
TF recall decoder (all chemistries)	one maximum per positive-score excursion	exact best set of intervals, --min-llr is the per-interval cost (tf_decoder=multi_interval_v1 in @PG)	none
TF --min-llr preset for DddB	4.0	5.0 (as every preset)	--min-llr 4
Nucleosome recall for Hia5 and DddB	periodicity prior (--phase-nrl auto); topology policy for Nanopore Hia5	accessible-cut split, no periodicity prior; nucleosome calls change	none (--phase-nrl and --nuc-recall-policy are retired)
DddA TF table and radial nucleosome recall	2.x ddda_TF.json, radial template	duplex-calibrated ddda_TF.json; phase-aware posterior edges (ddda_nuc_profile.json, ddda_nuc_refine.json)	none
DddA adjacent-target thinning (call, apply, recall-tfs/-nucs, pair/merge, consensus)	off	runs of ≥ 2 CC/GG targets keep one	--daf-mask-runs 0
Looser consensus prevalence tiers (prevalence_edge, prevalence_loose)	could double-count and exceed 1	coherent union; drops by up to about 0.14 (typically 0.002–0.04); core unchanged	none (the old value was an error)

R/Y- and MD-encoded deaminations are binary and unaffected by ML thresholds.

Behaviour that used to fail silently

These now either work or stop with a clear message:

• Unaligned (uBAM) and stdin input are called instead of being skipped as unmapped; a run that skips more than 90% of records as unmapped fails.
• A missing --seq is detected from the input instead of assuming PacBio (so ONT Hia5 is no longer silently called as PacBio).
• A custom --model inherits the input's declared chemistry; conflicts stop with a one-line fix (--replace-chemistry to re-declare).
• Worker failures above 1% of reads fail the run; outputs are published atomically, so a failed run leaves no valid-looking partial BAM.
• Hard-clipped supplementary records whose MM/ML cannot match SEQ are skipped instead of being called on the wrong bases.
• fiberhmm-tag-m5c writes unmethylated islands (ddda_ucg), so recall-tfs --use-m5c no longer masks every CpG.
• fiberhmm-apply -c 1 no longer crashes on DAF strand-swap chimeras.
• fiberhmm-posteriors decodes reverse reads in the right frame and handles DAF.
• Re-deduplicating a BAM that already carries duplicate marks (a 2.x output, or fiberhmm-call on one) recomputes them: fiberhmm-dedup clears the earlier 0x400 flags and di/ds tags before marking.
• fiberhmm-recall-tfs/-recall-nucs read ns/nl/as/al written by fibertools in molecular frame (reverse-read nucleosomes and MSPs were mirrored), and a merged header whose histories disagree stops the run. See Footprint-tag frame.
• fiberhmm-recall-tfs on a BAM called with --no-legacy-tags reads the MA footprints instead of deleting every annotation.
• fiberhmm-extract keeps intervals whose first or last base is soft-clipped or inserted (on minimap2 ONT/DAF alignments it dropped 11–16% of MSPs and about a quarter of TF calls); re-extract tracks made with 2.x.
• fiberhmm-apply --scores writes MSP aq as mean P(accessible) ×255, as documented (2.x wrote P(footprint), so confident MSPs scored near 0).
• EcoGII and custom-enzyme BAMs are never scored with Hia5 emissions in consensus.

Removed and renamed

2.x	3.0
fiberhmm-run	fiberhmm-call, piped into ft fire if needed
python apply_model.py, extract_tags.py, train_model.py, generate_probs.py, export_posteriors.py, fiberhmm_utils.py	the fiberhmm-* commands
fiberhmm-crossstrand, fiberhmm-duplex (development builds only)	fiberhmm-pair
fiberhmm-merge (development builds only)	still installed but deprecated: fiberhmm-pair --from-paired
fiberhmm-call --ddda-mcg (development builds only)	fiberhmm-tag-m5c, then fiberhmm-call on the tagged BAM (DAF-seq)
fiberhmm-apply --chroms, --skip-scaffolds, --region-size, --scores-db, -l	rejected (they never had an effect); use fiberhmm-call --region-parallel
--phase-nrl, --nuc-recall-policy (call, recall-tfs/-nucs)	retired; nucleosome recall is the accessible-cut split, without a periodicity prior
recaller.abutting (development builds only)	removed; use the "+ edge" tier or recaller.linker=either
--engine staged_native_families (consensus)	deprecated but available
fiberhmm[consensus], fiberhmm[numba]	still accepted; their packages are core dependencies now

fiberhmm-call gained --scores (the fiberhmm-apply spelling; the old --with-scores still works) and -c 0 for all CPUs.

New in 3.0

• The lattice recaller is the default consensus engine, with prevalence tiers, per-channel support and resolution, and per-molecule labels; transfer works with it.
• fiberhmm-consensus and fiberhmm-transfer work on a plain pip install fiberhmm.
• fiberhmm-recall-tfs/-recall-nucs accept --prob-threshold; fiberhmm-call, -apply, -posteriors, -recall-tfs/-recall-nucs, -pair/-merge and -pipeline accept --use-m5c/--no-use-m5c and --cpg-mask-policy.
• fiberhmm-apply --harmonize-legacy-tags (opt-in) writes ns/nl as the nucleosomes of the MA view, so they tile with as/al. Each such read carries hl:i:1, and fiberhmm-recall-tfs/-recall-nucs refuse it, because recall needs every HMM footprint in ns/nl. Re-calling or re-applying without the option removes the tag.
• fiberhmm-call output carries @CO fiberhmm:coord=molecular, so its footprint frame survives a pipeline that strips @PG (Coordinate frames).
• This documentation site, with a generated command-line reference.

FiberBrowser

FiberBrowser 3.0 requires FiberHMM 3.x. Reload BAMs called with 3.0 to get the updated Nanopore Hia5 and DddB calls and the lattice-recaller class layers.