obikmer/UserDocMD/index.md

obikmer

obikmer is a command-line tool for counting, indexing, querying and comparing DNA sequences represented as kmer sets. It targets individual genome datasets of tens of gigabases, with an emphasis on computational, memory, and disk efficiency.

All functionality is exposed through a single binary, obikmer, organized as subcommands.

Core principles

• Kmers are of fixed, odd length k, chosen at index-construction time in the range [11, 31] (see Kmers and super-kmers).
• Each kmer fits in a 64-bit word using a 2-bit-per-base encoding (see DNA encoding).
• Kmers are handled in canonical form (\text{canonical}(kmer) = \min(kmer, \text{revcomp}(kmer))), making counting strand-independent.
• Sequences are decomposed into super-kmers before storage, anchored on a hash-selected minimizer (see Minimizer selection), then routed to one of several partitions for parallel, memory-bounded processing (see Partitioning and indexing architecture).
• Low-complexity kmers can be filtered out at index-construction time using an entropy-based score (see Low-complexity kmer filter).

Commands

Command	Purpose
superkmer	Extract super-kmers from a sequence file and write them to stdout
index	Build a genome index
merge	Merge multiple indexes into one
filter	Retain only kmers matching ingroup/outgroup predicates
select	Project and/or aggregate genome columns of an index
query	Query an index with sequences and annotate matches
dump	Dump indexed kmers as CSV
annotate	Add, update, or dump genome metadata
phylo	Compute pairwise evolutionary-distance proxies, trees, and phylogenetic exports
name-tree	Translate a TNT/PhyG numeric-label tree export back to real taxon names
unitig	Dump the unitigs of an index as FASTA
estimate	Estimate approximate-index parameters before indexing
reindex	Convert an index's evidence representation (exact ↔ approximate)
utils	Miscellaneous index maintenance and inspection utilities
pack	Pack per-column matrix files into a single-file format

See Genome predicates and taxonomy paths for the selection language shared by filter, select, dump, and unitig.

Further reading

• Index construction and on-disk layout
• Architecture notes for advanced use — parallel execution, NUMA awareness, index dimensioning

Input formats

• superkmer and index: FASTA (.fa, .fasta), FASTQ (.fq, .fastq), GenBank flat file (.gb, .gbk, .gbff), all optionally gzip-compressed; directories are expanded recursively; streaming stdin via - or when no input path is given.
• query: FASTA or FASTQ, optionally gzip-compressed; streaming stdin the same way.

Parameter constraints

These constraints are checked at startup; an invalid value exits immediately with an error.

Parameter	Constraint	Reason
k (--kmer-size)	odd, k \in [11, 31]	odd length guarantees the canonical form is always well defined; the range keeps a kmer within a 64-bit word while retaining specificity
m (--minimizer-size)	odd, 3 \le m \le k-1	same palindrome argument as k; must be strictly shorter than the kmer
z (-z, approximate evidence only)	z \le k-1	the effective indexed kmer size is k-z+1

Genome label constraints

Genome labels are arbitrary Unicode strings, with the following restrictions:

Character	Forbidden	Reason
/	yes	filesystem path separator
=	yes	separator used by --new-label
\0	yes	null byte
\n, \r, \t	yes	would break CSV output
spaces	allowed	quote in the shell, e.g. --new-label 'new label=old label'

Empty labels are rejected. A label derived automatically from the input file name (when --label is omitted) is not validated, since it is already filesystem-safe.