Skip to content

# Genome predicates and taxonomy paths

Several commands (`filter`, `select`, `dump`, `unitig`) select or group genomes using the same predicate language over genome metadata (see `annotate` 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

    obikmer filter source -o output --ingroup "taxon~/Betulaceae/Betula"