topComp: Compares toponyms in a polygon and the remainder of countries

In toponym: Analyze and Visualize Toponyms

Compares toponyms in a polygon and the remainder of countries

Description

This function retrieves the most frequent toponym substrings in a given polygon relative to country frequencies.

Usage

topComp(countries, len, rat, polygon, ...)

Arguments

countries	character string vector with country designations (names or ISO-codes).
len	numeric. The length of the substring within toponyms.
rat	numeric. The cut-off ratio (a number between 0.0 and 1 for freq.type = "abs") of how many occurrences of a toponym string need to be in the polygon relative to the rest of the country (or countries).
polygon	data frame. Defines the polygon for comparison with the remainder of a country (or countries).
...	Additional parameters: type character string. Either by default "$" (ending) or "^" (beginning). feat.class character string vector. Selects data only of those feature classes (check http://download.geonames.org/export/dump/readme.txt for the list of all feature classes). By default, it is P. freq.type character string. If "abs" (the default), ratios of absolute frequencies inside the polygon and in the countries as a whole are computed. If "rel", ratios of relative frequencies inside the polygon and outside the polygon will be computed. limit numeric. The number of the most frequent toponym substrings which will be tested. toponym_path character string. Path name for downloaded data.

Details

This function sorts the toponym substrings in the given countries by frequency. It then tests which ones lie in the given polygon and prints out a data frame with those that match the ratio criterion. Parameter countries accepts all designations found in country(query = "country table"). Polygons passed through the polygon parameter need to intersect or be within a country specified by the countries parameter. Parameter toponym_path accepts "pkgdir" for the package directory or a full, alternative path. With toponymOptions(), users can specify the path for toponym and map data downloaded by this package across sessions. See help(toponymOptions). The data used is downloaded by getData() and is accessible on the GeoNames download server.

Value

A data frame printed out and saved in the global environment. It shows toponym substrings surpassing the ratio, the ratio and the frequency.

Examples

## We recommend setting a persistent path for downloaded data by using toponymOptions()
## Users can always set the path manually when a function is used
## For illustration purposes,
## 1. the path is manually set each time
## 2. and wrapped in donttest because data will be downloaded in the following examples:

topComp("GB",
  limit = 100,
  len = 4,
  rat = .7,
  polygon = toponym::danelaw_polygon,
  toponym_path = tempdir()
)
## returns a data frame of the top 100 four-character-long endings in the United Kingdom
## if more than 70% of them belong to the polygon
## corresponding to the Danelaw area.



topComp("GB",
  limit = 100,
  len = 3,
  rat = 1,
  polygon = toponym::danelaw_polygon,
  freq.type = "rel",
  toponym_path = tempdir()
)
## returns a data frame of the top 100 three-character-long endings in the United Kingdom
## if they have greater relative frequencies within Danelaw than outside of Danelaw.



topComp(c("BE", "NL"),
  limit = 50,
  len = 3,
  rat = .8,
  polygon = toponym::flanders_polygon,
  toponym_path = tempdir()
)
## returns a data frame of the top 50 three-character-long endings
## in Belgium and Netherlands viewed as a unit if more than 80% of them belong to the polygon
## corresponding to Flanders.

toponym documentation built on April 13, 2026, 5:06 p.m.