obikmer/UserDocMD/usage/index_command.md

index

Build a genome index from one or more sequence files. Construction proceeds in phases (scatter → dereplicate → count → layered MPHF), described in On-disk storage.

obikmer index -o OUTPUT [OPTIONS] [INPUTS...]

Arguments

Argument	Description
INPUTS...	Input sequence files or directories (FASTA/FASTQ/GenBank, gzip optional). If omitted, reads from stdin.

Options

Option	Default	Description
-o, --output	— (required)	Output index directory
--force	off	Overwrite an existing output directory
--label	input file name without extension	Genome label stored in the index
--meta KEY=VALUE	none	Attach a categorical metadata field to the genome (repeatable)
-k, --kmer-size	31	Kmer size (odd, in [11, 31])
-m, --minimizer-size	11	Minimizer size (odd, in [3, k-1])
--theta	0.7	Entropy threshold for the low-complexity filter
--level-max	6	Maximum sub-word size for the entropy score
-p, --partitions	256	Number of partitions (rounded up to a power of 2)
-T, --threads	detected core count	Number of worker threads
--max-open-files	threads / 4 (min 1)	Maximum number of input files open simultaneously
--min-abundance	1	Minimum abundance (inclusive) for a kmer to be retained
--max-abundance	none	Maximum abundance (inclusive)
--with-counts	off	Store per-kmer counts; otherwise only presence/absence is stored
--keep-intermediate	off	Keep intermediate build files instead of deleting them after construction
--approx	off	Use approximate evidence (Findere fingerprint) instead of exact evidence
-z, --findere-z	see below	Findere z parameter: number of consecutive kmers that must all match (approximate evidence only)
--evidence-bits	see below	Fingerprint bits per slot (b), approximate evidence only
--fp	see below	Target false-positive rate per z-window, approximate evidence only
--block-size	1	Block size, in unitigs, for the exact on-disk index (rounded up to a power of 2)

Exact vs. approximate evidence

By default, an index stores exact evidence: a kmer is either present or absent (or has an exact count with --with-counts), with no false positives.

With --approx, evidence is stored as a compact fingerprint instead, trading a small, tunable false-positive rate for reduced memory/disk usage. The false-positive model is:

FP = \frac{1}{2^{b \cdot z}}

where b is --evidence-bits and z is --findere-z. Any two of -z, --evidence-bits, --fp can be given and the third is derived; if none are given, defaults are b=8, z=1 (FP \approx 1/256). See estimate to explore this trade-off before building an index, and convert to change an existing index's representation afterwards.

z must be strictly less than k: the effective indexed kmer length under approximate evidence is k−z+1.