Eric Coissac
caf59b5658
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.
51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
# 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](../formats/index_layout.md).
|
|
|
|
```bash
|
|
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`](estimate.md) to explore this trade-off before building an index, and [`convert`](convert.md) 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.
|