Repository navigation
Common names tracking issue #38
Description
Issue text drafted with the help of Opus 5.5.
Common-name handling has gone through several iterations across releases, PRs, and branches. This issue collects that history in one place and gathers the open work that should inform the next iteration.
History
| Stage | Where | Released? | Behavior |
|---|---|---|---|
| Original retrieval | #6 (merged 2025-05-01) | v0.1.0 | Merges GBIF Backbone vernacular names into resolved output. Input common names could pass through. |
| Deterministic rewrite | #14 (open, branch feat/deterministic-common-names) |
never merged | Backbone-only names, Polars rewrite, higher-rank coverage, tests. The review discussion there (usefulness of higher-rank names such as "Orchid" for many species; recording the source rank) directly shaped later work. |
| Hierarchical fallback | #26 | v0.2.0 | Always climbs species → kingdom. Prefers the first English name, then any language. Input common names always replaced. |
| Optional fallback + rank column | #36 → #37 | unreleased (on main only) |
--no-higher-rank-fallback disables climbing. New common_name_rank column records the rank the name came from. Default output matches v0.2.0 plus the new column. |
Note: #37's behavior has not shipped in any tagged release. If the next iteration lands before the next tag, release notes should describe the net change from v0.2.0.
Open items
- Resolved common names should not allow variable input data through #10: input common names must not pass through. The literal request is addressed since v0.2.0 (the input
common_namecolumn is always dropped before lookup). Its broader goal, a uniform one-to-one mapping between taxonomy and vernacular, is affected by the homonym item below. - Homonym-blind taxon lookup (new). Each rank's name is mapped to a backbone
taxonIDbycanonicalNamealone, ignoring kingdom andtaxonomicStatus. Duplicates are dropped with Polarsunique(subset=[rank]), which keeps an arbitrary row (stable in practice, not guaranteed). In the GBIF Backbone: 44,403 duplicated genus names (11,520 spanning more than one kingdom), 248,587 duplicated species names, 194 duplicated family names. Example: genus Laelia maps to taxonID 7562880 (Plantae, doubtful) for every row, so animal Laelia can receive a plant's common name. - Common names cache dir dead code to remove #35: dead
cache_dirhandling in the standalone common-names parser. - IO inaccuracies in documentation #34 (last bullet):
--full-rerundoes not apply tocommon-names, although the command writes its own manifest. Decide whether it should, or document that it isresolve-only.
Related branches (kept for reference)
feat/deterministic-common-names: Deterministic common names; performance improvement; higher rank coverage #14's branch.
Next iteration
Should include fixes required by the above notes.
Before common names updates are added to a tagged release, the strategy should shift to use Catalogue of Life vernacular data retrieved from here.
Furthermore, a vernacular assignment strategy for TaxonoPy-resolved entries should be agreed upon. Default behavior can be unfiltered retrieval of all vernacular data, enabling a user to apply custom strategy of their design. Additionally, we can provide reasonable prioritization/filtering strategies that serve our own use-cases.
Activity