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/usage/pack/index.html
+6 -34
View File
@@ -704,34 +704,6 @@
<li class="md-nav__item">
<a href="../name-tree/" class="md-nav__link">
<span class="md-ellipsis">
name-tree
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../unitig/" class="md-nav__link">
@@ -789,14 +761,14 @@
<li class="md-nav__item">
<a href="../reindex/" class="md-nav__link">
<a href="../convert/" class="md-nav__link">
<span class="md-ellipsis">
reindex
convert
@@ -1198,15 +1170,15 @@
<tr>
<td><code>--sparse</code></td>
<td>off</td>
<td>Pack presence/absence matrices into a sparse, deduplicated format instead of the dense one</td>
<td>Pack presence/absence and count matrices into a sparse, deduplicated format instead of the dense one</td>
</tr>
</tbody>
</table>
<p>The index directory is locked for exclusive access while packing.</p>
<h2 id="-sparse"><code>--sparse</code></h2>
<p>Presence/absence data (which genomes carry each kmer) is often mostly empty — most kmers are present in only a handful of genomes out of the whole collection. The default (dense) packed format stores one bit per genome for every kmer regardless of how many genomes actually carry it; <code>--sparse</code> instead stores each kmer's genome list directly, and deduplicates identical lists shared by many kmers (common in real data, since kmers from the same conserved region tend to be carried by the same genomes).</p>
<p>On real genome collections this has measured at roughly 7x smaller on disk than the dense format, and single-kmer lookups (the shape <code>phylo</code>'s sibling-annex/entropy/Sankoff computations use) are typically faster too, since the smaller files mean less data to read from disk. The trade-off: reading a whole genome column at once (used by <code>--metric</code> distance-matrix computations) is much slower on the sparse format than on the dense one, since there is no native column layout to read sequentially — prefer the dense format (the default, no <code>--sparse</code>) for indexes you mainly query with <code>phylo</code>'s plain <code>--metric</code> distance matrices.</p>
<p>Count matrices (<code>--metric</code> on a count index) are not affected by <code>--sparse</code> — only presence/absence matrices are.</p>
<p>Matrix data (which genomes carry each kmer, or with what count) is often mostly empty — most kmers are present in only a handful of genomes out of the whole collection. The default (dense) packed format stores one entry per genome for every kmer regardless of how many genomes actually carry it; <code>--sparse</code> instead stores each kmer's genome list directly. For presence/absence matrices, identical genome lists shared by many kmers are also deduplicated (common in real data, since kmers from the same conserved region tend to be carried by the same genomes); for count matrices, the genome list is deduplicated the same way but each kmer's actual counts are kept per-kmer, since two kmers sharing the same genome list rarely carry the same counts.</p>
<p>On real genome collections this has measured at roughly 7x smaller on disk than the dense format for presence/absence, and single-kmer lookups (the shape <code>phylo</code>'s sibling-annex/entropy/Sankoff computations use) are typically faster too, since the smaller files mean less data to read from disk. The trade-off: reading a whole genome column at once (used by <code>--distance</code> matrix computations) is much slower on the sparse format than on the dense one, since there is no native column layout to read sequentially — prefer the dense format (the default, no <code>--sparse</code>) for indexes you mainly query with <code>phylo</code>'s <code>--distance</code> matrices.</p>
<p><code>--sparse</code> applies to both presence/absence and count matrices — a count index (<code>--distance</code> matrix computations included) is packed sparse the same as a presence index.</p>