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 [`reindex`](reindex.md) 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.
|