Preset Machines

May 10, 2026 · View on GitHub

Machine Boss ships with a library of preset machines that can be loaded with the --preset flag. Multiple presets can be chained on one command line to build composite pipelines via transducer composition.

{: .no_toc }

TOC {:toc}

Using Presets

boss --preset NAME              # load preset by name
boss --preset A --preset B      # compose two presets: A then B

To inspect a preset's JSON definition:

boss --preset NAME              # prints JSON to stdout

Sequence Alignment

Preset	Description
`dnapsw`	DNA pairwise alignment (Smith-Waterman) with substitution and gap parameters
`dnapsw_mix2`	DNA alignment with a two-component mixture model
`dnapswnbr`	DNA alignment with neighbor-dependent substitution context
`protpsw`	Protein pairwise alignment (Smith-Waterman) with 20-amino-acid substitution matrix
`psw2dna`	Protein-to-DNA alignment: protein Smith-Waterman composed with reverse translation
`pswint`	Protein Smith-Waterman with intron support (allows GT-AG spliced introns)

These are transducers that read one sequence as input and write an aligned sequence as output. They include parameterized gap-open and gap-extend penalties, substitution weights, and (for psw2dna and pswint) the genetic code.

Evolutionary Models

Preset	Description
`jukescantor`	Jukes-Cantor model of DNA sequence divergence
`tkf91-root-dna-jc`	TKF91 root: geometric DNA singlet, P(L=k)=κ^k(1−κ) with κ=insRate/delRate
`tkf91-branch-dna-jc`	TKF91 branch transducer: 7-state DNA + Jukes-Cantor substitutions

The standalone tkf92-branch-prot-f81 preset was retired in favour of the parameterised CLI flag --tkf92-branch-prot-f81 (see below) — the new preset emits a 6-state WFST that correctly factors the joint TKF92 pair HMM by the zero-inflated --tkf92-root singlet (ν = r + (1−r)κ); the old hand-tuned 5-state version did not. Use the parameterised flag or --evolmoves-branch-prot-f81 (the 5-state regularised conditional pair HMM that composes with --evolmoves-root to recover the same joint matrix).

The TKF91 (Thorne, Kishino, Felsenstein 1991) and TKF92 (1992) models are continuous-time Markov models of sequence evolution with insertions, deletions, and substitutions; TKF92 adds a fragment-extension parameter that clusters indels into runs. tkf91-root-dna-jc is a generator (output only) that produces the root sequence; the *-branch-* presets are conditional WFST transducers that evolve an input sequence to an output sequence. Together root and branch model pairwise evolution.

Parameterised CLI generators

Any combination of TKF version, root/branch, alphabet, and substitution model can be constructed on the fly via the CLI flag --tkfYY-TTT-AAA-MMM:

YY is 91, 92, iid, or evolmoves.
- 91 and 92 give the canonical TKF91 / TKF92 root + branch transducers. The TKF92 branch is the 6-state WFST [begin, match, hold, insert, delete, end] that correctly factors the joint TKF92 pair HMM by the zero-inflated TKF92 root singlet (the extra hold state distinguishes pre-input from post-input inserts so the divisor on transitions out of begin/hold is κ — singlet still at start — while out of match/insert/delete it is ν — singlet in its insert loop). See ~/tkf-mixdom/tkf/tkf92-wfst-derivation.tex.
- iid is the zero-indel-rate degeneration of TKF91: the branch transducer collapses to a single emit state with self-loops, with no insert/delete states (every input symbol maps 1:1 to an output symbol). The iid root is structurally identical to the TKF91 root (a 2-state geometric-length emitter), but the length-extension probability is exposed as a free parameter pExtend instead of being derived from insRate/delRate.
- evolmoves is a TKF92 variant whose root is a non-zero-inflated ν-geometric singlet — P(L=0)=1−ν, P(L=k≥1)=ν^k·(1−ν) — and whose 5-state branch is the regularised conditional pair HMM that uniformly divides input-consuming transitions by ν. Composing --evolmoves-root with --evolmoves-branch recovers the standard TKF92 5-state joint pair HMM matrix entries to ulp; composing --tkf92-root with --tkf92-branch (the 6-state) recovers the same joint. The two pairs are equivalent factorisations of the same model; evolmoves uses the 5-state regularised branch as its move-proposal likelihood and the 6-state TKF92 branch as its per-branch simulator.
- All four versions accept the TKF92 fragment-extension probability r; for iid r is unused.
TTT is root or branch.
AAA is dna, rna, prot, binary, unary, or custom (followed by the alphabet string).
MMM is one of:
- jc (Jukes-Cantor; uniform π).
- f81 (free per-symbol π_X).
- k80 (transition/transversion ratio tsRatio, DNA/RNA only).
- hky85 (free π_X + tsRatio, DNA/RNA only).
- id (no substitution; required for unary alphabet root).
- telegraph (binary 2-state CTMC with independent rates rate01 and rate10; stationary π_0 = rate10/(rate01+rate10), π_1 = rate01/(rate01+rate10) — these are derived via defs from the rates, not free parameters; binary alphabet only).
- bsc (Binary Symmetric Channel: symmetric Telegraph with single rate flipRate and uniform π = ½; binary alphabet only).
- erasure (Binary Erasure Channel: 0-absorbing Telegraph with rate eraseRate — only the (1→1) and (1→0) transitions are emitted; binary alphabet only; not valid as a root preset because the equilibrium π = (1, 0) is degenerate).

boss --tkf91-root-dna-jc                   # same as --preset tkf91-root-dna-jc
boss --tkf91-branch-prot-f81               # TKF91 indel structure + F81 protein substitution
boss --tkf92-branch-dna-hky85              # TKF92 fork triad + HKY85
boss --tkf91-branch-custom-jc 0123         # TKF91 + JC over 4-symbol custom alphabet
boss --iid-branch-binary-bsc               # zero-indel-rate BSC: input/output binary 1:1
boss --iid-branch-binary-telegraph         # iid + asymmetric 2-state CTMC on {0, 1}
boss --iid-branch-binary-erasure           # iid + 0-absorbing erasure channel
boss --iid-root-binary-bsc                 # geometric binary emitter (free pExtend) + BSC π
boss --evolmoves-root-prot-f81             # plain ν-geometric protein singlet (no zero-inflation)
boss --evolmoves-branch-prot-f81           # 5-state regularised conditional pair HMM (factors above singlet)

The closed-form formulas for K80 and HKY85 transition probabilities are encoded directly in the resulting WFST's parameter definitions; no numerical eigendecomposition is required at inference time. The 2×2 closed-form for Telegraph / BSC / Erasure is similarly inlined (P_ij(t) = π_j + (δ_ij − π_j) exp(−λt) with λ = rate01 + rate10 for Telegraph, λ = 2flipRate for BSC, and the absorbing form for Erasure).

Genetic Code and Translation

Preset	Description
`translate`	Standard genetic code: DNA codons to amino acids (64 codon mappings)
`prot2dna`	Reverse translation: protein to DNA via composition with `translate` inverse
`simple_introns`	Intron insertion transducer with GT-AG splice signals
`add-intron-placeholders`	Marks intron positions in aligned sequences with placeholder labels
`pint`	Protein identity transducer with optional 3-symbol intron emission

DNA Storage Coding

Preset	Description
`bintern`	Binary to ternary: 5 bits → 2 ternary digits (rate 5/4 bits per trit)
`terndna`	Ternary to non-repeating DNA: each trit selects from 3 bases that differ from the previous one
`nontern`	Composition of `bintern` and `terndna`: bit blocks directly to non-repeating ternary-DNA tokens
`bitcod`	Trivial binary-to-ternary padding: bit `b` → `b12` (rate 1/3)
`bitbase`	Binary to DNA directly: 1 bit → 1 base, selecting from 3 alternatives (rate 1 bit/base)
`bytern`	Byte-oriented binary to ternary: 8 bits → 3 pairs of ternary digits
`AfeI`	Like `terndna` but avoids the AfeI restriction enzyme recognition site AGCGCT

The bintern → terndna pipeline implements the DNA storage code described by Goldman et al. (2013). See the DNA Storage tutorial for details.

Error-Correcting Codes

Preset	Description
`hamming31`	(3,1) repetition code: each input bit is repeated 3 times
`hamming74`	(7,4) Hamming code: 4 input bits → 7-bit codeword with 3 parity bits

These generate error-correcting codewords as transducers. They can be composed with channel noise models (e.g. a bit-flip transducer) and decoded using beam search.

Alphabet Conversion

Preset	Description
`compdna`	DNA complement (A↔T, C↔G) with IUPAC ambiguity code support
`comprna`	RNA complement (A↔U, C↔G) with IUPAC ambiguity code support
`dna2rna`	DNA to RNA: T → U
`rna2dna`	RNA to DNA: U → T
`tolower`	Converts all ASCII characters to lowercase
`toupper`	Converts all ASCII characters to uppercase

Alphabet Expansion

Preset	Description
`iupacdna`	Expands IUPAC DNA ambiguity codes (e.g. R → A or G, N → any base)
`iupacaa`	Expands IUPAC protein codes (X → any amino acid, B → D or N, etc.)

These are useful when input sequences contain ambiguity codes that need to be resolved before further processing.

Helper Machines

Preset	Description
`null`	Empty machine with a single state and no transitions
`flankbase`	Generator: emits geometric-length runs of `base` symbols
`geom_iid_binary`	Generator: emits geometric-length runs of `0`/`1` with parameter `p`
`base2acgt`	Maps abstract `base` tokens to concrete ACGT nucleotides with fitted probabilities

These are building blocks used internally or in composed pipelines. flankbase is used with --flank-output-wild to add flanking regions around profile HMM matches. base2acgt resolves the abstract base symbol used by some machines into concrete nucleotides.