Standardize parameters across functions

[sckott]

the same types of inputs to functions are sometimes specified with different function param names. we should standarize them where possible. here's the candidates:

• scientific names (aka taxonomic)
• common names (aka vernacular)
• taxon ids
• ---: stays the same

new param names are:

• sci: scientific name
• com: common name
• id: name identifier
• sci_com: scientific name or common name
• sci_id: scientific name or name identifier
• For scientific name, common name, or name identifier - just leave as is

---

get functions

function	param_current	accepts	proposed	notes
get_uid	sciname	sci. or vern.	sci_com	modifier param toggles which
get_tsn	searchterm	sci. or vern.	sci_com	searchtype param toggles which
get_boldid	searchterm	sci.	sci	---
get_eolid	sciname	sci. or vern.	sci_com	---
get_tpsid	sciname	sci.	sci	---
get_gbifid	sciname	sci.	sci	---
get_tolid	sciname	sci.	sci	---
get_iucn	x	sci.	sci	---
get_natservid	query	sci. or vern.	sci_com	---
get_nbnid	name	sci. or vern.	sci_com	---
get_pow	x	sci. or vern.	sci_com	---
get_wiki	x	sci. or vern.	sci_com	---
get_wormsid	query	sci. or vern.	sci_com	---
get_ids	names	sci, or vern.	---	sci_com
get_colid	---	---	---	removed fxn for now

search functions

function	param_current	accepts	proposed	notes
bold_search	name	sci.	sci	---
col_search	name	sci.	sci	removed fxn for now
eol_search	terms	sci.	sci	---
gni_search	search_term	sci.	sci	---
nbn_search	q	sci. or vern.	sci_com	---
tp_search	name	sci.	sci	---
vascan_search	q	sci. or vern. or ids	---	leave as is
pow_search	q	sci. or vern.	sci_com	---

high level functions

function	param_current	accepts	proposed
classification	x	sci. or ids	sci_id
children	x	sci. or ids	sci_id
downstream	x	sci. or ids	sci_id
upstream	x	sci. or ids	sci_id
lowest_common	x	sci. or id	sci_id
tax_name	query	sci.	sci
tax_rank	x	sci. or ids	sci_id
id2name	x	ids	id
sci2comm	scinames	sci.	sci
comm2sci	commnames	vern.	com
synonyms	x	sci. or ids	sci_id
resolve	query	sci.	sci

downstream functions

function	param_current	accepts	proposed
downstream	x	sci. or ids	---
worms_downstream	id	ids	---
ncbi_downstream	id	ids	---
itis_downstream	tsns	ids	id
gbif_downstream	key	ids	id
bold_downstream	id	ids	---

resolve functions

function	param_current	accepts	proposed
resolve	query	sci.	sci
gnr_resolve	names	sci.	sci
iplant_resolve	query	sci.	sci
tnrs	query	sci.	sci

---

• in one release, add params, warn on usage of old
• in next release, remove old params

[maelle]

I like the idea but wonder whether something like sci_ver_id could be annoying since it is long.

Some naive thoughts.

An alternative would be to have as many parameters as possible input: sci for sci names and ver for vernacular names within the same function (and you could only provide one of them, Not both a value for sci and a value for ver within a function call). Then the first argument could be called search and would accept all the names the function accepts, but its name wouldn't provide clarity.

Are there cases where people would feed a vector of both vernacular and scientific names to the function?

In a case where more than 50% of results are NA could the function message "many queries had no results, make sure you used the right input, refer to blabla vignette" 🤔

Your case reminds me a bit of https://r-hub.github.io/pkgsearch/reference/advanced_search.html where the user enters either named terms or a query string.

[sckott]

thanks @maelle !

You're right that sci_ver_id is quite long. Maybe just going with name for scientific or vernacular name and id when an identifier is expected, but if name or id can be given, then you'd need a 3rd option (i guess just x?)

Are there cases where people would feed a vector of both vernacular and scientific names to the function?

No, only one or the other.

In a case where more than 50% of results are NA

It could, but the search results are beyond my control - and I don't want to throw more messages, though that's a good idea to document more why users get results they get from different data sources.

Thanks for link to rhub fxn. I can see now that makes sense in that context.

[maelle]

but if name or id can be given, then you'd need a 3rd option (i guess just x?)

I don't understand this, can you explain to me what the input is in this case?

[sckott]

some functions can accept a taxonomic id or name - so name wouldn't be appropriate for that parameter and neither would id