Changelog
Source:NEWS.md
APCalign (development version)
- The documentation of
taxonomic_splits = "collapse_to_higher_taxon"now describes what it returns. It said noaccepted_nameis returned and the rank is demoted to genus. In factaccepted_nameisGenus sp.(orNAwhen the most likely taxon is not accepted) andsuggested_nameGenus sp. [collapsed names: ...], whiletaxon_rank,taxon_IDandscientific_namestay those of the most likely taxon. It applies to every name with a pro parte usage, including names whose usages all lead to one taxon (number_of_collapsed_taxa1). Output is unchanged. The docs ofmost_likely_speciesare corrected too: the alternative names are insuggested_name, not in a separate column. -
LICENSEnow names Elizabeth Wenk as copyright holder, matchingDESCRIPTION, and its year is 2023, the first release. -
create_taxonomic_update_lookup()now uses itsversionandstable_or_current_dataarguments. They were documented but never passed on, so the resources loaded were always the default version:version = "2024-10-11"was silently ignored. -
default_version()no longer gives up when the GitHub API can’t be reached while the internet can. The API allows 60 unauthenticated requests an hour, and once that was used up (easily, on a shared network or in CI)default_version()returnedNULL, so every function loading resources by default returnedNULLwith “No internet connection”, even with the data already downloaded. It now falls back to the most recent locally downloaded version, as it already did offline, and says why. It also asks the API only once per R session.get_versions()anddefault_version()list only releases that hold the parquet filesload_taxonomic_resources()downloads (the 2020-05-14 and 2023-02-28 releases are CSV only). -
load_taxonomic_resources()no longer leaves a partly downloaded file in its cache when a download fails, which was then read as the cached copy on every later call. A failed download now returnsNULLwith a message, as documented, rather than an error.stable_or_current_data = "current"no longer needs the GitHub API to be reachable. The progress bar goes to stderr, with the messages, and is not shown whenquiet = TRUE. - The
outputargument ofalign_taxa()andcreate_taxonomic_update_lookup()now works as documented: a second call with the same file reads the names already there and adds the new ones. Before,align_taxa()stopped with “not in the right format” on its own file, andcreate_taxonomic_update_lookup()overwrote the file with just the current names. The file now also records each name’sidentifier, and is keyed by name and identifier, so the same name with another identifier is looked up afresh. Files written by earlier versions can be reused: their names are read as having no identifier. The other arguments are not recorded, so use the same settings with a given file. When every name is already in the file, the closing summary is not printed. -
align_taxa()andcreate_taxonomic_update_lookup()return one row per input name for any input, including input that is all missing or blank (which returned no rows), and accept a logical all-NAvector (what an empty spreadsheet column reads in as), which was an error.identifiermust be a single value or one per name, with a clear error otherwise. Columns ofupdate_taxonomy()output are always their documented type (an all-NAcolumn was logical). -
standardise_names()no longer joins the words either side ofss,s.lat.ors.str.("Acacia dealbata s.lat. Royal NP"became"Acacia dealbataRoyal NP"), and now also removess.lat.ands.str.at the end of a name. (Leading digits are still removed, so numbered lists still align; they were removed only by accident before, through a character range,+-=, that also covered the digits.) - Family names that do not end in “-aceae” (Leguminosae) no longer align as an APNI genus: APNI has a genus-rank record “Leguminosae (=RFK/2760)”. They now align as APC family synonyms, like Compositae.
-
state_diversity_counts()returnsnum_speciesas integers rather than atablecolumn, and its error for an unknown state names the argument. - Documentation corrections: the defaults of
taxonomic_splitsandAPNI_matchesincreate_taxonomic_update_lookup(); the output columns ofalign_taxa(),update_taxonomy()andcreate_taxonomic_update_lookup()(scientific_name, notscientific_name_authorship); and the main vignette, rebuilt against the current code. -
strip_names()keeps a hyphen between two letters, as in a hyphenated genus (Van-royena, ICN Art. 20.3) or epithet (Alisma plantago-aquatica,Acacia undulata-elegans). It used to turn the hyphen into a space, making one word two and shifting every later word along, so the first-two- and first-three-word keys used by the binomial and trinomial match steps matched the wrong names:"Van-royena"aligned to the species Van-royena castanosperma instead of the genus, and"Acacia undulata-elegans var. fooensis"to a different taxon, Acacia undulata var. elegans. Hyphens next to a digit, a space or a full stop, or after a rank marker or qualifier (sp-Mt Magnet,var-intermedia,x-aneura), are still removed, as are--intergrade markers; the Unicode hyphens U+2010 and U+2011 count as hyphens. The stripped keys of the reference names change the same way, andload_taxonomic_resources()now also returnshyphenated_words, the hyphenated words of the reference names. A name written with spaces where the reference name has a hyphen (Ipomoea pes caprae subsp. brasiliensis) has the hyphen put back before matching, where the words never occur unhyphenated in the reference names, so it still aligns. All earlier benchmark alignments are unchanged (#310). -
align_taxa(),update_taxonomy()andcreate_taxonomic_update_lookup()gain achars_changedcolumn: for a fuzzy match, how many characters of the name were changed to match the reference name (the Damerau-Levenshtein distance thatfuzzy_match()already uses to choose the match),0for an exact match, andNAwhen the name was not aligned. Only what the match step compared is counted: for a genus- or family-rank match, just the first word, and in most steps after case, punctuation, rank markers and filler words have been standardised or removed. It describes the size of the correction, not how reliable the match is (#307). -
create_taxonomic_update_lookup()andalign_taxa()no longer stop with “missing value where TRUE/FALSE needed” when one of a name’s first words has no letter or digit: a genus word like"12 34","1 1/2","\u00bd"or"\u00b1 Acacia"(which becomes"+/- Acacia"), or a later word that is only symbols, like"Acacia + aneura"or"Eucalyptus |". One such name used to stop the whole lookup; it now goes unmatched where it cannot be aligned.fuzzy_match()returnsNAfor text whose first word has no letter, and no longer errors when a word’s first letter is missing. -
create_taxonomic_update_lookup()now ends with a summary of what it did, unlessquiet = TRUE: how many names aligned to a species or infraspecific taxon (in the APC, or the APNI only), to a genus or family only, or not at all; how many aligned names were updated to a different name; and how many could refer to more than one accepted taxon, with a note on how the chosentaxonomic_splitsoption reports them. Each distinct input name is counted once (#131). -
aligned_reasonnow ends with the version of the APC/APNI data used, e.g.(APC/APNI version 2024-10-11), instead of the date the alignment was run. The same names aligned against the same data now give identical output on any day, so results can be diffed and cached. The run date was also the wrong provenance: what an alignment depends on is the data it was made against.load_taxonomic_resources()records this as a"version"attribute on the resources it returns. Forstable_or_current_data = "current"it is"current, downloaded <date>", since the live data has no version. Resources built withoutload_taxonomic_resources()have no such attribute, and theiraligned_reasonthen carries no suffix (#281). - APCalign no longer imports
stringr,stringiorpurrr.stringrandstringimove toSuggests, for the tests;purrris no longer used.stringibundles the ICU library and was the largest single download when APCalign runs in a web browser through webR (14 MB of about 51 MB). The string handling is now base R, through small internal helpers inR/strings.Rthat reproduce thestringrbehaviour APCalign relied on: missing values stay missing, andstringr’s ICU regular expressions are written as Perl ones with Unicode properties ([:alpha:]becomes\p{L},[:punct:]becomes\p{P}, which is not the same as base R’s[[:punct:]]). Transliteration to ASCII and ICU’s lower, title and sentence case use character tables generated once fromstringibydata-raw/ascii_table.Rand stored inR/sysdata.rda. Output is unchanged:standardise_names(),strip_names(),strip_names_extra(),extract_genus()andstandardise_taxon_rank()give identical results on 353,776 names (every APC and APNI name, the benchmark names, and versions with random typos, accents, non-breaking spaces and changed case), in bothen_US.UTF-8andC.UTF-8locales, and so do the resource tables,create_taxonomic_update_lookup()(alltaxonomic_splitsandfulloptions),native_anywhere_in_australia()andcreate_species_state_origin_matrix(). The only known differences are for text in other scripts (Greek, Cyrillic, Chinese, …), which ICU transliterates using neighbouring characters and the tables do a character at a time, and for strings of symbols and stacked combining marks that are not plausible names. -
fuzzy_match()keeps the lower-case first letter of each reference name between calls, instead of working it out for the whole reference list for every name. Results are unchanged; a lookup of 790 names with typos took 6.2 s instead of 11.0 s. -
standardise_names(),strip_names()andstrip_names_extra()now apply their text substitutions in a loop instead of%>%chains. Output is unchanged (checked on every APC and APNI name). magrittr’s%>%runs a chain as nested calls, and with the 46-step chain instandardise_names()a lookup of even a single name needed an R evaluation depth of about 430. That overflows small stacks: APCalign running in a web browser through webR failed in Safari with “Maximum call stack size exceeded”. A full lookup now needs a depth of about 110. - Lighter dependencies. The cached APC/APNI parquet files are now read with
nanoparquetinstead ofarrow, a much smaller install that doesn’t need the Arrow C++ library. The files and the loaded resources are unchanged.readrmoves fromImportstoSuggests: it is only needed forload_taxonomic_resources(stable_or_current_data = "current")and for theoutputargument ofalign_taxa(),update_taxonomy()andcreate_taxonomic_update_lookup(). Each of these now asks you to install it if it is missing.crayonis replaced bycli, whichdplyralready installs.
APCalign 2.0.1
CRAN release: 2026-09-09
-
fuzzy_match()no longer confirms a fuzzy match against a candidate that drops anaff./cf./xqualifier present in the query. Itscheck_match()confirmation step only compared word positions up to the shorter of query/candidate, soAcacia aff. aneura(“resembles Acacia aneura, not confidently identified”) could fuzzy-match past its qualifier to the unrelated accepted speciesAcacia aptaneurainstead of being capped at genus rank. A query containingaff,cf, orxas a standalone word now requires the candidate to contain that same token, or the candidate is rejected outright before the coarser word-position check runs; genuineaff./cf.-qualified synonyms and named hybrids that still need fuzzy matching to fix a typo are unaffected. -
standardise_taxon_rank()no longer corrupts rank values that are already English, or that merely contain a Latin rank term as a substring.sectiois a literal prefix of its own translation (section) andformasits insideinformal, so replacing either anywhere in the input silently mangledsection/subsection/zoosectionintosectionn/subsectionn/zoosectionn, andinformal/informal groupintoinforml/informl group. Both terms are now matched only as the last word of the value, which still translates the prefixed ranks that need it (subsectio,subforma). APC/APNI rank values are unaffected — the fix changes output only for the zoological and DwC vocabularies, where it was found (traitecoevo/taxonAlign#11). -
standardise_names()no longer rewritesaffinistoaff.when it is the species epithet of an infraspecific name — that is, when the next word is a rank marker (subsp.,var.,f.,ser.,cv.and their unabbreviated or unpunctuated variants). PreviouslyGomphrena affinis subsp. pilbarensisbecameGomphrena aff. subsp. pilbarensis, a name that exists nowhere, so it could only ever align to genus rank. Eight APC/APNI names were affected, three of them currently accepted; all now align at their own rank. A trailingaffinis(Acacia affinis) was already left alone and still is. Two hybrid formulas of the formGenus affinis x Genus epithetare still rewritten, and are left for a follow-up. - Fix malformed
aligned_reasontext for fuzzy genus-levelaff./affinismatches (match_06b/06c/06d), which previously appended the date without a separating(. -
align_taxa(full = TRUE)no longer leaks the internalidentifier_string,identifier_string2andaligned_name_tmpcolumns when every name is aligned before the last match step runs. The output is now the documented set of columns in all cases. -
native_anywhere_in_australia()now checks for missing taxonomic resources before building the state-origin matrix, so an offline call reports the problem once instead of once per function that gives up. Its native/introduced test also now reads only the state columns, so a taxon whose name contains “native” (e.g. thenativitatisepithets) can no longer be misclassified. - Internal refactor of
match_taxa(): the ~54 match steps now share helper functions rather than repeating the same block of code. Alignment output is unchanged. - Internal refactor: the duplicated
gsub()-wrapper helper instandardise_names(),strip_names()andstrip_names_extra()is now a single sharedgsub_perl(), and a redundant nested copy ofrelevel_taxonomic_status_preferred_order()insidesynonyms_for_accepted_names()has been removed in favour of the existing top-level function. Behaviour is unchanged.
APCalign 2.0.0
CRAN release: 2026-03-27
- New function
synonyms_for_accepted_names()to list synonyms for currently accepted taxon names. -
load_taxonomic_resources()now caches results in memory for the duration of the R session, so repeated calls with the same version return immediately without re-downloading or re-processing data. - New function
clear_cached_resources()to remove the session cache and force a reload. -
load_taxonomic_resources()now works offline when parquet files have been previously downloaded;default_version()falls back to the most recently cached local version when no internet connection is available. - Internal taxonomic resource tables renamed to snake_case;
familycolumn added to resource tables. - Functions
create_species_state_origin_matrix()andstate_diversity_counts()now includes the parameterinclude_infrataxa, allowing users to select whether just species-rank taxa or species and infra-specific taxa are output in the table. Whencreate_species_state_origin_matrix()is called bynative_anywhere_in_australia(),include_infrataxa = TRUEis set as the default, so infrataxa can also be checked by this function.
APCalign 1.1.6
- Fix issue #262: filter to accepted species only in genus-family lookup
- Skip problematic tests on CRAN
- Update maintainer to Elizabeth Wenk, reflecting her leading role in writing the core of the package algorithms and maintaining it going forward.
APCalign 1.1.3
CRAN release: 2025-02-11
- Failing gracefully for the edge case when the internet is up generally but github is down for a few seconds
APCalign 1.1.2
CRAN release: 2025-01-28
Added
get_versions()Create a genus->family lookup from the specified APC release
APCalign 1.0.2
CRAN release: 2024-08-17
Minor update to fix issues
- Deal with the vignette issues that emerged on CRAN
- Improve “graceful failing”, based on issues that have come up on github CI
- minor formatting
APCalign 1.0.1
CRAN release: 2024-05-30
First major release of APCalign. A preprint is available at https://www.biorxiv.org/content/10.1101/2024.02.02.578715v1. Article has been accepted for publication at Australian journal of Botany.
Following review, a number of changes have been implemented. These have sped & streamlined the package.
- Update function documentation
- Speed up
extract_genus - Write a replacement function for
stringr::wordthat is much faster. - Additional speed up and accuracy of fuzzy_match function by
- Restricting reference list to names with the same first letter as input string.
- Switch from using
utils::adisttostringdist::stringdist(method = "dl")
- Rework
standardise_namesto remove punctuation from the start of the string - Rework
strip_names_extra(previouslystrip_names_2) to just perform additional functions tostrip_names, rather than repeating those performed bystrip_names. - Avoid importing entire packages by using package::function format throughout and removing functions from @import
- Add fuzzy match arguments to
create_taxonomic_update_lookup - Add 3 additional family-level APC matches to
match_taxa. - Refine tests
- Make messages to console optional
- Fix issue with fails when github is down (https://github.com/traitecoevo/APCalign/issues/205)
- Update installation instructions
- Added how to cite and version APCalign as an article
- Exported
default_version - Add citing method for R package
- Update GitHub Actions
- Improved family alignments
- Added
standardise_taxon_rank - Improved messaging during alignment