obikmer/UserDocMD/usage/predicates.md

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"