Skip to content

# 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 `reindex` to convert an existing index between the two representations.

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