OBIKmers/obikmer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity

Update documentation for CLI command renames and new commands

Browse Source 
Renames the reindex command to convert across all usage guides and navigation menus. Adds documentation for the newly introduced name-tree command. Updates flag references, such as replacing --metric with --distance in pack and phylo modules, and adjusts MkDocs configuration to match the revised structure. All changes are strictly limited to documentation and configuration files.
This commit is contained in:
Eric Coissac
2026-08-28 23:06:05 +02:00
parent 95fa0c93b2
commit caf59b5658
38 changed files with 666 additions and 2433 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/formats/index_layout/index.html
+4 -32
View File
@@ -702,34 +702,6 @@
<li class="md-nav__item">
<a href="../../usage/name-tree/" class="md-nav__link">
<span class="md-ellipsis">
name-tree
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../usage/unitig/" class="md-nav__link">
@@ -787,14 +759,14 @@
<li class="md-nav__item">
<a href="../../usage/reindex/" class="md-nav__link">
<a href="../../usage/convert/" class="md-nav__link">
<span class="md-ellipsis">
reindex
convert
@@ -1203,7 +1175,7 @@
<h2 id="minimal-perfect-hash-function-mphf">Minimal perfect hash function (MPHF)</h2>
<p>Each partition's surviving kmers are mapped to a dense range of integer slots by a minimal perfect hash function: no collisions, near-optimal space (a few bits per key), O(1) lookup. Because an MPHF maps <em>any</em> input to some slot — including kmers that were never indexed — a lookup alone cannot distinguish a genuinely indexed kmer from an arbitrary one; every lookup is followed by an evidence check.</p>
<h2 id="evidence-exact-vs-approximate">Evidence: exact vs. approximate</h2>
<p>Two verification modes are available, selected at build time (<code>index --approx</code>) and convertible afterwards (<a href="../../usage/reindex/"><code>reindex</code></a>):</p>
<p>Two verification modes are available, selected at build time (<code>index --approx</code>) and convertible afterwards (<a href="../../usage/convert/"><code>convert</code></a>):</p>
<ul>
<li><strong>Exact</strong> (default): the hashed slot stores a pointer back into the partition's unitig data. At query time the kmer is reconstructed from that location and compared directly to the query. Zero false positives, at the cost of one extra random read per lookup.</li>
<li><strong>Approximate</strong> (<code>--approx</code>): the slot stores a short fingerprint (<code>--evidence-bits</code> bits) instead of a pointer; verification is a single fingerprint comparison. This trades a small, bounded false-positive rate (<span class="arithmatex">\(1/2^b\)</span> per kmer, reduced further to about <span class="arithmatex">\(1/2^{b \cdot z}\)</span> for a read requiring <span class="arithmatex">\(z\)</span> consecutive matching kmers via the <code>-z</code>/<code>--findere-z</code> parameter) for lower memory and disk usage, since no reconstruction index is needed. See <a href="../../usage/estimate/"><code>estimate</code></a> to explore this trade-off before building.</li>
@@ -1230,7 +1202,7 @@
</code></pre></div>
<p><code>unitigs.bin</code> is the only file from which the indexed kmer content can be fully recovered; it is always retained. Every other file (MPHF, evidence, counts) is derived from it.</p>
<p>A <strong>layer</strong> corresponds to one increment of kmer content added to a partition — most commonly, one <a href="../../usage/merge/"><code>merge</code></a> operation that introduces kmers not already present in the index. Genomes already present in the index simply gain new columns in the existing layers' count/presence data; only genuinely new kmer content is assembled into a new layer. Because of this, merging cost scales with the novel kmer content being added, not with the accumulated size of the index. A query against an index with several layers checks each layer's MPHF in turn.</p>
<p>Sources merged together must share the same kmer size, minimizer size, partition count, and evidence mode (including matching approximate-mode parameters); mismatches are rejected rather than silently reconciled — <a href="../../usage/reindex/"><code>reindex</code></a> one of the sources first if needed.</p>
<p>Sources merged together must share the same kmer size, minimizer size, partition count, and evidence mode (including matching approximate-mode parameters); mismatches are rejected rather than silently reconciled — <a href="../../usage/convert/"><code>convert</code></a> one of the sources first if needed.</p>
<p><code>obikmer pack</code> consolidates a partition's per-column files (counts/presence) into a single file, reducing the number of file opens needed at query time.</p>