docs: add obikmer user guide and MkDocs build configuration

Introduces a comprehensive documentation set covering theoretical foundations, CLI usage, installation, and system architecture. Adds MkDocs configuration and Makefile targets to generate, serve with live reload, and clean the documentation site. Includes citation styles and bibliography files for academic references.
2026-08-13 17:19:01 +02:00
parent 0c86ea0385
commit 6acafa7f2c
28 changed files with 1497 additions and 1 deletions
@@ -0,0 +1,46 @@
+# Genome predicates and taxonomy paths
+
+Several commands ([`filter`](filter.md), [`select`](select.md), [`dump`](dump.md), [`unitig`](unitig.md)) select or group genomes using the same predicate language over genome metadata (see [`annotate`](annotate.md) for attaching metadata to a genome).
+
+## Predicate syntax
+
+| Form | Meaning |
+|---|---|
+| `*` or `all` | Matches every genome (case-insensitive) |
+| `key=v1\|v2` | Genome's `key` metadata equals one of the listed values |
+| `key!=v` | Genome's `key` metadata does not equal `v` |
+| `key~path` | Genome's `key` metadata (a taxonomy path) matches `path` (ancestry match) |
+| `key!~path` | Genome's `key` metadata does not match `path` |
+
+A genome whose metadata does not contain `key` at all cannot be classified by that predicate and is excluded from the relevant group's quorum count.
+
+Multiple `--ingroup` predicates are combined with AND; multiple `--outgroup` predicates are combined with OR. When both an ingroup and an outgroup predicate would match the same genome, ingroup classification wins.
+
+## Taxonomy paths
+
+A metadata value is treated as a taxonomy path when it starts with the literal prefix `taxonomy:/`; any other value is treated as a plain string and only supports `=`/`!=`.
+
+```
+taxonomy:/segment1@rank1/segment2@rank2/...
+```
+
+Each segment is a name, optionally annotated with a rank (e.g. `@family`, `@genus`, `@species`); ranks are optional and can be mixed within a path. The `@` character is reserved inside taxonomy paths and cannot appear in segment names or rank labels.
+
+### Path matching (`~` / `!~`)
+
+Matching compares segment names only (ranks are informational, not part of the match), with anchoring controlled by leading/trailing `/`:
+
+| Pattern | Matches |
+|---|---|
+| `A/B` | anywhere in the path |
+| `/A/B` | at the start of the path (prefix) |
+| `A/B$` | at the end of the path (suffix) |
+| `/A/B$` | the entire path (exact) |
+
+A rank-qualified query, `key@rank=value`, matches only when the path's segment at that specific rank equals `value`.
+
+### Example
+
+```bash
+obikmer filter source -o output --ingroup "taxon~/Betulaceae/Betula"
+```