47 lines
2.1 KiB
Markdown
47 lines
2.1 KiB
Markdown
|
# 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"
|
||
|
|
```
|