Skip to content

Flag a grounding that is not the type-anchored clade (#374) - #598

Open
realmarcin wants to merge 1 commit into
mainfrom
flag-nontype-gtdb-374
Open

Flag a grounding that is not the type-anchored clade (#374)#598
realmarcin wants to merge 1 commit into
mainfrom
flag-nontype-gtdb-374

Conversation

@realmarcin

Copy link
Copy Markdown
Contributor

Closes #374. Implements the decision: report the disagreement, do not resolve it.

The conflict

gtdb_ground.py grounds a higher-rank NCBI taxon to whichever GTDB taxon holds the most genomes. GTDB names by nomenclatural type — the lineage containing the type species keeps the unsuffixed name, the rest take alphabetic suffixes. The rules disagree whenever a non-type clade is more heavily sequenced.

The suffix is not a heuristic: it is GTDB's own published marker for "this clade does not hold the type". That is why a regex can decide it and still be correct.

What a curator now sees

Enterococcus
  GTDB taxon   : Enterococcus_B  ⚠ NAME DIFFERS
  GTDB CURIE   : GTDB:g__Enterococcus_B
  majority     : 0.598  (at g__ rank)  [17011/28462 genomes]
  ⚠ NON-TYPE   : Enterococcus_B is not the type-anchored clade; GTDB reserves
                 Enterococcus for the lineage holding the nomenclatural type,
                 which drew 9904 genomes here (#374)

The message names the type clade and its support, because a type clade that drew 9904 genomes and one that drew none call for different action and should not read the same. Printed by the CLI, not merely stored — the value of flagging is that it is seen at grounding time; a key surfacing only in emitted YAML would be found late or never. The key is omitted entirely when there is no conflict, so its presence always means something.

It does not change any answer

Deliberately. Preferring the type clade would change what every existing grounding means on the evidence of one live case, and the majority answer is defensible — someone asking for "NCBI genus X" may well want the clade most of X's genomes sit in. test_enterococcus_warns_and_still_returns_the_majority_answer asserts g__Enterococcus_B is still returned, so a future change to resolving has to be made deliberately.

KB survey — the issue understated the scope, then overstated it

#374 counted 1 affected taxon. Sweeping all 728 gtdb_classification blocks:

  • 35 carry a non-type clade name
  • 32 of those are species-rank and are not conflicts — Ruminococcus_B gnavus, Clostridium_B kluyveri, Pseudomonas_E protegens genuinely live in the suffixed genus. Flagging them would be a false positive, and the warning is on the higher-rank path only, so it does not.
  • 3 genus-rank plus p__Bacillota_A have the actual Majority-of-genomes grounding can contradict GTDB's type-species rule #374 shape:
CURIE record
GTDB:g__Cetobacterium_A Crucian_Carp_Gut_Disease_Resistance_SynCom
GTDB:g__Enterococcus_B Electrostimulated_Mixotrophic_VFA_Producing_Enrichment_Consortium
GTDB:g__Methanobrevibacter_A Iberian_Pit_Lake_Stratified_Community
GTDB:p__Bacillota_A 4 records (ASF, Brachypodium, Naica, Rifle)

Left for a curator rather than changed here — that is what "flag, don't resolve" means, and re-grounding them is a separate decision per record.

Mutation checks

reverted result
the CLI print of the warning 1 failed (end-to-end Enterococcus)
flag fires on every name 13 failed (incl. all four type-agreeing taxa)
nothing 24 passed

-rs confirms the end-to-end tests genuinely run against the local mapping rather than skipping.

Gates

lint 0, validate-strict 0, 2488 passed.

Decision on #374: report the disagreement, do not resolve it.

gtdb_ground.py grounds a higher-rank NCBI taxon to whichever GTDB taxon holds
the most genomes. GTDB names by nomenclatural type — the lineage containing the
type species keeps the unsuffixed name, the rest take alphabetic suffixes — so
the two rules disagree whenever a non-type clade is more heavily sequenced.

The suffix is not a heuristic. It is GTDB's own published marker for "this clade
does not hold the type", which is why a regex can decide it and still be right.

Enterococcus is the live case: grounds to g__Enterococcus_B at 0.598, while
E. faecalis sits in g__Enterococcus, which drew 9904 of 28462 genomes. The
warning names the type clade and how much support it had, because a type clade
that drew 9904 genomes and one that drew none call for different curator action
and should not read the same.

Not used to override the answer. Preferring the type clade would change what
every existing grounding means on the evidence of one live case, and the
majority answer is defensible — someone asking for "NCBI genus X" may want the
clade most of X's genomes are in.

Printed by the CLI, not merely stored: the value of flagging is that a curator
sees it while grounding, and a key that surfaced only in emitted YAML would be
found later or not at all. The key is omitted entirely when there is no
conflict, so its presence always means something.

Surveyed the KB while here: of 728 gtdb blocks, 35 carry a non-type clade name,
but 32 are species-rank (Ruminococcus_B gnavus genuinely lives in the suffixed
genus — not a conflict). Only 3 genus-rank groundings and p__Bacillota_A have
the #374 shape. Listed in the PR for a curator rather than changed here.

Mutations checked: removing the CLI print reddens the end-to-end Enterococcus
test; making the flag fire unconditionally reddens the four taxa that agree
with the type rule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Majority-of-genomes grounding can contradict GTDB's type-species rule

1 participant