Skip to content

Settle #309 decisions: collapse docs, benchmarks, licence - #312

Merged
dfalster merged 3 commits into
masterfrom
decisions-309
Nov 15, 2026
Merged

dfalster merged 3 commits into
masterfrom
decisions-309

Conversation

@dfalster

Copy link
Copy Markdown
Member

Acts on the maintainer decisions on the open questions in #309's first comment.

  • collapse_to_higher_taxon: docs now describe the code. accepted_name is Genus sp., suggested_name is Genus sp. [collapsed names: ...]; taxon_rank, taxon_ID and scientific_name stay those of the most likely taxon. Output unchanged; a dead line that "demoted" the rank in a table column never joined back is removed. Pinned by new assertions.
  • Old downloaded versions are not pruned (decision recorded in AGENTS.md; location already documented).
  • Benchmarks tightened. The 118 rows that only asserted suggested_name != updated_name now assert the full expected suggested_name; each was checked against the target genus/family the row originally named. test_splits_synonyms.csv is now asserted (taxon_ID and status), with two rows updated for APC data changes.
  • LICENSE names Elizabeth Wenk, matching cph in DESCRIPTION.

Merges cleanly with #311 and passes together. Details in the first comment.

🤖 Generated with Claude Code

Document what collapse_to_higher_taxon returns (rank and IDs stay
those of the most likely taxon) and drop its dead rank demotion.
Assert the full expected suggested_name for the 118 benchmark rows
that only asserted a mismatch, and taxon_ID and status for the split
benchmark. LICENSE names Elizabeth Wenk, matching DESCRIPTION.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dfalster

Copy link
Copy Markdown
Member Author

Details

collapse_to_higher_taxon, measured on APC 2024-10-11

For names collapsed because of a split (number_of_collapsed_taxa > 1), over every split accepted name (961) and every split synonym:

Column Docs said Code returns
suggested_name Genus sp. [collapsed names: ...] same
accepted_name none Genus sp. (NA in the rare case the most likely target isn't accepted)
taxonomic_status — accepted
taxon_rank genus unchanged (species, subspecies, variety)
taxon_ID, scientific_name, scientific_name_ID none those of the most likely taxon, identical to most_likely_species
update_reason — "collapsed to genus due to ambiguity" for synonyms; "aligned name accepted by APC" for accepted names (line 218 overwrites it)

The rank demotion in update_taxonomy.R assigned taxon_rank in split_taxa_table, but only aligned_name, accepted_name_2, alternative_accepted_name, suggested_collapsed_name, number_of_collapsed_taxa are joined back, so it never reached the output. Removed. Docs fixed in: update_taxonomy() (taxonomic_splits and taxon_rank), create_taxonomic_update_lookup(), the main vignette prose (both .Rmd and .Rmd.orig; the knitted output already showed the real behaviour), update_taxonomy_documentation.csv, AGENTS.md. The most_likely_species docs also said alternatives go in "a separate column"; they are in suggested_name.

New assertions in test-operation_outputs.R pin each row of the table above.

Benchmark rows

The 118 weak rows had updated_name set to a bare genus or family (Actinotus, Damasonium), which the output (Actinotus sp. [test_all_matches_TRUE]) can never equal, so they asserted only a mismatch. I did not copy the output in blindly: each current suggested_name was checked against the name the row originally intended.

  • 95: Genus sp. [...] / Family sp. [...] for the intended genus or family.
  • 19 hybrid formulas: Genus x [...] (the hybrid format) for the intended genus, including synonym genera (Dryandra → Banksia, Aporuellia → Brunoniella, fuzzy Ryandra → Randia).
  • 4 Acaena x ovina variants: the intended species plus [alternative possible names: ...].

All 118 matched their intent. Only those rows changed (118/118 lines in the diff). Mutation check: setting the Actinocarpus row's expectation back to the un-updated genus now fails the test; before, it passed.

test_splits_synonyms.csv had its taxon_ID assertion commented out and a todo for status. Now: 45/45 taxon_ID match, and each recorded status is the aligned status or appears as (status) in suggested_name. Two rows were stale against the 2024-10-11 data: Apium prostratum's expected ID (taxon/apni/51430924) no longer exists in APC, and the name is now an accepted taxon (51736246); Abutilon halophilum is now accepted (its "taxonomic synonym" usage points at itself).

Licence

LICENSE named Daniel Falster (year 2024); DESCRIPTION gives cph to Elizabeth Wenk. Now both name Elizabeth Wenk. Year set to 2023, the first CRAN release, when the holder was first named (the 2024 bump was routine).

Checks

Full test suite passes. Trial merge with #311: no conflicts; operation_outputs, match_branches and hyphenated_names pass on the merged tree.

dfalster and others added 2 commits November 15, 2026 06:47
Review of #312: a pro parte name with one target is still collapsed
(number_of_collapsed_taxa 1), and accepted_name is NA when the most
likely taxon is not accepted. Document and test both; fix
suggested_name and taxon_rank docs; quote the outputs CSV row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dfalster

Copy link
Copy Markdown
Member Author

Independent review (fresh Claude agent; Copilot and agy out of quota)

It confirmed the removed taxon_rank line has no effect (base and head identical() on 4,841 names, all three taxonomic_splits options), that rank and IDs under collapse match most_likely_species across all 1,638 collapsed rows, that the 118 benchmark values are taxonomically right (genus synonyms checked against APC), and that the two test_splits_synonyms.csv changes match the APC data. Findings, checked against the code:

Finding Verdict Action
A pro parte name whose usages all lead to one taxon is still collapsed, number_of_collapsed_taxa 1, update_reason its raw status (186 of 1,641 split names; e.g. Lycopodium selago → Huperzia sp. [collapsed names: Huperzia australiana (pro parte misapplied) ]) Confirmed Documented (the split table is every name with a pro parte usage), and pinned by a new test
accepted_name is NA when the most likely taxon is not accepted (5 rows; Abutilon muticum → Sida mutica, status "taxonomic synonym"); the test stepped around it Confirmed Documented, and asserted
"for a synonym" was too narrow for the update_reason rule Confirmed Now: "collapsed to genus due to ambiguity" when number_of_collapsed_taxa > 1 and the aligned name is not accepted
suggested_name "identical to the accepted_name" and taxon_rank docs still wrong in create_taxonomic_update_lookup() and APCalign_outputs_documentation.csv Confirmed Fixed in all three places (the CSV row is now quoted; it contains commas)
Rd rendered "(pro parte misapplied)" Confirmed Fixed
AGENTS.md additions hard-wrapped; NEWS bullets made the list loose; LICENSE year change not in NEWS Confirmed Fixed
Diff vs master shows #311 reverted Branch predated #311's merge Merged master in

Not changed: whether collapsing single-target pro parte names is itself desirable is a behaviour question, outside "docs follow the code"; the trailing " ]" in collapsed names predates this PR.

Full suite passes.

@ehwenk ehwenk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with this - but is this detail needed?

@dfalster
dfalster merged commit 4386df9 into master Nov 15, 2026
4 checks passed
@dfalster
dfalster deleted the decisions-309 branch November 15, 2026 09:35
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.

2 participants