Update documentation to explain that merged indices can serve as sources if at least one source is unmerged, and that the resulting column order follows the base index first. Clarify that explicitly named files are always read regardless of extension, with format detection based on content. - refactor: prevent I/O errors when re-merging packed outputs by restricting `choose_base` to valid destinations via new `can_be_destination` check - fix: handle zero-layer partitions in `build_index_layer` and `remove_build_artifacts` to skip unnecessary operations - feat: allow `PathIter` to treat unrecognized extensions as explicit files, ensuring they are not silently dropped during directory expansion - test: add comprehensive tests for `PathIter` including extension recognition, explicit file handling, and stdin sentinel behavior - test: update smoke tests to verify empty partitions, `.fna.gz` indexing, and refusal of merging only packed indexes - chore: remove obsolete cargo build environment variables from `run.sh` script
3.7 KiB
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. |
Which files are read
A file named explicitly on the command line is always read, whatever its extension: the format (FASTA, FASTQ or GenBank) and the compression (gzip, bzip2, xz or zstd) are detected from the content. If the content is not a sequence file, the command reports an error rather than skipping the file.
When an input is a directory, the files inside it are selected by extension: .fasta, .fa, .fna (the extension of NCBI genome downloads), .ffn, .fas, .fsa, .fastq, .fq, .gbff, .gbk and .gb, each optionally followed by .gz.
A small input spread over many partitions leaves most partitions empty. This is valid: the index is built normally and empty partitions simply hold no k-mers.
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.