getAdmin: Get Administrative Subdivisions from a Gazetteer

In LimaRAF/plantR: Managing Species Records from Biological Collections

Get Administrative Subdivisions from a Gazetteer

Description

Obtain the names of the administrative subdivisions for a given locality from a gazetteer. Users can use the default plantR gazetteer or provide one to the function.

Usage

getAdmin(
  x,
  gazet = "plantR",
  str.name = "loc.correct",
  gazet.names = c("loc.correct", "NAME_0", "NAME_1", "NAME_2", "NAME_3", "source")
)

Arguments

x	a vector or a dataframe containing the plantR search string in the proper format (lowercase, separated by an underline).
gazet	a data frame containing the gazetteer with the list of names and locality subdivisions. The default is "plantR", the internal plantR gazetteer (focused on Latin America and the Caribbean).
str.name	a character corresponding to the columns name containing the locality search string to match the input dataframe and the gazetteer. Defaults to 'loc.correct'.
gazet.names	a vector of the column names containing the locality search string in the gazetteer, and the administrative subdivisions, in that order. If available, the source of the administrative information can be provided as the last name of this vector. Defaults to columns names of the plantR gazetteer: 'loc.correct', 'NAME_0', 'NAME_1', 'NAME_2', 'NAME_3 and 'source'.

Details

Although the internal gazetteer used in plantR can handle common notation variants and typos in locality names (see function getLoc), the function getAdmin assumes that these issues were already solved. Otherwise, the function may not find the information required. See Examples below.

The retrieval of information depends on the completeness of the gazetteer itself. So, even if all variants and typos were solved for an existing locality, if the gazetteer does not include a specific locality, the query will return NAs. The gazetteer is permanently being improved. If you found an error or want to contribute with region-specific gazetteers, please send an email to [e-mail].

In Brazil, NAME_0, NAME_1, NAME_2, AND NAME_3 correspond to the Country, State, Municipality and Locality, respectively. But this may not be the case of other countries if they adopt a different nomenclature for their administrative levels.

Finally, function getAdmin currently does not return information below the municipality level, although the default plantR gazetteer can retrieve information at lower administrative levels (i.e. locality and sub-locality).

A different gazetteer than the default one can be provided using the argument gazet. If the column names of the user-provided gazetteer do not match those of the default gazetteer, the column names can be supplied using argument gazet.names.

Value

A data frame containing the input locality string in the first column, the administrative names at the resolution retrieved (four following columns) and the source of the administrative names (last column)

Author(s)

Renato A. F. de Lima

Examples

str <- c("paraguay_paraguari",
         "brazil_parana_paranagua",
         "brazil_rio janeiro_parati", # an example of a variant in the locality name
         "brazil_rio janeiro_paraty",
         "brazil_sao paulo_sao miguel arcanjo_pe carlos botelho",
         "united states_florida") # valid location but not in the default gazetteer
getAdmin(str)

LimaRAF/plantR documentation built on Jan. 1, 2023, 10:18 a.m.