docs: restructure documentation for kmer indexing and phylogeny theory

Reorganize the documentation structure to better separate kmer indexing logic from phylogenetic analysis methods. This involves moving several existing pages into new directories under `theory/kmer_indexing` and `theory/phylogeny`, updating navigation links across the site, and adding new content for VCF pseudo-alignment and specific phylogenetic models.

- Move `doc/index.html` to `doc/theory/kmer_indexing/minimizer_selection/index.html` to document minimizer selection logic.
- Move `doc/installation/index.html` to `doc/theory/phylogeny/kmer_based/kmer_set_distances/index.html` for whole k-mer set distance documentation.
- Move `doc/usage/dump/index.html` to `doc/theory/kmer_indexing/superkmers/index.html` to cover canonical super-kmers.
- Move `doc/usage/query/index.html` to `doc/theory/kmer_indexing/entropy_filter/index.html` for low-complexity kmer filtering details.
- Move `doc/theory/encoding/index.html` to `doc/theory/kmer_indexing/encoding/index.html` for DNA and kmer encoding specifics.
- Move `doc/theory/indexing_architecture/index.html` to `doc/theory/kmer_indexing/indexing_architecture/index.html` for partitioning and routing architecture.
- Move `doc/usage/query/index.html` (duplicate move noted in facts, likely referring to the query command usage or similar) to `doc/theory/phylogeny/snp_based/sankoff_model/index.html` for the 16-state Sankoff model.
- Move `doc/theory/minimizer_selection/index.html` to `doc/theory/phylogeny/snp_based/central_snp_model/index.html` for central-position SNP models and substitution corrections.
- Move `doc/theory/indexing_architecture/index.html` (duplicate move noted) to `doc/theory/phylogeny/snp_based/gamma_rate_heterogeneity/index.html` for gamma rate heterogeneity and automatic alpha estimation.
- Move `doc/theory/entropy_filter/index.html` to `doc/theory/phylogeny/snp_based/sampling_design/index.html` for entropy-biased sampling design.
- Move `doc/formats/index_layout/index.html` to `doc/formats/vcf/index.html` to document VCF pseudo-alignment output and structure.
- Add `doc/molecular-ecology-modified.csl` with a new XML style definition for Molecular Ecology Modified citations.
- Update `UserDocMD/formats/vcf.md` to clarify that `--vcf` implies `--pseudo-alignment`, requires `--n-sites`, and generates files alongside `--fasta`.
- Add three new BibTeX entries in `UserDocMD/references.bib` for Karlin (1997, 1995) and Bennett & Moran (2013).
- Update `UserDocMD/theory/kmer_indexing/kmers.md` to use binomial distribution for probability calculations and define k-mer sharing deviation.
- Clarify in `UserDocMD/theory/phylogeny/kmer_based/kmer_set_distances.md` that counts are used instead of presence/absence for $L^1$ distance.
- Update `UserDocMD/theory/phylogeny/snp_based/gamma_rate_heterogeneity.md` to attribute method-of-moments $\alpha$ estimation to obikmer, not Jin & Nei (1990).
- Update `UserDocMD/theory/phylogeny/snp_based/sampling_design.md` to redirect entropy sampling references to the correct phylo section.
- Add new options `--cpu-max`, `--output`, `--pair-balance`, `--sibling-stats`, `--family-overlap`, and `--shannon` to `UserDocMD/usage/phylo.md`.
- Mark SNP-based distance saving and session reuse as unavailable in `src/obikmer/src/cmd/phylo/args/distance.rs`.
This commit is contained in:
Eric Coissac committed 2026-11-19 17:47:59 +01:00
1 parent d78a6b4501
commit 33d7a59dd9
43 files changed
+25375 -1117

No files matched your search

@@ -9,16 +9,16 @@
<link rel="prev" href="../kmers_and_superkmers/">
<link rel="prev" href="../../../installation/">
<link rel="next" href="../entropy_filter/">
<link rel="next" href="../kmers/">
<link rel="icon" href="../../assets/images/favicon.png">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
@@ -27,7 +27,7 @@
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/main.484c7ddc.min.css">
@@ -46,7 +46,7 @@
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
@@ -80,7 +80,7 @@
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -138,7 +138,7 @@
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -156,7 +156,7 @@
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<a href="../../.." class="md-nav__link">
@@ -183,7 +183,7 @@
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<a href="../../../installation/" class="md-nav__link">
@@ -256,17 +256,30 @@
<li class="md-nav__item">
<a href="../kmers_and_superkmers/" class="md-nav__link">
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" checked>
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Kmers and super-kmers
Kmer indexing
@@ -274,11 +287,19 @@
</a>
</li>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
Kmer indexing
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -395,14 +416,14 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<a href="../kmers/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
Kmers
@@ -450,6 +471,34 @@
<li class="md-nav__item">
<a href="../superkmers/" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../indexing_architecture/" class="md-nav__link">
@@ -472,6 +521,347 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" >
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Phylogeny
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Phylogeny
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_1" >
<label class="md-nav__link" for="__nav_3_2_1" id="__nav_3_2_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_1">
<span class="md-nav__icon md-icon"></span>
Kmer-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/kmer_based/kmer_set_distances/" class="md-nav__link">
<span class="md-ellipsis">
Whole k-mer set distances
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" >
<label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0">
<span class="md-ellipsis">
SNP-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_2">
<span class="md-nav__icon md-icon"></span>
SNP-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/central_snp_model/" class="md-nav__link">
<span class="md-ellipsis">
Central-position SNP model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/gamma_rate_heterogeneity/" class="md-nav__link">
<span class="md-ellipsis">
Gamma rate heterogeneity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sankoff_model/" class="md-nav__link">
<span class="md-ellipsis">
Sankoff model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sampling_design/" class="md-nav__link">
<span class="md-ellipsis">
Sampling design
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
@@ -533,7 +923,7 @@
<li class="md-nav__item">
<a href="../../usage/superkmer/" class="md-nav__link">
<a href="../../../usage/superkmer/" class="md-nav__link">
@@ -561,7 +951,7 @@
<li class="md-nav__item">
<a href="../../usage/index_command/" class="md-nav__link">
<a href="../../../usage/index_command/" class="md-nav__link">
@@ -589,7 +979,7 @@
<li class="md-nav__item">
<a href="../../usage/merge/" class="md-nav__link">
<a href="../../../usage/merge/" class="md-nav__link">
@@ -617,7 +1007,7 @@
<li class="md-nav__item">
<a href="../../usage/filter/" class="md-nav__link">
<a href="../../../usage/filter/" class="md-nav__link">
@@ -645,7 +1035,7 @@
<li class="md-nav__item">
<a href="../../usage/select/" class="md-nav__link">
<a href="../../../usage/select/" class="md-nav__link">
@@ -673,7 +1063,7 @@
<li class="md-nav__item">
<a href="../../usage/query/" class="md-nav__link">
<a href="../../../usage/query/" class="md-nav__link">
@@ -701,7 +1091,7 @@
<li class="md-nav__item">
<a href="../../usage/dump/" class="md-nav__link">
<a href="../../../usage/dump/" class="md-nav__link">
@@ -729,7 +1119,7 @@
<li class="md-nav__item">
<a href="../../usage/annotate/" class="md-nav__link">
<a href="../../../usage/annotate/" class="md-nav__link">
@@ -757,7 +1147,7 @@
<li class="md-nav__item">
<a href="../../usage/phylo/" class="md-nav__link">
<a href="../../../usage/phylo/" class="md-nav__link">
@@ -785,7 +1175,7 @@
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
<a href="../../../usage/unitig/" class="md-nav__link">
@@ -813,7 +1203,7 @@
<li class="md-nav__item">
<a href="../../usage/estimate/" class="md-nav__link">
<a href="../../../usage/estimate/" class="md-nav__link">
@@ -841,7 +1231,7 @@
<li class="md-nav__item">
<a href="../../usage/convert/" class="md-nav__link">
<a href="../../../usage/convert/" class="md-nav__link">
@@ -869,7 +1259,7 @@
<li class="md-nav__item">
<a href="../../usage/utils/" class="md-nav__link">
<a href="../../../usage/utils/" class="md-nav__link">
@@ -897,7 +1287,7 @@
<li class="md-nav__item">
<a href="../../usage/pack/" class="md-nav__link">
<a href="../../../usage/pack/" class="md-nav__link">
@@ -925,7 +1315,7 @@
<li class="md-nav__item">
<a href="../../usage/predicates/" class="md-nav__link">
<a href="../../../usage/predicates/" class="md-nav__link">
@@ -1007,7 +1397,7 @@
<li class="md-nav__item">
<a href="../../formats/index_layout/" class="md-nav__link">
<a href="../../../formats/index_layout/" class="md-nav__link">
@@ -1028,6 +1418,34 @@
<li class="md-nav__item">
<a href="../../../formats/vcf/" class="md-nav__link">
<span class="md-ellipsis">
VCF pseudo-alignment
</span>
</a>
</li>
</ul>
</nav>
@@ -1042,7 +1460,7 @@
<li class="md-nav__item">
<a href="../../architecture/" class="md-nav__link">
<a href="../../../architecture/" class="md-nav__link">
@@ -1172,9 +1590,9 @@
<p>A kmer of length <span class="arithmatex">\(k\)</span> (<span class="arithmatex">\(k \le 31\)</span>) fits in a single 64-bit word. The first nucleotide occupies the two most significant bits, each following nucleotide occupies the next two bits, and unused low-order bits are zero. Extracting nucleotide i (0-indexed from the 5′ end) is a shift-and-mask operation.</p>
<p>Reverse complement is computed by bit manipulation directly on the packed word, without any lookup table: complement every base, reverse the byte order, then reverse the order of 2-bit groups within each byte in two more passes, and finally realign the result to the most-significant bits.</p>
<h2 id="canonical-form">Canonical form</h2>
<p>The canonical form of a kmer is the lexicographic minimum of the kmer and its reverse complement:</p>
<div class="arithmatex">\[\text{canonical}(kmer) = \min\big(kmer,\ \text{revcomp}(kmer)\big)\]</div>
<p>Using the canonical form halves the kmer space and makes counting strand-independent: a kmer and its reverse complement are always treated as the same entity, regardless of which DNA strand was sequenced.</p>
<p>The canonical form of a packed 2-bit sequence is the lexicographic minimum of the sequence and its reverse complement:</p>
<div class="arithmatex">\[\text{canonical}(x) = \min\big(x,\ \text{revcomp}(x)\big)\]</div>
<p>This is a single operation on the packed representation, so it applies identically regardless of what <code>x</code> represents — a kmer (see <a href="../kmers/">Kmers</a>), an m-mer (see <a href="../minimizer_selection/">Minimizer selection</a>), or a super-kmer (see <a href="../superkmers/">Super-kmers</a>). Using the canonical form halves the relevant space and makes counting/selection strand-independent: a sequence and its reverse complement are always treated as the same entity, regardless of which DNA strand was sequenced.</p>
@@ -1224,10 +1642,10 @@
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": [], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
@@ -9,16 +9,16 @@
<link rel="prev" href="../encoding/">
<link rel="prev" href="../indexing_architecture/">
<link rel="next" href="../minimizer_selection/">
<link rel="next" href="../../phylogeny/kmer_based/kmer_set_distances/">
<link rel="icon" href="../../assets/images/favicon.png">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
@@ -27,7 +27,7 @@
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/main.484c7ddc.min.css">
@@ -46,7 +46,7 @@
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
@@ -80,7 +80,7 @@
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -138,7 +138,7 @@
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -156,7 +156,7 @@
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<a href="../../.." class="md-nav__link">
@@ -183,7 +183,7 @@
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<a href="../../../installation/" class="md-nav__link">
@@ -256,17 +256,66 @@
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" checked>
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer indexing
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
Kmer indexing
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../kmers_and_superkmers/" class="md-nav__link">
<a href="../encoding/" class="md-nav__link">
<span class="md-ellipsis">
Kmers and super-kmers
DNA encoding
@@ -287,14 +336,98 @@
<li class="md-nav__item">
<a href="../encoding/" class="md-nav__link">
<a href="../kmers/" class="md-nav__link">
<span class="md-ellipsis">
DNA encoding
Kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../minimizer_selection/" class="md-nav__link">
<span class="md-ellipsis">
Minimizer selection
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../superkmers/" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../indexing_architecture/" class="md-nav__link">
<span class="md-ellipsis">
Partitioning and indexing architecture
@@ -438,6 +571,108 @@
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" >
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Phylogeny
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Phylogeny
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_1" >
<label class="md-nav__link" for="__nav_3_2_1" id="__nav_3_2_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_1">
<span class="md-nav__icon md-icon"></span>
Kmer-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -445,14 +680,97 @@
<li class="md-nav__item">
<a href="../minimizer_selection/" class="md-nav__link">
<a href="../../phylogeny/kmer_based/kmer_set_distances/" class="md-nav__link">
<span class="md-ellipsis">
Minimizer selection
Whole k-mer set distances
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" >
<label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0">
<span class="md-ellipsis">
SNP-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_2">
<span class="md-nav__icon md-icon"></span>
SNP-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/central_snp_model/" class="md-nav__link">
<span class="md-ellipsis">
Central-position SNP model
@@ -473,14 +791,14 @@
<li class="md-nav__item">
<a href="../indexing_architecture/" class="md-nav__link">
<a href="../../phylogeny/snp_based/gamma_rate_heterogeneity/" class="md-nav__link">
<span class="md-ellipsis">
Partitioning and indexing architecture
Gamma rate heterogeneity
@@ -494,6 +812,78 @@
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sankoff_model/" class="md-nav__link">
<span class="md-ellipsis">
Sankoff model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sampling_design/" class="md-nav__link">
<span class="md-ellipsis">
Sampling design
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
@@ -555,7 +945,7 @@
<li class="md-nav__item">
<a href="../../usage/superkmer/" class="md-nav__link">
<a href="../../../usage/superkmer/" class="md-nav__link">
@@ -583,7 +973,7 @@
<li class="md-nav__item">
<a href="../../usage/index_command/" class="md-nav__link">
<a href="../../../usage/index_command/" class="md-nav__link">
@@ -611,7 +1001,7 @@
<li class="md-nav__item">
<a href="../../usage/merge/" class="md-nav__link">
<a href="../../../usage/merge/" class="md-nav__link">
@@ -639,7 +1029,7 @@
<li class="md-nav__item">
<a href="../../usage/filter/" class="md-nav__link">
<a href="../../../usage/filter/" class="md-nav__link">
@@ -667,7 +1057,7 @@
<li class="md-nav__item">
<a href="../../usage/select/" class="md-nav__link">
<a href="../../../usage/select/" class="md-nav__link">
@@ -695,7 +1085,7 @@
<li class="md-nav__item">
<a href="../../usage/query/" class="md-nav__link">
<a href="../../../usage/query/" class="md-nav__link">
@@ -723,7 +1113,7 @@
<li class="md-nav__item">
<a href="../../usage/dump/" class="md-nav__link">
<a href="../../../usage/dump/" class="md-nav__link">
@@ -751,7 +1141,7 @@
<li class="md-nav__item">
<a href="../../usage/annotate/" class="md-nav__link">
<a href="../../../usage/annotate/" class="md-nav__link">
@@ -779,7 +1169,7 @@
<li class="md-nav__item">
<a href="../../usage/phylo/" class="md-nav__link">
<a href="../../../usage/phylo/" class="md-nav__link">
@@ -807,7 +1197,7 @@
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
<a href="../../../usage/unitig/" class="md-nav__link">
@@ -835,7 +1225,7 @@
<li class="md-nav__item">
<a href="../../usage/estimate/" class="md-nav__link">
<a href="../../../usage/estimate/" class="md-nav__link">
@@ -863,7 +1253,7 @@
<li class="md-nav__item">
<a href="../../usage/convert/" class="md-nav__link">
<a href="../../../usage/convert/" class="md-nav__link">
@@ -891,7 +1281,7 @@
<li class="md-nav__item">
<a href="../../usage/utils/" class="md-nav__link">
<a href="../../../usage/utils/" class="md-nav__link">
@@ -919,7 +1309,7 @@
<li class="md-nav__item">
<a href="../../usage/pack/" class="md-nav__link">
<a href="../../../usage/pack/" class="md-nav__link">
@@ -947,7 +1337,7 @@
<li class="md-nav__item">
<a href="../../usage/predicates/" class="md-nav__link">
<a href="../../../usage/predicates/" class="md-nav__link">
@@ -1029,7 +1419,7 @@
<li class="md-nav__item">
<a href="../../formats/index_layout/" class="md-nav__link">
<a href="../../../formats/index_layout/" class="md-nav__link">
@@ -1050,6 +1440,34 @@
<li class="md-nav__item">
<a href="../../../formats/vcf/" class="md-nav__link">
<span class="md-ellipsis">
VCF pseudo-alignment
</span>
</a>
</li>
</ul>
</nav>
@@ -1064,7 +1482,7 @@
<li class="md-nav__item">
<a href="../../architecture/" class="md-nav__link">
<a href="../../../architecture/" class="md-nav__link">
@@ -1252,10 +1670,10 @@
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": [], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
@@ -9,16 +9,16 @@
<link rel="prev" href="../minimizer_selection/">
<link rel="prev" href="../superkmers/">
<link rel="next" href="../../usage/superkmer/">
<link rel="next" href="../entropy_filter/">
<link rel="icon" href="../../assets/images/favicon.png">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
@@ -27,7 +27,7 @@
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/main.484c7ddc.min.css">
@@ -46,7 +46,7 @@
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
@@ -80,7 +80,7 @@
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -138,7 +138,7 @@
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -156,7 +156,7 @@
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<a href="../../.." class="md-nav__link">
@@ -183,7 +183,7 @@
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<a href="../../../installation/" class="md-nav__link">
@@ -256,17 +256,30 @@
<li class="md-nav__item">
<a href="../kmers_and_superkmers/" class="md-nav__link">
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" checked>
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Kmers and super-kmers
Kmer indexing
@@ -274,11 +287,19 @@
</a>
</li>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
Kmer indexing
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -315,14 +336,14 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<a href="../kmers/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
Kmers
@@ -368,6 +389,34 @@
<li class="md-nav__item">
<a href="../superkmers/" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
</li>
@@ -439,17 +488,6 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#why-hashing-is-necessary" class="md-nav__link">
<span class="md-ellipsis">
Why hashing is necessary
</span>
</a>
</li>
<li class="md-nav__item">
@@ -472,6 +510,347 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" >
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Phylogeny
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Phylogeny
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_1" >
<label class="md-nav__link" for="__nav_3_2_1" id="__nav_3_2_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_1">
<span class="md-nav__icon md-icon"></span>
Kmer-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/kmer_based/kmer_set_distances/" class="md-nav__link">
<span class="md-ellipsis">
Whole k-mer set distances
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" >
<label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0">
<span class="md-ellipsis">
SNP-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_2">
<span class="md-nav__icon md-icon"></span>
SNP-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/central_snp_model/" class="md-nav__link">
<span class="md-ellipsis">
Central-position SNP model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/gamma_rate_heterogeneity/" class="md-nav__link">
<span class="md-ellipsis">
Gamma rate heterogeneity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sankoff_model/" class="md-nav__link">
<span class="md-ellipsis">
Sankoff model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sampling_design/" class="md-nav__link">
<span class="md-ellipsis">
Sampling design
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
@@ -533,7 +912,7 @@
<li class="md-nav__item">
<a href="../../usage/superkmer/" class="md-nav__link">
<a href="../../../usage/superkmer/" class="md-nav__link">
@@ -561,7 +940,7 @@
<li class="md-nav__item">
<a href="../../usage/index_command/" class="md-nav__link">
<a href="../../../usage/index_command/" class="md-nav__link">
@@ -589,7 +968,7 @@
<li class="md-nav__item">
<a href="../../usage/merge/" class="md-nav__link">
<a href="../../../usage/merge/" class="md-nav__link">
@@ -617,7 +996,7 @@
<li class="md-nav__item">
<a href="../../usage/filter/" class="md-nav__link">
<a href="../../../usage/filter/" class="md-nav__link">
@@ -645,7 +1024,7 @@
<li class="md-nav__item">
<a href="../../usage/select/" class="md-nav__link">
<a href="../../../usage/select/" class="md-nav__link">
@@ -673,7 +1052,7 @@
<li class="md-nav__item">
<a href="../../usage/query/" class="md-nav__link">
<a href="../../../usage/query/" class="md-nav__link">
@@ -701,7 +1080,7 @@
<li class="md-nav__item">
<a href="../../usage/dump/" class="md-nav__link">
<a href="../../../usage/dump/" class="md-nav__link">
@@ -729,7 +1108,7 @@
<li class="md-nav__item">
<a href="../../usage/annotate/" class="md-nav__link">
<a href="../../../usage/annotate/" class="md-nav__link">
@@ -757,7 +1136,7 @@
<li class="md-nav__item">
<a href="../../usage/phylo/" class="md-nav__link">
<a href="../../../usage/phylo/" class="md-nav__link">
@@ -785,7 +1164,7 @@
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
<a href="../../../usage/unitig/" class="md-nav__link">
@@ -813,7 +1192,7 @@
<li class="md-nav__item">
<a href="../../usage/estimate/" class="md-nav__link">
<a href="../../../usage/estimate/" class="md-nav__link">
@@ -841,7 +1220,7 @@
<li class="md-nav__item">
<a href="../../usage/convert/" class="md-nav__link">
<a href="../../../usage/convert/" class="md-nav__link">
@@ -869,7 +1248,7 @@
<li class="md-nav__item">
<a href="../../usage/utils/" class="md-nav__link">
<a href="../../../usage/utils/" class="md-nav__link">
@@ -897,7 +1276,7 @@
<li class="md-nav__item">
<a href="../../usage/pack/" class="md-nav__link">
<a href="../../../usage/pack/" class="md-nav__link">
@@ -925,7 +1304,7 @@
<li class="md-nav__item">
<a href="../../usage/predicates/" class="md-nav__link">
<a href="../../../usage/predicates/" class="md-nav__link">
@@ -1007,7 +1386,7 @@
<li class="md-nav__item">
<a href="../../formats/index_layout/" class="md-nav__link">
<a href="../../../formats/index_layout/" class="md-nav__link">
@@ -1028,6 +1407,34 @@
<li class="md-nav__item">
<a href="../../../formats/vcf/" class="md-nav__link">
<span class="md-ellipsis">
VCF pseudo-alignment
</span>
</a>
</li>
</ul>
</nav>
@@ -1042,7 +1449,7 @@
<li class="md-nav__item">
<a href="../../architecture/" class="md-nav__link">
<a href="../../../architecture/" class="md-nav__link">
@@ -1097,17 +1504,6 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#why-hashing-is-necessary" class="md-nav__link">
<span class="md-ellipsis">
Why hashing is necessary
</span>
</a>
</li>
<li class="md-nav__item">
@@ -1141,15 +1537,13 @@
<h1 id="partitioning-and-indexing-architecture">Partitioning and indexing architecture</h1>
<p>An index is split into a fixed number of <strong>partitions</strong>, each handling an independent, disjoint slice of the kmer space. Partitioning keeps the working set of each stage small enough to process efficiently and enables parallel construction and querying.</p>
<h2 id="routing">Routing</h2>
<p>The canonical minimizer of a super-kmer (see <a href="../minimizer_selection/">Minimizer selection</a>) is hashed to produce a <span class="arithmatex">\(p\)</span>-bit routing value that selects the destination partition:</p>
<p>The canonical minimizer of a super-kmer (see <a href="../minimizer_selection/">Minimizer selection</a>) is hashed to produce a <span class="arithmatex">\(p\)</span>-bit routing value that selects the destination partition — the low <span class="arithmatex">\(p\)</span> bits of the minimizer's hash:</p>
<div class="highlight"><pre><span></span><code>canonical minimizer → hash(minimizer) → p-bit value → partition index
</code></pre></div>
<p>The routing value is recomputed whenever it is needed (during construction and again at query time) rather than stored — it is not part of the on-disk super-kmer representation.</p>
<p>Within a partition, kmers are indexed as plain values via a minimal perfect hash function (see <a href="../../formats/index_layout/">On-disk storage</a>); the minimizer plays no further role once a super-kmer has reached its partition.</p>
<h2 id="why-hashing-is-necessary">Why hashing is necessary</h2>
<p>A canonical minimizer is an m-mer (<span class="arithmatex">\(m \in \{9, 11, 13, 15\}\)</span>), and its distribution over all possible m-mer values is not uniform — as the lexicographic minimum of a window, small values are systematically over-represented (Golan &amp; Shur 2025; Kille <em>et al.</em> 2023; Pan &amp; Reinert 2024; Zheng <em>et al.</em> 2020, 2021)<sup id="fnref:Zheng2020-ji"><a class="footnote-ref" href="#fn:Zheng2020-ji">1</a></sup> <sup id="fnref:Zheng2021-cc"><a class="footnote-ref" href="#fn:Zheng2021-cc">2</a></sup> <sup id="fnref:Pan2024-hb"><a class="footnote-ref" href="#fn:Pan2024-hb">3</a></sup> <sup id="fnref:Kille2023-px"><a class="footnote-ref" href="#fn:Kille2023-px">4</a></sup> <sup id="fnref:Golan2025-xf"><a class="footnote-ref" href="#fn:Golan2025-xf">5</a></sup>. Routing directly on the raw minimizer value would therefore produce badly unbalanced partitions.</p>
<p>Hashing the minimizer before routing redistributes this skewed distribution uniformly across partitions. This works reliably because the number of partition-index bits <span class="arithmatex">\(p\)</span> is chosen well below the number of bits available in the minimizer (<span class="arithmatex">\(2m\)</span>): even with strong bias in the minimizer distribution, the hash has enough entropy margin to absorb it, provided the number of distinct minimizers actually observed is much larger than the number of partitions.</p>
<div class="arithmatex">\[\text{partition} = H(\text{minimizer}) \bmod 2^p\]</div>
<p>Within a partition, kmers are indexed as plain values via a minimal perfect hash function (see <a href="../../../formats/index_layout/">On-disk storage</a>); the minimizer plays no further role once a super-kmer has reached its partition.</p>
<h2 id="parameter-guidance">Parameter guidance</h2>
<p>Even though <span class="arithmatex">\(H\)</span> already makes minimizer values well-distributed (see <a href="../minimizer_selection/">Minimizer selection</a>), choosing <span class="arithmatex">\(p\)</span> well below the number of bits available in the minimizer (<span class="arithmatex">\(2m\)</span>) leaves a comfortable entropy margin, provided the number of distinct minimizers actually observed is much larger than the number of partitions.</p>
<table>
<thead>
<tr>
@@ -1187,26 +1581,6 @@
</tbody>
</table>
<p>The number of partitions must satisfy <span class="arithmatex">\(p \le 2m\)</span>, and in practice <span class="arithmatex">\(p\)</span> is chosen well below that bound to leave a comfortable entropy margin. For <span class="arithmatex">\(k=31\)</span>, <span class="arithmatex">\(m=13\)</span>, <span class="arithmatex">\(p=10\)</span> (1024 partitions), partition load is well balanced on real genomic data.</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:Zheng2020-ji">
<p>Zheng, H., Kingsford, C. &amp; Marçais, G. (2020). <a href="https://doi.org/10.1093/bioinformatics/btaa472">Improved design and analysis of practical minimizers</a>. <em>Bioinformatics (Oxford, England)</em>, 36, i119--i127.&#160;<a class="footnote-backref" href="#fnref:Zheng2020-ji" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>
<li id="fn:Zheng2021-cc">
<p>Zheng, H., Kingsford, C. &amp; Marçais, G. (2021). <a href="https://doi.org/10.1093/bioinformatics/btab313">Sequence-specific minimizers via polar sets</a>. <em>Bioinformatics (Oxford, England)</em>, 37, i187--i195.&#160;<a class="footnote-backref" href="#fnref:Zheng2021-cc" title="Jump back to footnote 2 in the text">&#8617;</a></p>
</li>
<li id="fn:Pan2024-hb">
<p>Pan, C. &amp; Reinert, K. (2024). <a href="https://doi.org/10.1093/bioinformatics/btae045">A simple refined DNA minimizer operator enables 2-fold faster computation</a>. <em>Bioinformatics (Oxford, England)</em>, 40.&#160;<a class="footnote-backref" href="#fnref:Pan2024-hb" title="Jump back to footnote 3 in the text">&#8617;</a></p>
</li>
<li id="fn:Kille2023-px">
<p>Kille, B., Garrison, E., Treangen, T.J. &amp; Phillippy, A.M. (2023). <a href="https://doi.org/10.1093/bioinformatics/btad512">Minmers are a generalization of minimizers that enable unbiased local jaccard estimation</a>. <em>Bioinformatics (Oxford, England)</em>, 39.&#160;<a class="footnote-backref" href="#fnref:Kille2023-px" title="Jump back to footnote 4 in the text">&#8617;</a></p>
</li>
<li id="fn:Golan2025-xf">
<p>Golan, S. &amp; Shur, A.M. (2025). <a href="https://doi.org/10.1007/978-3-031-82670-2\_25">Expected density of random minimizers</a>. In: <em>Lecture notes in computer science</em>, Lecture notes in computer science. Springer Nature Switzerland, Cham, pp. 347--360.&#160;<a class="footnote-backref" href="#fnref:Golan2025-xf" title="Jump back to footnote 5 in the text">&#8617;</a></p>
</li>
</ol>
</div>
@@ -1256,10 +1630,10 @@
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": [], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -9,25 +9,25 @@
<link rel="prev" href="../../installation/">
<link rel="prev" href="../minimizer_selection/">
<link rel="next" href="../encoding/">
<link rel="next" href="../indexing_architecture/">
<link rel="icon" href="../../assets/images/favicon.png">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>Kmers and super-kmers - obikmer — User Guide</title>
<title>Super-kmers - obikmer — User Guide</title>
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/main.484c7ddc.min.css">
@@ -46,7 +46,7 @@
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
@@ -64,7 +64,7 @@
<div data-md-component="skip">
<a href="#kmers-and-super-kmers" class="md-skip">
<a href="#super-kmers" class="md-skip">
Skip to content
</a>
@@ -80,7 +80,7 @@
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -100,7 +100,7 @@
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Kmers and super-kmers
Super-kmers
</span>
</div>
@@ -138,7 +138,7 @@
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -156,7 +156,7 @@
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<a href="../../.." class="md-nav__link">
@@ -183,7 +183,7 @@
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<a href="../../../installation/" class="md-nav__link">
@@ -260,22 +260,26 @@
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<label class="md-nav__link md-nav__link--active" for="__toc">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" checked>
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Kmers and super-kmers
Kmer indexing
@@ -283,88 +287,19 @@
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
<span class="md-ellipsis">
Kmers and super-kmers
Kmer indexing
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#kmers" class="md-nav__link">
<span class="md-ellipsis">
Kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#super-kmers" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
<nav class="md-nav" aria-label="Super-kmers">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#canonical-super-kmers" class="md-nav__link">
<span class="md-ellipsis">
Canonical super-kmers
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -401,14 +336,14 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<a href="../kmers/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
Kmers
@@ -454,6 +389,92 @@
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Super-kmers
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#canonical-super-kmers" class="md-nav__link">
<span class="md-ellipsis">
Canonical super-kmers
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -478,6 +499,347 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<span class="md-ellipsis">
Low-complexity kmer filter
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" >
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Phylogeny
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Phylogeny
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_1" >
<label class="md-nav__link" for="__nav_3_2_1" id="__nav_3_2_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_1">
<span class="md-nav__icon md-icon"></span>
Kmer-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/kmer_based/kmer_set_distances/" class="md-nav__link">
<span class="md-ellipsis">
Whole k-mer set distances
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" >
<label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0">
<span class="md-ellipsis">
SNP-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_2">
<span class="md-nav__icon md-icon"></span>
SNP-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/central_snp_model/" class="md-nav__link">
<span class="md-ellipsis">
Central-position SNP model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/gamma_rate_heterogeneity/" class="md-nav__link">
<span class="md-ellipsis">
Gamma rate heterogeneity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sankoff_model/" class="md-nav__link">
<span class="md-ellipsis">
Sankoff model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../phylogeny/snp_based/sampling_design/" class="md-nav__link">
<span class="md-ellipsis">
Sampling design
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
@@ -539,7 +901,7 @@
<li class="md-nav__item">
<a href="../../usage/superkmer/" class="md-nav__link">
<a href="../../../usage/superkmer/" class="md-nav__link">
@@ -567,7 +929,7 @@
<li class="md-nav__item">
<a href="../../usage/index_command/" class="md-nav__link">
<a href="../../../usage/index_command/" class="md-nav__link">
@@ -595,7 +957,7 @@
<li class="md-nav__item">
<a href="../../usage/merge/" class="md-nav__link">
<a href="../../../usage/merge/" class="md-nav__link">
@@ -623,7 +985,7 @@
<li class="md-nav__item">
<a href="../../usage/filter/" class="md-nav__link">
<a href="../../../usage/filter/" class="md-nav__link">
@@ -651,7 +1013,7 @@
<li class="md-nav__item">
<a href="../../usage/select/" class="md-nav__link">
<a href="../../../usage/select/" class="md-nav__link">
@@ -679,7 +1041,7 @@
<li class="md-nav__item">
<a href="../../usage/query/" class="md-nav__link">
<a href="../../../usage/query/" class="md-nav__link">
@@ -707,7 +1069,7 @@
<li class="md-nav__item">
<a href="../../usage/dump/" class="md-nav__link">
<a href="../../../usage/dump/" class="md-nav__link">
@@ -735,7 +1097,7 @@
<li class="md-nav__item">
<a href="../../usage/annotate/" class="md-nav__link">
<a href="../../../usage/annotate/" class="md-nav__link">
@@ -763,7 +1125,7 @@
<li class="md-nav__item">
<a href="../../usage/phylo/" class="md-nav__link">
<a href="../../../usage/phylo/" class="md-nav__link">
@@ -791,7 +1153,7 @@
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
<a href="../../../usage/unitig/" class="md-nav__link">
@@ -819,7 +1181,7 @@
<li class="md-nav__item">
<a href="../../usage/estimate/" class="md-nav__link">
<a href="../../../usage/estimate/" class="md-nav__link">
@@ -847,7 +1209,7 @@
<li class="md-nav__item">
<a href="../../usage/convert/" class="md-nav__link">
<a href="../../../usage/convert/" class="md-nav__link">
@@ -875,7 +1237,7 @@
<li class="md-nav__item">
<a href="../../usage/utils/" class="md-nav__link">
<a href="../../../usage/utils/" class="md-nav__link">
@@ -903,7 +1265,7 @@
<li class="md-nav__item">
<a href="../../usage/pack/" class="md-nav__link">
<a href="../../../usage/pack/" class="md-nav__link">
@@ -931,7 +1293,7 @@
<li class="md-nav__item">
<a href="../../usage/predicates/" class="md-nav__link">
<a href="../../../usage/predicates/" class="md-nav__link">
@@ -1013,7 +1375,7 @@
<li class="md-nav__item">
<a href="../../formats/index_layout/" class="md-nav__link">
<a href="../../../formats/index_layout/" class="md-nav__link">
@@ -1034,6 +1396,34 @@
<li class="md-nav__item">
<a href="../../../formats/vcf/" class="md-nav__link">
<span class="md-ellipsis">
VCF pseudo-alignment
</span>
</a>
</li>
</ul>
</nav>
@@ -1048,7 +1438,7 @@
<li class="md-nav__item">
<a href="../../architecture/" class="md-nav__link">
<a href="../../../architecture/" class="md-nav__link">
@@ -1095,29 +1485,6 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#kmers" class="md-nav__link">
<span class="md-ellipsis">
Kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#super-kmers" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
<nav class="md-nav" aria-label="Super-kmers">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#canonical-super-kmers" class="md-nav__link">
<span class="md-ellipsis">
@@ -1126,11 +1493,6 @@
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
@@ -1150,29 +1512,22 @@
<h1 id="kmers-and-super-kmers">Kmers and super-kmers</h1>
<h2 id="kmers">Kmers</h2>
<p>A <strong>kmer</strong> is a DNA subsequence of fixed length <span class="arithmatex">\(k\)</span>. Two constraints apply to <span class="arithmatex">\(k\)</span>, both enforced when a command starts (an invalid value exits immediately with an error):</p>
<ul>
<li><span class="arithmatex">\(k \in [11, 31]\)</span>: long enough to be specific, short enough to fit in a single 64-bit word at 2 bits/base (<span class="arithmatex">\(k \le 32\)</span> is the hard limit; <span class="arithmatex">\(k &lt; 11\)</span> gives insufficient specificity).</li>
<li><span class="arithmatex">\(k\)</span> <strong>is odd</strong>: an odd-length sequence can never equal its own reverse complement, so the two orientations of any kmer are always distinct. This is required for the canonical form (see <a href="../encoding/">DNA encoding</a>) to be well defined.</li>
</ul>
<h2 id="super-kmers">Super-kmers</h2>
<h1 id="super-kmers">Super-kmers</h1>
<p>A <strong>super-kmer</strong> is a maximal run of consecutive, overlapping kmers from a read that share the same canonical minimizer (see <a href="../minimizer_selection/">Minimizer selection</a>). Each kmer in the run overlaps the next by <span class="arithmatex">\(k-1\)</span> nucleotides. A super-kmer is capped at 256 nucleotides; a longer run is split at that boundary.</p>
<p>For a random minimizer of length <span class="arithmatex">\(m\)</span> over kmers of length <span class="arithmatex">\(k\)</span>, the expected length of a super-kmer is approximately (Golan &amp; Shur 2025; Zheng <em>et al.</em> 2020)<sup id="fnref:Zheng2020-ji"><a class="footnote-ref" href="#fn:Zheng2020-ji">1</a></sup> <sup id="fnref:Golan2025-xf"><a class="footnote-ref" href="#fn:Golan2025-xf">2</a></sup>:</p>
<p>For a random minimizer of length <span class="arithmatex">\(m\)</span> over kmers of length <span class="arithmatex">\(k\)</span>, the expected length of a super-kmer is approximately (Zheng <em>et al.</em> 2020; Golan &amp; Shur 2025)<sup id="fnref:Zheng2020-ji"><a class="footnote-ref" href="#fn:Zheng2020-ji">1</a></sup> <sup id="fnref:Golan2025-xf"><a class="footnote-ref" href="#fn:Golan2025-xf">2</a></sup>:</p>
<div class="arithmatex">\[L_{\text{nt}} \approx \frac{k-m+2}{2} + k - 1\]</div>
<p>For <span class="arithmatex">\(k=31\)</span>, <span class="arithmatex">\(m=13\)</span> this is about 40 nucleotides; in practice super-kmers rarely exceed a few dozen nucleotides.</p>
<h3 id="canonical-super-kmers">Canonical super-kmers</h3>
<p>A <strong>canonical super-kmer</strong> is the lexicographic minimum of a super-kmer and its reverse complement. When a read and its reverse complement are both encountered, they produce super-kmers that are reverse complements of each other; both reduce to the same canonical super-kmer, so a genomic region is represented once regardless of which strand was read.</p>
<h2 id="canonical-super-kmers">Canonical super-kmers</h2>
<p>A <strong>canonical super-kmer</strong> is the canonical form of a super-kmer (see <a href="../encoding/">DNA encoding</a>): the lexicographic minimum of the super-kmer and its reverse complement. When a read and its reverse complement are both encountered, they produce super-kmers that are reverse complements of each other; both reduce to the same canonical super-kmer, so a genomic region is represented once regardless of which strand was read.</p>
<p>Super-kmers are the unit of work used throughout construction and querying: sequences are decomposed into super-kmers first, and every downstream step (partition routing, deduplication, counting) operates on them rather than on individual kmers.</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:Zheng2020-ji">
<p>Zheng, H., Kingsford, C. &amp; Marçais, G. (2020). <a href="https://doi.org/10.1093/bioinformatics/btaa472">Improved design and analysis of practical minimizers</a>. <em>Bioinformatics (Oxford, England)</em>, 36, i119--i127.&#160;<a class="footnote-backref" href="#fnref:Zheng2020-ji" title="Jump back to footnote 1 in the text">&#8617;</a></p>
<p>Zheng H, Kingsford C, Marçais G (2020) <a href="https://doi.org/10.1093/bioinformatics/btaa472">Improved design and analysis of practical minimizers</a>. <em>Bioinformatics (Oxford, England)</em>, <strong>36</strong>, i119--i127.&#160;<a class="footnote-backref" href="#fnref:Zheng2020-ji" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>
<li id="fn:Golan2025-xf">
<p>Golan, S. &amp; Shur, A.M. (2025). <a href="https://doi.org/10.1007/978-3-031-82670-2\_25">Expected density of random minimizers</a>. In: <em>Lecture notes in computer science</em>, Lecture notes in computer science. Springer Nature Switzerland, Cham, pp. 347--360.&#160;<a class="footnote-backref" href="#fnref:Golan2025-xf" title="Jump back to footnote 2 in the text">&#8617;</a></p>
<p>Golan S, Shur AM (2025) <a href="https://doi.org/10.1007/978-3-031-82670-2\_25">Expected density of random minimizers</a>. In: <em>Lecture notes in computer science</em> Lecture notes in computer science., pp. 347--360. Springer Nature Switzerland, Cham.&#160;<a class="footnote-backref" href="#fnref:Golan2025-xf" title="Jump back to footnote 2 in the text">&#8617;</a></p>
</li>
</ol>
</div>
@@ -1225,10 +1580,10 @@
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": [], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -9,25 +9,25 @@
<link rel="prev" href="../entropy_filter/">
<link rel="prev" href="../gamma_rate_heterogeneity/">
<link rel="next" href="../indexing_architecture/">
<link rel="next" href="../sampling_design/">
<link rel="icon" href="../../assets/images/favicon.png">
<link rel="icon" href="../../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>Minimizer selection - obikmer — User Guide</title>
<title>Sankoff model - obikmer — User Guide</title>
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../../assets/stylesheets/main.484c7ddc.min.css">
@@ -46,7 +46,7 @@
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<script>__md_scope=new URL("../../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
@@ -64,7 +64,7 @@
<div data-md-component="skip">
<a href="#minimizer-selection" class="md-skip">
<a href="#the-16-state-sankoff-model" class="md-skip">
Skip to content
</a>
@@ -80,7 +80,7 @@
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../../.." title="obikmer — User Guide" class="md-header__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -100,7 +100,7 @@
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Minimizer selection
Sankoff model
</span>
</div>
@@ -138,7 +138,7 @@
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<a href="../../../.." title="obikmer — User Guide" class="md-nav__button md-logo" aria-label="obikmer — User Guide" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
@@ -156,7 +156,7 @@
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<a href="../../../.." class="md-nav__link">
@@ -183,7 +183,7 @@
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<a href="../../../../installation/" class="md-nav__link">
@@ -258,15 +258,26 @@
<li class="md-nav__item">
<a href="../kmers_and_superkmers/" class="md-nav__link">
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" >
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Kmers and super-kmers
Kmer indexing
@@ -274,11 +285,19 @@
</a>
</li>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
Kmer indexing
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -287,7 +306,7 @@
<li class="md-nav__item">
<a href="../encoding/" class="md-nav__link">
<a href="../../../kmer_indexing/encoding/" class="md-nav__link">
@@ -315,7 +334,119 @@
<li class="md-nav__item">
<a href="../entropy_filter/" class="md-nav__link">
<a href="../../../kmer_indexing/kmers/" class="md-nav__link">
<span class="md-ellipsis">
Kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../kmer_indexing/minimizer_selection/" class="md-nav__link">
<span class="md-ellipsis">
Minimizer selection
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../kmer_indexing/superkmers/" class="md-nav__link">
<span class="md-ellipsis">
Super-kmers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../kmer_indexing/indexing_architecture/" class="md-nav__link">
<span class="md-ellipsis">
Partitioning and indexing architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../kmer_indexing/entropy_filter/" class="md-nav__link">
@@ -336,6 +467,251 @@
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" checked>
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Phylogeny
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Phylogeny
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_1" >
<label class="md-nav__link" for="__nav_3_2_1" id="__nav_3_2_1_label" tabindex="0">
<span class="md-ellipsis">
Kmer-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2_1">
<span class="md-nav__icon md-icon"></span>
Kmer-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../kmer_based/kmer_set_distances/" class="md-nav__link">
<span class="md-ellipsis">
Whole k-mer set distances
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" checked>
<label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0">
<span class="md-ellipsis">
SNP-based
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_2_2">
<span class="md-nav__icon md-icon"></span>
SNP-based
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../central_snp_model/" class="md-nav__link">
<span class="md-ellipsis">
Central-position SNP model
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../gamma_rate_heterogeneity/" class="md-nav__link">
<span class="md-ellipsis">
Gamma rate heterogeneity
</span>
</a>
</li>
@@ -359,7 +735,7 @@
<span class="md-ellipsis">
Minimizer selection
Sankoff model
@@ -377,7 +753,7 @@
<span class="md-ellipsis">
Minimizer selection
Sankoff model
@@ -403,49 +779,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#definition" class="md-nav__link">
<a href="#combining-into-a-1616-cost-matrix" class="md-nav__link">
<span class="md-ellipsis">
Definition
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#hash-based-random-minimizer" class="md-nav__link">
<span class="md-ellipsis">
Hash-based ("random") minimizer
</span>
</a>
<nav class="md-nav" aria-label="Hash-based (&#34;random&#34;) minimizer">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#hash-function" class="md-nav__link">
<span class="md-ellipsis">
Hash function
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#partition-routing-is-independent-of-minimizer-selection" class="md-nav__link">
<span class="md-ellipsis">
Partition routing is independent of minimizer selection
Combining into a 16×16 cost matrix
</span>
</a>
@@ -468,14 +805,14 @@
<li class="md-nav__item">
<a href="../indexing_architecture/" class="md-nav__link">
<a href="../sampling_design/" class="md-nav__link">
<span class="md-ellipsis">
Partitioning and indexing architecture
Sampling design
@@ -495,6 +832,22 @@
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
@@ -550,7 +903,7 @@
<li class="md-nav__item">
<a href="../../usage/superkmer/" class="md-nav__link">
<a href="../../../../usage/superkmer/" class="md-nav__link">
@@ -578,7 +931,7 @@
<li class="md-nav__item">
<a href="../../usage/index_command/" class="md-nav__link">
<a href="../../../../usage/index_command/" class="md-nav__link">
@@ -606,7 +959,7 @@
<li class="md-nav__item">
<a href="../../usage/merge/" class="md-nav__link">
<a href="../../../../usage/merge/" class="md-nav__link">
@@ -634,7 +987,7 @@
<li class="md-nav__item">
<a href="../../usage/filter/" class="md-nav__link">
<a href="../../../../usage/filter/" class="md-nav__link">
@@ -662,7 +1015,7 @@
<li class="md-nav__item">
<a href="../../usage/select/" class="md-nav__link">
<a href="../../../../usage/select/" class="md-nav__link">
@@ -690,7 +1043,7 @@
<li class="md-nav__item">
<a href="../../usage/query/" class="md-nav__link">
<a href="../../../../usage/query/" class="md-nav__link">
@@ -718,7 +1071,7 @@
<li class="md-nav__item">
<a href="../../usage/dump/" class="md-nav__link">
<a href="../../../../usage/dump/" class="md-nav__link">
@@ -746,7 +1099,7 @@
<li class="md-nav__item">
<a href="../../usage/annotate/" class="md-nav__link">
<a href="../../../../usage/annotate/" class="md-nav__link">
@@ -774,7 +1127,7 @@
<li class="md-nav__item">
<a href="../../usage/phylo/" class="md-nav__link">
<a href="../../../../usage/phylo/" class="md-nav__link">
@@ -802,7 +1155,7 @@
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
<a href="../../../../usage/unitig/" class="md-nav__link">
@@ -830,7 +1183,7 @@
<li class="md-nav__item">
<a href="../../usage/estimate/" class="md-nav__link">
<a href="../../../../usage/estimate/" class="md-nav__link">
@@ -858,7 +1211,7 @@
<li class="md-nav__item">
<a href="../../usage/convert/" class="md-nav__link">
<a href="../../../../usage/convert/" class="md-nav__link">
@@ -886,7 +1239,7 @@
<li class="md-nav__item">
<a href="../../usage/utils/" class="md-nav__link">
<a href="../../../../usage/utils/" class="md-nav__link">
@@ -914,7 +1267,7 @@
<li class="md-nav__item">
<a href="../../usage/pack/" class="md-nav__link">
<a href="../../../../usage/pack/" class="md-nav__link">
@@ -942,7 +1295,7 @@
<li class="md-nav__item">
<a href="../../usage/predicates/" class="md-nav__link">
<a href="../../../../usage/predicates/" class="md-nav__link">
@@ -1024,7 +1377,7 @@
<li class="md-nav__item">
<a href="../../formats/index_layout/" class="md-nav__link">
<a href="../../../../formats/index_layout/" class="md-nav__link">
@@ -1045,6 +1398,34 @@
<li class="md-nav__item">
<a href="../../../../formats/vcf/" class="md-nav__link">
<span class="md-ellipsis">
VCF pseudo-alignment
</span>
</a>
</li>
</ul>
</nav>
@@ -1059,7 +1440,7 @@
<li class="md-nav__item">
<a href="../../architecture/" class="md-nav__link">
<a href="../../../../architecture/" class="md-nav__link">
@@ -1106,49 +1487,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#definition" class="md-nav__link">
<a href="#combining-into-a-1616-cost-matrix" class="md-nav__link">
<span class="md-ellipsis">
Definition
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#hash-based-random-minimizer" class="md-nav__link">
<span class="md-ellipsis">
Hash-based ("random") minimizer
</span>
</a>
<nav class="md-nav" aria-label="Hash-based (&#34;random&#34;) minimizer">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#hash-function" class="md-nav__link">
<span class="md-ellipsis">
Hash function
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#partition-routing-is-independent-of-minimizer-selection" class="md-nav__link">
<span class="md-ellipsis">
Partition routing is independent of minimizer selection
Combining into a 16×16 cost matrix
</span>
</a>
@@ -1172,33 +1514,20 @@
<h1 id="minimizer-selection">Minimizer selection</h1>
<h2 id="definition">Definition</h2>
<p>A <strong>minimizer</strong> of a kmer window is the m-mer (<span class="arithmatex">\(m &lt; k\)</span>) that is smallest, among all <span class="arithmatex">\(k - m + 1\)</span> overlapping m-mers in the window, under a chosen ordering. The minimizer is always taken in canonical form (lexicographic minimum of forward and reverse complement) so that selection is strand-independent.</p>
<p>The minimizer partitions a sequence into super-kmers: maximal runs of overlapping kmers that share the same minimizer (see <a href="../kmers_and_superkmers/">Kmers and super-kmers</a>).</p>
<h2 id="hash-based-random-minimizer">Hash-based ("random") minimizer</h2>
<p><code>obikmer</code> selects minimizers by hash order rather than plain lexicographic order. Ordering m-mers lexicographically on their 2-bit encoding systematically favors AT-rich m-mers (an all-A m-mer always encodes to 0), which causes low-complexity regions to dominate as minimizers and produces unbalanced partitions.</p>
<p>Instead, a well-distributed hash function <span class="arithmatex">\(H\)</span> is applied to the canonical (lexicographically minimal) form of each m-mer, and the m-mer with the smallest <span class="arithmatex">\(H\)</span> value wins. Because <span class="arithmatex">\(H\)</span> is a bijection with good avalanche properties, every distinct m-mer in a window has an equal chance of holding the minimum hash value, independent of its nucleotide composition.</p>
<p>The canonical form used as input to <span class="arithmatex">\(H\)</span> is still the lexicographic minimum of forward/reverse-complement — hashing is applied on top of it, not used to redefine it. Defining canonicity by hash value instead would bias the <em>distribution of hash values themselves</em> toward small values (the minimum of two independent hashes is not uniformly distributed), reintroducing a bias one layer down.</p>
<h3 id="hash-function">Hash function</h3>
<p>The hash function is a 64-bit mixing function (splitmix64-style finalizer) applied to the m-mer XORed with a fixed non-zero seed:</p>
<div class="arithmatex">\[H(x) = \text{mix64}(x \oplus s), \quad s = \lfloor 2^{64}/\varphi \rfloor = \texttt{0x9e3779b97f4a7c15}\]</div>
<div class="highlight"><pre><span></span><code>H(x):
x ← x ⊕ 0x9e3779b97f4a7c15
x ← x ⊕ (x &gt;&gt; 30)
x ← x × 0xbf58476d1ce4e5b9
x ← x ⊕ (x &gt;&gt; 27)
x ← x × 0x94d049bb133111eb
return x ⊕ (x &gt;&gt; 31)
</code></pre></div>
<p>The XOR seed avoids the finalizer's fixed point at 0 (<span class="arithmatex">\(\text{mix64}(0) = 0\)</span>), which would otherwise make an all-A m-mer (canonical value 0) win every window comparison.</p>
<h2 id="partition-routing-is-independent-of-minimizer-selection">Partition routing is independent of minimizer selection</h2>
<p>The hash used to select a minimizer within a window (the minimum of several hash values) and the hash used to route a super-kmer to a storage partition are computed separately:</p>
<h1 id="the-16-state-sankoff-model">The 16-state Sankoff model</h1>
<p>Each family (see <a href="../central_snp_model/">Central-position SNP model</a>) is treated as a character with 16 possible states: one per subset of the 4 possible central bases, including the empty subset (no observed form). A genome pair's calibration reduces to two separately-estimated first-order Markov models, both restricted to genome pairs below a configurable SNP-ratio ceiling (excluding saturated pairs from skewing the calibration):</p>
<ul>
<li><strong>Selection</strong> uses <span class="arithmatex">\(H\)</span> applied to every candidate m-mer in the window, keeping the minimum.</li>
<li><strong>Partition routing</strong> recomputes <span class="arithmatex">\(H\)</span> on the single selected minimizer only, once its position is fixed. This is a hash of one specific value, not the minimum of several, so it is uniformly distributed and safe to use directly for routing.</li>
<li><strong>Cardinality transitions</strong> (<span class="arithmatex">\(5 \times 5\)</span>, row-stochastic): the probability that a family observed with <span class="arithmatex">\(i\)</span> forms in one genome (<span class="arithmatex">\(i \in \{0,\dots,4\}\)</span>) is observed with <span class="arithmatex">\(j\)</span> forms in the other.</li>
<li><strong>Composition transitions</strong> (<span class="arithmatex">\(4 \times 4\)</span>, row-stochastic): the probability that an unambiguous, single-copy base observed as one of A/C/G/T in one genome is observed as another base in the other genome.</li>
</ul>
<p>See <a href="../indexing_architecture/">Partitioning and indexing architecture</a> for how the routing value is turned into a partition index.</p>
<h2 id="combining-into-a-1616-cost-matrix">Combining into a 16×16 cost matrix</h2>
<p>The two matrices are <em>not</em> combined as a plain tensor product. For a pair of states <span class="arithmatex">\((A, B)\)</span> — each a subset of <span class="arithmatex">\(\{A,C,G,T\}\)</span> — let <code>shared</code> <span class="arithmatex">\(= A \cap B\)</span>, <code>lost</code> <span class="arithmatex">\(= A \setminus B\)</span>, <code>gained</code> <span class="arithmatex">\(= B \setminus A\)</span>. The log-probability of the transition <span class="arithmatex">\(A \to B\)</span> is:</p>
<div class="arithmatex">\[\log P(A,B) = \underbrace{\log P_{\text{card}}(|A|,|B|)}_{\text{cardinality term, omitted when loss events are treated as free}} \;+\; \underbrace{\sum_{i \,\in\, \text{shared}} \log P_{\text{comp}}(i,i)}_{\text{bases conserved on both sides}} \;-\; \underbrace{\text{best\_pairing\_cost}(\text{lost}, \text{gained})}_{\text{substitutions among the differing bases}}\]</div>
<p><code>best_pairing_cost</code> enumerates every injection pairing elements of <code>lost</code> with elements of <code>gained</code> and keeps the one minimizing <span class="arithmatex">\(-\sum \log P_{\text{comp}}\)</span> over the pairs — the discrete analogue of "prefer a substitution over an independent loss and gain": if a base is lost from one side and a different base is gained on the other, that is scored as a single substitution between them (cheaper, under any sane calibration, than treating them as two unrelated cardinality-changing events) whenever such a pairing is possible.</p>
<p>The resulting <span class="arithmatex">\(16 \times 16\)</span> log-probability matrix is row-normalized in log-space (log-sum-exp, not a direct <code>exp()</code>/divide, for numerical stability), giving a genuine row-stochastic transition matrix <span class="arithmatex">\(P\)</span>. The cost matrix is then <span class="arithmatex">\(\text{cost}(A,B) = -\ln P(A,B)\)</span>, symmetrized by simple averaging:</p>
<div class="arithmatex">\[\text{sym}(A,B) = \frac{\text{cost}(A,B) + \text{cost}(B,A)}{2}\]</div>
<p>This calibrated cost matrix is what every downstream export (for TNT, PhyG, IQ-TREE) reuses, recoded into each tool's own format.</p>
<p>See <a href="../../../../usage/phylo/#sankoff-calibration-and-phylogenetic-exports"><code>phylo</code></a> for how to run the calibration and produce these exports.</p>
@@ -1248,10 +1577,10 @@
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script id="__config" type="application/json">{"annotate": null, "base": "../../../..", "features": [], "search": "../../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../../../../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>