Package 'GNRS'

Title: Access the 'Geographic Name Resolution Service'
Description: Provides tools for interacting with the 'geographic name resolution service' ('GNRS') API <https://github.com/ojalaquellueva/gnrs> and associated functionality. The 'GNRS' is a batch application for resolving & standardizing political division names against standard name in the geonames database <http://www.geonames.org/>. The 'GNRS' resolves political division names at three levels: country, state/province and county/parish. Resolution is performed in a series of steps, beginning with direct matching to standard names, followed by direct matching to alternate names in different languages, followed by direct matching to standard codes (such as ISO and FIPS codes). If direct matching fails, the 'GNRS' attempts to match to standard and then alternate names using fuzzy matching, but does not perform fuzzing matching of political division codes. The 'GNRS' works down the political division hierarchy, stopping at the current level if all matches fail. In other words, if a country cannot be matched, the 'GNRS' does not attempt to match state or county.
Authors: Brad Boyle [aut], Brian Maitner [aut, cre]
Maintainer: Brian Maitner <[email protected]>
License: MIT + file LICENSE
Version: 0.3.4
Built: 2025-02-10 03:29:17 UTC
Source: https://github.com/cran/GNRS

Help Index


Standardize political division names

Description

GNRS returns standardized political division names (according to geonames.org).

Usage

GNRS(political_division_dataframe, batches = NULL, ...)

Arguments

political_division_dataframe

A properly formatted dataframe, see http://bien.nceas.ucsb.edu/bien/tools/gnrs/gnrs-api/

batches

NULL or Numeric. Optional number of batches to divide the request into for parallel processing.

...

Additional parameters passed to internal functions

Value

Dataframe containing GNRS results.

Note

To create an empty and properly formatted dataframe, use GNRS_template()

The fields the GNRS takes as input are titled "country", "state_province", and "county_parish" for simplicity, but these field actually refer to 0th-, 1st-, and 2nd-order political division, respectively. In the case of some exceptions (e.g. the UK) this distinction becomes important (e.g. Ireland is a 1st-order political division and should be treated as a "state_province" and cannot be matched as a country.)

Examples

## Not run: 
results <- GNRS(political_division_dataframe = gnrs_testfile)
  


## End(Not run)

Get acknowledgment information

Description

Return information needed to acknowledge GNRS contributors

Usage

GNRS_acknowledgments(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing acknowledgments

Examples

## Not run: 
GNRS_acknowledgments_metadata <- GNRS_acknowledgments()

## End(Not run)

Get citation information

Description

Return information needed to cite the GNRS

Usage

GNRS_citations(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing bibtex-formatted citation information

Examples

## Not run: 
GNRS_citations_metadata <- GNRS_citations()

## End(Not run)

Get Data Dictionary

Description

Return GNRS Data Dictionary

Usage

GNRS_data_dictionary(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing GNRS Data Dictionary

Examples

## Not run: 
GNRS_dictionary <- GNRS_data_dictionary()

## End(Not run)

Get metadata on counties

Description

Return metadata about counties, parishes, etc. used by the GNRS

Usage

GNRS_get_counties(state_province_id = "", ...)

Arguments

state_province_id

A GNRS state_id, or a vector of state_ids.

...

Additional parameters passed to internal functions

Value

Dataframe containing information on counties/parishes (e.g. iso code, fips code, continent, standardized name)

Examples

## Not run: 
states <- GNRS_get_states()
us_counties <- GNRS_get_counties(
state_province_id = states$state_province_id[
which(states$country_iso == "US")])

## End(Not run)

Get metadata on countries

Description

Return metadata about countries used by the GNRS

Usage

GNRS_get_countries(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing information on countries (e.g. iso code, fips code, continent, standardized name)

Examples

## Not run: 
countries <- GNRS_get_countries()

## End(Not run)

Get metadata on states

Description

Return metadata about states used by the GNRS

Usage

GNRS_get_states(country_id = "", ...)

Arguments

country_id

A GNRS country_id, or a vector of country_ids. If empty, will return metadata for all countries.

...

Additional parameters passed to internal functions

Value

Dataframe containing information on states/provinces (e.g. iso code, fips code, continent, standardized name)

Examples

## Not run: 
states <- GNRS_get_states()

## End(Not run)

Get GNRS metadata

Description

Returns metadata on GNRS including version and citation information

Usage

GNRS_metadata(bibtex_file = NULL, ...)

Arguments

bibtex_file

Optional output file for writing bibtex citations.

...

Additional parameters passed to internal functions

Value

List containing: (1) bibtex-formatted citation information, (2) information about GNRS data sources, (3) GNRS version information, and (4) information that can be used in an acknowledgments statement..

Note

This function provides citation information in bibtex format that can be used with reference manager software (e.g. Paperpile, Zotero). Please remember to cite both the sources and the GNRS, as the GNRS couldn't exist without these sources!

This function is a wrapper that returns the output of the functions GNRS_citations, GNRS_sources, GNRS_version, and GNRS_acknowledgments.

Examples

## Not run: 
metadata <- GNRS_metadata()

## End(Not run)

Get metadata on current GNRS sources

Description

Return metadata about the current GNRS version

Usage

GNRS_sources(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing current GNRS sources.

Examples

## Not run: 
GNRS_sources_metadata <- GNRS_sources()

## End(Not run)

Standardize political division names

Description

GNRS_super_simple returns standardized political division names (according to geonames.org).

Usage

GNRS_super_simple(
  country = NULL,
  state_province = NULL,
  county_parish = NULL,
  user_id = NULL,
  ...
)

Arguments

country

A single country or a vector of countries. If a vector, length must equal length of species vector.

state_province

A single state/province or a vector of states. If a vector, length must equal length of species vector.

county_parish

A single county/parish or a vector of counties. If a vector, length must equal length of species vector.

user_id

A single identifier or vector of identifiers. This field is assigned if not provided and is used to maintain record order.

...

Additional parameters passed to internal functions

Value

Dataframe containing GNRS results.

Note

The fields the GNRS takes as input are titled "country", "state_province", and "county_parish" for simplicity, but these field actually refer to 0th-, 1st-, and 2nd-order political division, respectively. In the case of some exceptions (e.g. the UK) this distinction becomes important (e.g. Ireland is a 1st-order political division and should be treated as a "state_province" and cannot be matched as a country.)

Examples

## Not run: 

 results <- GNRS_super_simple(country = "United States of America")
 results <- GNRS_super_simple(
             country = "United States",
             state_province = "Arizona",
             county_parish = "Pima County")


## End(Not run)

Make a template for a GNRS query

Description

GNRS_template builds a template that can be populated to submit a GNRS query.

Usage

GNRS_template(nrow = 1)

Arguments

nrow

The number of rows to include in the template

Value

Template data.frame that can be populated and then used in GNRS queries.

Examples

## Not run: 

template<-GNRS_template(nrow = 2)
template$country<-c("United Stapes","Mexico")
template$state_province<-c("Arizona","Sinalo")
GNRS(political_division_dataframe = template)  


## End(Not run)

Names of 21 political divisions

Description

A dataset containing the country, state/province, and country/parish names of 21 political divisions.

Usage

gnrs_testfile

Format

A data frame with 21 rows and 4 variables:

user_id

Unique integer identifying each row

country

Country names, possibly containing errors

state_province

State names, possibly containing errors

county_parish

County names, possibly containing errors

...

Source

https://github.com/ojalaquellueva/gnrs


Get metadata on current GNRS version

Description

Return metadata about the current GNRS version

Usage

GNRS_version(...)

Arguments

...

Additional parameters passed to internal functions

Value

Dataframe containing current GNRS version number, build date, and code version.

Examples

## Not run: 
GNRS_version_metadata <- GNRS_version()

## End(Not run)