more changes

* ensure 1-sentence function names are similar to longer descriptions
* change new function descriptions file from qmd to rmd
* more work formatting tables for vignettes
* add missing info into vignettes; delete an unused vignette

R/align_taxa.R

@@ -1,6 +1,6 @@
-#' Find taxonomic alignments for a list of names to a version of the Australian Plant Census (APC) through standardizing formatting and checking for spelling issues
+#' For a list of Australian plant names, find taxonomic or scientific name alignments to the APC or APNI through standardizing formatting and fixing spelling errors
 #'
-#' Finds taxonomic alignments in the APC or APNI. 
+#' This function finds taxonomic alignments in APC or scientific name alignments in APNI. 
 #' It uses the internal function `match_taxa` to attempt to match input strings to taxon names in the APC/APNI.
 #' It sequentially searches for matches against more than 20 different string patterns, 
 #' prioritising exact matches (to accepted names as well as synonyms, orthographic variants) over fuzzy matches. 

R/create_species_state_origin_matrix.R

@@ -1,7 +1,7 @@
-#' Process geographic data and return state level species origin and diversity counts
+#' Use the taxon distribution data from the APC to determine state level native and introduced origin status
 #'
 #' This function processes the geographic data available in the APC and 
-#' returns state level diversity for native, introduced and more complicated species origins.
+#' returns state level native, introduced and more complicated origins status for all taxa.
 #'
 #'
 #' @family diversity methods

R/create_taxonomic_update_lookup.R

@@ -1,4 +1,4 @@
-#' Create a lookup table to help fix the taxonomy for a list of Australian plant species
+#' Create a lookup table with the best-possible scientific name match for a list of Australian plant names
 #'
 #' This function takes a list of Australian plant names that need to be reconciled with current taxonomy and 
 #' generates a lookup table of the best-possible scientific name match for each input name. 

R/native_anywhere_in_australia.R

@@ -1,4 +1,4 @@
-#' Check if a vector of species are native anywhere in Australia
+#' For a vector of taxon names in to the APC, check if the species are native anywhere in Australia
 #'
 #' This function checks if the given species is native anywhere in Australia according to the APC. 
 #' Note that this will not detect within-Australia introductions, e.g. if a species is from Western Australia and is invasive on the east coast.

R/standardise_names.R

@@ -1,7 +1,6 @@
 
-#' Standardise Taxon Names
+#' Standardises taxon names by performing a series of text substitutions to remove common inconsistencies in taxonomic nomenclature.
 #'
-#' Standardises taxon names by performing a series of text substitutions to remove common inconsistencies in taxonomic nomenclature. 
 #' The function takes a character vector of taxon names as input and 
 #' returns a character vector of taxon names using standardised taxonomic syntax as output. 
 #' In particular it standardises taxon rank abbreviations and qualifiers (subsp., var., f.), as people use many variants of these terms. 

R/state_diversity_counts.R

@@ -1,4 +1,4 @@
-#' Calculate Australian plant state-level diversity for native, introduced, and more complicated species origins
+#' For Australian states and territories, use data from the APC to calculate state-level diversity for native, introduced, and more complicated species origins
 #'
 #' This function calculates state-level diversity for native, introduced, and more complicated species origins 
 #' based on the geographic data available in the APC.

R/strip_names.R

@@ -1,4 +1,4 @@
-#' Strip taxonomic names of subtaxa designations and special characters
+#' Strip taxonomic names of taxon rank abbreviations and qualifiers and special characters
 #'
 #' Given a vector of taxonomic names, this function removes subtaxa designations ("subsp.", "var.", "f.", and "ser"),
 #' special characters (e.g., "-", ".", "(", ")", "?"), and extra whitespace. The resulting vector
@@ -34,7 +34,7 @@ strip_names <- function(taxon_names) {
     tolower()
 }
 
-#' Strip taxonomic names of subtaxa designations, filled words and special characters
+#' Strip taxonomic names of taxon rank abbreviations and qualifiers, filler words and special characters
 #'
 #' Given a vector of taxonomic names, this function removes subtaxa designations ("subsp.", "var.", "f.", and "ser"),
 #' additional filler words and characters (" x " for hybrid taxa, "sp."), 

R/update_taxonomy.R

@@ -1,4 +1,4 @@
-#' Use APC and APNI to update taxonomy, replacing synonyms to current taxa where relevant
+#' For a list of taxon names aligned to the APC, update the name to an accepted taxon concept per the APC and add scientific name and taxon concept metadata to names aligned to either the APC or APNI. 
 #'
 #' This function uses the APC to update the taxonomy of names aligned to a taxon concept listed in the APC to the currently accepted name for the taxon concept. 
 #' The aligned_data data frame that is input must contain 5 columns, 

_pkgdown.yml

@@ -19,9 +19,9 @@ navbar:
       - text: "Data providers"
       - text: APC and APNI
         href: articles/data-providers.html
-      - text: "Data caching"
-      - text: How is APC/APNI stored in APCalign? 
-        href: 'articles/caching.html'
+      - text: "Functions"
+      - text: Details on the 10 exported functions, including examples of usage
+        href: function_notes.html
       - text: -------
       - text: "Taxon matching"
       - text: Our fuzzy matching  algorithm

inst/extdata/APCalign_outputs_documentation.csv

@@ -2,7 +2,7 @@ variable,returned by,description
 original_name,default,The original plant name.
 aligned_name,default,The input plant name that has been aligned to a taxon name in the APC or APNI by the align_taxa function.
 accepted_name,default,The APC-accepted plant name when available.
-suggested_name,default,The suggested plant name to use. Identical to the accepted_name when an accepted_name exists; otherwise the the suggested_name is the aligned_name.
+suggested_name,default,The suggested plant name to use. Identical to the accepted_name when an accepted_name exists; otherwise the suggested_name is the aligned_name or the aligned name with an outdated genus updated.
 genus,default,The genus of the accepted (or suggested) name; only APC-accepted genus names are filled in. 
 family,full,The family of the accepted (or suggested) name; only APC-accepted family names are filled in.
 taxon_rank,default,The taxonomic rank of the suggested (and accepted) name.
@@ -18,4 +18,4 @@ taxon_ID_genus,full,An identifier for the genus; only filled in if an APC-accept
 scientific_name_ID,full,An identifier for the nomenclatural (not taxonomic) details of a scientific name; available for both APC and APNI names.
 taxonomic_status_aligned,full,The taxonomic status of the aligned name before any taxonomic updates have been applied.
 row_number,full,The row number of a specific original_name in the input.
-number_of_collapsed_taxa,default,The number of possible taxon names that have been collapsed when taxonomic_splits == "collapse_to_higher_taxon".
+number_of_collapsed_taxa,default,"The number of possible taxon names that have been collapsed when taxonomic_splits == ""collapse_to_higher_taxon""."

inst/extdata/match_taxa_documentation.csv

@@ -7,12 +7,12 @@ match_03a,"Detect ` -- `, `--` (intergrade taxa) and align to genus","first word
 match_03b,"Detect ` -- `, `--` (intergrade taxa) and align to genus","first word (""genus"")",fuzzy,APC accepted taxon concepts,genus,
 match_03c,"Detect ` -- `, `--` (intergrade taxa) and align to genus","first word (""genus"")",fuzzy,other APC taxon concepts,genus,
 match_03d,"Detect ` -- `, `--` (intergrade taxa) and align to genus","first word (""genus"")",fuzzy,APNI,genus,
-match_03e,"Detect ` -- `, `--` (intergrade taxa), but fail to align to genus",NA,no match,NA,genus,
+match_03e,"Detect ` -- `, `--` (intergrade taxa), but fail to align to genus",NA,no match,NA,NA,
 match_04a,Detect ` \` (indecision between taxa) and align to genus.,"first word (""genus"")",exact,"APC accepted taxon concepts, other APC taxon concepts, APNI",genus,Next find strings that indicate a name reflects a data collector's indecision about which of two (or more) taxa is the appropriate taxon. These names can only be aligned to a genus.
 match_04b,Detect ` \` (indecision between taxa) and align to genus.,"first word (""genus"")",fuzzy,APC accepted taxon concepts,genus,
 match_04c,Detect ` \` (indecision between taxa) and align to genus.,"first word (""genus"")",fuzzy,other APC taxon concepts,genus,
 match_04d,Detect ` \` (indecision between taxa) and align to genus.,"first word (""genus"")",fuzzy,APNI,genus,
-match_04e,"Detect ` \` (indecision between taxa), but fail to align to genus",NA,no match,NA,genus,
+match_04e,"Detect ` \` (indecision between taxa), but fail to align to genus",NA,no match,NA,NA,
 match_05a,"Detect scientific names, including authorship",original_name,exact,APC accepted taxon concepts,species/infraspecific,"Check if strings are full scientific names, including authorship."
 match_05b,"Detect scientific names, including authorship",original_name,exact,other APC taxon concepts,species/infraspecific,
 match_06a,"Detect canonical names, lacking authorship",cleaned_name,exact,APC accepted taxon concepts,species/infraspecific,"Check if strings are taxon names, lacking authorship."
@@ -24,14 +24,14 @@ match_09a,"Detect `aff`, `affinis` (affinity to) and align to genus","first word
 match_09b,"Detect `aff`, `affinis` (affinity to) and align to genus","first word (""genus"")",fuzzy,APC accepted taxon concepts,genus,
 match_09c,"Detect `aff`, `affinis` (affinity to) and align to genus","first word (""genus"")",fuzzy,other APC taxon concepts,genus,
 match_09d,"Detect `aff`, `affinis` (affinity to) and align to genus","first word (""genus"")",fuzzy,APNI,genus,
-match_09e,"Detect `aff`, `affinis` (affinity to), but fail to align to genus",NA,no match,NA,genus,
+match_09e,"Detect `aff`, `affinis` (affinity to), but fail to align to genus",NA,no match,NA,NA,
 match_10a,"Detect canonical names, lacking authorship",stripped_name,imprecise fuzzy,APC accepted taxon concepts,species/infraspecific,"Further checks if strings are taxon  names, lacking authorship, now with imprecise fuzzy matching"
 match_10b,"Detect canonical names, lacking authorship",stripped_name,imprecise fuzzy,other APC taxon concepts,species/infraspecific,
 match_11a,Detect ` x ` (hybrid taxon) and align to genus,"first word (""genus"")",exact,"APC accepted taxon concepts, other APC taxon concepts, APNI",genus,"Find strings that indicate a name that is a hybrid between two taxa. Such names, unless documented in APC (i.e. matches 6, 7 above) can only be aligned to genus."
 match_11b,Detect ` x ` (hybrid taxon) and align to genus,"first word (""genus"")",fuzzy,APC accepted taxon concepts,genus,
 match_11c,Detect ` x ` (hybrid taxon) and align to genus,"first word (""genus"")",fuzzy,other APC taxon concepts,genus,
 match_11d,Detect ` x ` (hybrid taxon) and align to genus,"first word (""genus"")",fuzzy,APNI,genus,
-match_11e,"Detect ` x ` (hybrid taxon), but fail to align to genus",NA,no match,NA,genus,
+match_11e,"Detect ` x ` (hybrid taxon), but fail to align to genus",NA,no match,NA,NA,
 match_12a,"Detect canonical names, by checking first three words in string",trinomial (from stripped_name_2),exact,APC accepted taxon concepts,species/infraspecific,"Check if the first three words in the name string match with a taxon name, allowing notes to be discarded. Also useful for aligning phrase names."
 match_12b,"Detect canonical names, by checking first three words in string",trinomial (from stripped_name_2),exact,other APC taxon concepts,species/infraspecific,
 match_13a,"Detect canonical names, by checking first three words in string",trinomial (from stripped_name_2),fuzzy,APC accepted taxon concepts,species/infraspecific,

inst/extdata/update_taxonomy_documentation.csv

@@ -1,14 +1,11 @@
-function name,categories of aligned names processed:,,,,columns filled in,,
-,taxonomic dataset,taxon rank,updates to aligned name,format of `suggested_name`,accepted name (& taxon_ID),genus (& taxon_ID_genus),scientific_name_ID
+,categories of aligned names processed:,,,,columns filled in,,
+function name,taxonomic dataset,taxon rank,updates to aligned name,format of `suggested_name`,accepted name (& taxon_ID),genus (& taxon_ID_genus),scientific_name_ID
 update_taxonomy_APC_genus,APC,genus,to APC accepted genus,`genus sp. [notes]` *,no,yes,no
 update_taxonomy_APNI_genus,APNI,genus,none,`genus sp. [notes]`,no,no,no
 update_taxonomy_APC_family,APC,family,none,`family sp. [notes]`,no,no,no
 update_taxonomy_APC_species_and_infraspecific_taxa,APC,species & infraspecific,,APC accepted species** name,yes,yes,yes
-"taxonomic_splits = ""most_likely_species""",,,to APC accepted taxon concept,most likely APC accepted species** name [alternative possible names],yes,yes,yes
-"taxonomic_splits = ""return_all""",,,to APC accepted taxon concept,all possible APC accepted species** name (extra rows added),yes,yes,yes
-"taxonomic_splits = ""collapse_to_higher_taxon""",,,collapsed to APC accepted genus,`genus sp.` [collapsed names],no,yes,no
+" -- taxonomic_splits = ""most_likely_species""",,,to APC accepted taxon concept,most likely APC accepted species** name [alternative possible names],yes,yes,yes
+" -- taxonomic_splits = ""return_all""",,,to APC accepted taxon concept,all possible APC accepted species** name (extra rows added),yes,yes,yes
+" -- taxonomic_splits = ""collapse_to_higher_taxon""",,,collapsed to APC accepted genus,`genus sp.` [collapsed names],no,yes,no
 update_taxonomy_APNI_species_and_infraspecific_taxa,APNI,species & infraspecific,none to species name; genus to APC accepted genus if possible,APNI listed species** name*,no,sometimes,yes
-not required,(not aligned),(not aligned),none,original name,no,no,no
-,,,,,,,
-* genus updated to APC accepted genus if possible,,,,,,,
-** species or infraspecific taxon name,,,,,,,
+(names not aligned),(not aligned),(not aligned),none,original name,no,no,no