Package 'geotools' reference manual

Title:	Support for Geography Packages
Description:	Support functions for the GeoVerse packages.
Authors:	Pascal Burkhard [aut, cre] (ORCID: <https://orcid.org/0009-0001-5504-5084>)
Maintainer:	Pascal Burkhard <[email protected]>
License:	MIT + file LICENSE
Version:	1.1.0.9000
Built:	2026-10-30 21:22:11 UTC
Source:	https://github.com/Nenuial/geotools

Provide custom countrycode function

Description

Provide custom countrycode function

Usage

gtl_admin_code(..., country = c("China", "Switzerland", "Russia"))
gtl_admin_code(..., country = c("China", "Switzerland", "Russia"))

Arguments

...

Arguments passed on to countrycode::countrycode

sourcevar

Vector which contains the codes or country names to be converted (character or factor)

origin

A string which identifies the coding scheme of origin (e.g., "iso3c"). See codelist for a list of available codes.

destination

A string or vector of strings which identify the coding scheme of destination (e.g., "iso3c" or c("cowc", "iso3c")). See codelist for a list of available codes. When users supply a vector of destination codes, they are used sequentially to fill in missing values not covered by the previous destination code in the vector.

warn

Prints unique elements from sourcevar for which no match was found

nomatch

When countrycode fails to find a match for the code of origin, it fills-in the destination vector with nomatch. The default behavior is to fill non-matching codes with NA. If nomatch = NULL, countrycode tries to use the origin vector to fill-in missing values in the destination vector. nomatch must be either NULL, of length 1, or of the same length as sourcevar.

custom_dict

A data frame which supplies a new dictionary to replace the built-in country code dictionary. Each column contains a different code and must include no duplicates. The data frame format should resemble codelist. Users can pre-assign attributes to this custom dictionary to affect behavior (see Examples section):

"origin.regex" attribute: a character vector with the names of columns containing regular expressions.
"origin.valid" attribute: a character vector with the names of columns that are accepted as valid origin codes.

custom_match

A named vector which supplies custom origin and destination matches that will supercede any matching default result. The name of each element will be used as the origin code, and the value of each element will be used as the destination code. Values supplied via custom_match supersede ambiguous or duplicate matches and will not trigger the corresponding ambiguity/duplicate-match warnings for those values.

origin_regex

NULL or Logical: When using a custom dictionary, if TRUE then the origin codes will be matched as regex, if FALSE they will be matched exactly. When NULL, countrycode will behave as TRUE if the origin name is in the custom_dictionary's origin_regex attribute, and FALSE otherwise. See examples section below.

country

Select the custom dictionary, currently one of China, Switzerland or Russia

Value

A vector with the desired output

Examples

tibble::tribble(
  ~canton, ~population,
  "Neuchâtel", 176496,
  "Vaud", 805098,
  "Genève", 504128
) -> population

population |>
  dplyr::mutate(iso = gtl_admin_code(
    sourcevar = canton,
    origin = "canton.name.regex",
    destination = "iso",
    origin_regex = TRUE,
    country = "Switzerland"
  ))
tibble::tribble(
  ~canton, ~population,
  "Neuchâtel", 176496,
  "Vaud", 805098,
  "Genève", 504128
) -> population

population |>
  dplyr::mutate(iso = gtl_admin_code(
    sourcevar = canton,
    origin = "canton.name.regex",
    destination = "iso",
    origin_regex = TRUE,
    country = "Switzerland"
  ))

Check API connexion

Description

Check API connexion

Usage

gtl_chk_api_call(call)
gtl_chk_api_call(call)

Arguments

call

An API url

Value

Returns an error if the API call fails

Check IDB API key

Description

Function to check if the IDB API key is correctly set.

Usage

gtl_chk_idb_api_key()
gtl_chk_idb_api_key()

Value

Returns an error if the IDB API key is not properly set

Examples


# Not run: fails if the IDB API key isn't set

gtl_chk_idb_api_key()

# Not run: fails if the IDB API key isn't set

gtl_chk_idb_api_key()

Check NOAA API key

Description

Function to check if the NOAA API key is correctly set.

Usage

gtl_chk_rnoaa_api_key()
gtl_chk_rnoaa_api_key()

Value

Returns an error if the NOAA API key is not properly set

Examples


# Not run: fails if the NOAA API key isn't set

gtl_chk_rnoaa_api_key()

# Not run: fails if the NOAA API key isn't set

gtl_chk_rnoaa_api_key()

NOAA country list

Description

This function returns a list of World Bank countries for a choice selector in a Shiny app.

Usage

gtl_country_list_noaa()
gtl_country_list_noaa()

Examples


# Not run: need the NCDC city database
gtl_country_list_noaa()

# Not run: need the NCDC city database
gtl_country_list_noaa()

World Bank country list

Description

This function returns a list of World Bank countries for a choice selector in a Shiny app.

Usage

gtl_country_list_wb()
gtl_country_list_wb()

Examples

gtl_country_list_wb()

gtl_country_list_wb()

Get a defined CRS definition for a given code

Description

A function that returns the corresponding CRS for different codes.

Usage

gtl_crs_proj(code)
gtl_crs_proj(code)

Arguments

code

A string with the CRS identifier

Details

The current list of available codes is:

eqearth
equirec
gallpeters
goode
hobodyer
mercator
robinson
wintri

Value

A CRS object

Examples

gtl_crs_proj("eqearth")

gtl_crs_proj("robinson")

gtl_crs_proj("eqearth")

gtl_crs_proj("robinson")

Get a defined proj4 string for a given country

Description

A function that returns an ideal CRS for a given country.

Usage

gtl_crs_regional(country)
gtl_crs_regional(country)

Arguments

country

A string with the country name

Details

The current list of possible countries:

Russia

Value

A CRS object

Examples

gtl_crs_regional("Russia")

gtl_crs_regional("Russia")

Download JSON response from API

Description

Download JSON response from API

Usage

gtl_dwnl_api_json(call)
gtl_dwnl_api_json(call)

Arguments

call

An API url

Value

JSON body

Examples

gtl_dwnl_api_json("https://dummyjson.com/products/1")

gtl_dwnl_api_json("https://dummyjson.com/products/1")

French typography

Description

Puts a non-breaking space (U+00A0) before ; : ! ? » and %, and after «, in place of a plain space, so that these signs never start a line. The non-breaking space is in Latin-1, so every pdf device can draw it. gtl_translate_enfr() applies it to the French strings. Anything but text is returned unchanged.

Usage

gtl_fr_typo(x)
gtl_fr_typo(x)

Arguments

x

A character vector of French text

Value

The text with non-breaking spaces

Examples

gtl_fr_typo("Source : OFS ; Donn\u00e9es : 2024, soit 12 %")
gtl_fr_typo("Source : OFS ; Donn\u00e9es : 2024, soit 12 %")

Format full date

Description

This function formats a date in a long format (see return value). The format takes the current language setting into account (see gtl_opt_set_i18n()).

Usage

gtl_full_date(date)
gtl_full_date(date)

Arguments

date

A date in YYYY-MM-DD format

Value

A formated ⁠day month year⁠ (%d %B %Y) date

Examples

# Set en english locale
gtl_opt_set_i18n("en_US")
gtl_full_date("2020-02-20")

# Set a french locale
gtl_opt_set_i18n("fr_FR")
gtl_full_date("2020-02-20")

# Set en english locale
gtl_opt_set_i18n("en_US")
gtl_full_date("2020-02-20")

# Set a french locale
gtl_opt_set_i18n("fr_FR")
gtl_full_date("2020-02-20")

World Tissot Matrix

Description

World Tissot Matrix

Usage

gtl_gis_tissot_indicatrix()
gtl_gis_tissot_indicatrix()

Value

A simple feature layer

Examples

gtl_gis_tissot_indicatrix()
gtl_gis_tissot_indicatrix()

Return a list of color breaks for Higchart maps

Description

Return a list of color breaks for Higchart maps

Usage

gtl_hc_color_axis(breaks, palette)
gtl_hc_color_axis(breaks, palette)

Arguments

breaks

The data with the breaks (using chopped data with santoku::santoku)

palette

A color palette that can take a numeric argument

Value

A list of lists to use in colorAxis' dataClasses argument

Examples

data <- seq(1, 20)
data_cut <- santoku::chop(data, breaks = c(5, 10, 15))
gtl_hc_color_axis(data_cut, rainbow)
data <- seq(1, 20)
data_cut <- santoku::chop(data, breaks = c(5, 10, 15))
gtl_hc_color_axis(data_cut, rainbow)

Return a list of color breaks for Higchart maps

Description

Return a list of color breaks for Higchart maps

Usage

gtl_hc_discrete_color_axis(breaks, palette)
gtl_hc_discrete_color_axis(breaks, palette)

Arguments

breaks

The data with the breaks (factors !)

palette

A color palette that can take a numeric argument

Value

A list of lists to use in colorAxis' dataClasses argument

mapView options for highcharter objects

Description

mapView options for highcharter objects

Usage

gtl_hc_map_view(hc, ...)
gtl_hc_map_view(hc, ...)

Arguments

hc

A highchart htmlwidget object.

...

Options as defined in https://api.highcharts.com/highmaps/mapView.

Provide HMD country codes

Description

This function returns a dataframe with the 47 countries for which the Human Mortality Database provides data. For each country there is a name and a code.

Usage

gtl_hmd_codes()
gtl_hmd_codes()

Value

A dataframe with 2 columns and 47 rows

Examples

gtl_hmd_codes()

gtl_hmd_codes()

Determine the Köppen climate based on temperature and precipitation

Description

The Köppen-Geiger classification as in Beck et al. (2018, 2023) after Peel et al. (2007), the same as the GeoResources climate diagrams: B (arid) is tested first, summer is the warmer half-year (April–September or October–March), and C and D are separated at 0 °C (cd = -3 for Köppen's original -3 °C).

Usage

gtl_koppen_code(temp, prec, lat = NULL, cd = 0)
gtl_koppen_code(temp, prec, lat = NULL, cd = 0)

Arguments

temp

A vector with temperatures in degree Celsius for each month

prec

A vector with precipitations in millimeters for each month

lat

Unused: the summer half-year is found from the temperatures. Kept for compatibility.

cd

The temperature of the coldest month separating C from D climates

Value

A string with the Köppen climate determination

Examples

# Based on climate data for Geneva
gtl_koppen_code(
  temp = c(2.1, 3, 6.8, 10.4, 14.8, 18.4, 20.5, 20.2, 15.8, 11.5, 6, 2.7),
  prec = c(70.8, 60.6, 56.9, 69, 75.7, 78.8, 83.2, 81.4, 94.9, 97.6, 90.3, 85.2)
)

# Based on climate data for Geneva
gtl_koppen_code(
  temp = c(2.1, 3, 6.8, 10.4, 14.8, 18.4, 20.5, 20.2, 15.8, 11.5, 6, 2.7),
  prec = c(70.8, 60.6, 56.9, 69, 75.7, 78.8, 83.2, 81.4, 94.9, 97.6, 90.3, 85.2)
)

Format numbers in the current language

Description

Label functions for ggplot2 scales (or for any vector of numbers) that follow the current language setting (see gtl_opt_set_i18n()): an apostrophe between thousands in every language (60'000), a decimal comma in French and German (2,5) and a space before the percent sign in French and German (2,5 %). The language is read when the numbers are formatted.

Usage

gtl_label_number(...)

gtl_label_percent(...)
gtl_label_number(...)

gtl_label_percent(...)

Arguments

...

Arguments passed on to scales::number() or scales::percent() (accuracy, scale, suffix...)

Value

A function that formats numbers

Examples

gtl_opt_set_i18n("fr_CH")
gtl_label_number()(c(60000, 2.5))
gtl_label_percent(accuracy = 0.1)(0.025)

gtl_opt_set_i18n("en_US")
gtl_label_number()(c(60000, 2.5))
gtl_label_percent(accuracy = 0.1)(0.025)
gtl_opt_set_i18n("fr_CH")
gtl_label_number()(c(60000, 2.5))
gtl_label_percent(accuracy = 0.1)(0.025)

gtl_opt_set_i18n("en_US")
gtl_label_number()(c(60000, 2.5))
gtl_label_percent(accuracy = 0.1)(0.025)

Return long language name

Description

Function to get the current language setting in full.

Usage

gtl_opt_long_language()
gtl_opt_long_language()

Value

A string with the language name (lowercase)

Examples

# With a french locale
gtl_opt_set_i18n("fr_CH")
gtl_opt_long_language()

# With an english locale
gtl_opt_set_i18n("en_US")
gtl_opt_long_language()
# With a french locale
gtl_opt_set_i18n("fr_CH")
gtl_opt_long_language()

# With an english locale
gtl_opt_set_i18n("en_US")
gtl_opt_long_language()

Set language and country settings

Description

This function allows setting the default language and country settings using a valid i18n code.

Usage

gtl_opt_set_i18n(code)
gtl_opt_set_i18n(code)

Arguments

code

A valid i18n code (example: fr_CH)

Examples

# Swiss french locale
gtl_opt_set_i18n("fr_CH")
gtl_options("language")
gtl_options("country")

# American english locale
gtl_opt_set_i18n("en_US")
gtl_options("language")
gtl_options("country")
# Swiss french locale
gtl_opt_set_i18n("fr_CH")
gtl_options("language")
gtl_options("country")

# American english locale
gtl_opt_set_i18n("en_US")
gtl_options("language")
gtl_options("country")

Return short language code

Description

Function that returns the short language code currently set if it is in the list of valid options. If the current language isn't in the list of valid options, the first element of the valid elements is returned.

Usage

gtl_opt_short_language(valid = c("en", "fr"))
gtl_opt_short_language(valid = c("en", "fr"))

Arguments

valid

A vector with valid language options

Value

A string

Examples

gtl_opt_set_i18n("fr_CH")
gtl_opt_short_language(valid = c("de", "fr"))

# With the current local not among the valid options
gtl_opt_set_i18n("en_US")
gtl_opt_short_language(valid = c("de", "fr"))
gtl_opt_set_i18n("fr_CH")
gtl_opt_short_language(valid = c("de", "fr"))

# With the current local not among the valid options
gtl_opt_set_i18n("en_US")
gtl_opt_short_language(valid = c("de", "fr"))

Set or get options for my package

Description

Set or get options for my package

Usage

gtl_options(...)
gtl_options(...)

Arguments

...

Option names to retrieve option values or ⁠[key]=[value]⁠ pairs to set options.

Supported options

The following options are supported

language: The default language
country: The default country setting
theme: The default ggplot theme
mode: The default ggplot mode
opacity: The default opacity

Examples

# Retrieve default options
gtl_options("language")
gtl_options("plot_standard_width")

# Change a setting and retrieve it
gtl_options(plot_standard_width = 25)
gtl_options("plot_standard_width")
# Retrieve default options
gtl_options("language")
gtl_options("plot_standard_width")

# Change a setting and retrieve it
gtl_options(plot_standard_width = 25)
gtl_options("plot_standard_width")

Reformat santoku chop dash labels

Description

This function can be used to reformat the levels produced by the santoku::lbl_dash() function.

Usage

gtl_relabel_dash(x)
gtl_relabel_dash(x)

Arguments

x

A string vector of labels

Value

A string vector with clean labels

Examples

data <- seq(1, 20)
data_cut <- santoku::chop(data,
  breaks = c(5, 7, 13),
  labels = santoku::lbl_dash(),
  extend = TRUE, drop = FALSE
)
forcats::fct_relabel(data_cut, gtl_relabel_dash)

data <- seq(1, 20)
data_cut <- santoku::chop(data,
  breaks = c(5, 7, 13),
  labels = santoku::lbl_dash(),
  extend = TRUE, drop = FALSE
)
forcats::fct_relabel(data_cut, gtl_relabel_dash)

Format numbers using scientific notation for html

Description

Format numbers using scientific notation for html

Usage

gtl_sci_10_html(x)
gtl_sci_10_html(x)

Arguments

x

Number to format

Value

A formatted expression

Examples

gtl_sci_10_html(10e6)
gtl_sci_10_html(10e9)

gtl_sci_10_html(10e6)
gtl_sci_10_html(10e9)

Get Swiss canton abbreviations

Description

This is a shortcut for Swiss canton abbreviation based on the canton name.

Usage

gtl_swiss_canton_abbr(canton_name)
gtl_swiss_canton_abbr(canton_name)

Arguments

canton_name

A vector of Swiss canton names

Value

A vector of Swiss canton abbreviations

Examples

gtl_swiss_canton_abbr(c("Jura", "Genève", "Neuchâtel"))

gtl_swiss_canton_abbr(c("Jura", "Genève", "Neuchâtel"))

Get Swiss canton FSO ids

Description

This is a shortcut for Swiss canton codes based on the canton name.

Usage

gtl_swiss_canton_id(canton_name)
gtl_swiss_canton_id(canton_name)

Arguments

canton_name

A vector of Swiss canton names

Value

A vector of Swiss canton FSO ids

Examples

gtl_swiss_canton_id(c("Jura", "Genève", "Neuchâtel"))

gtl_swiss_canton_id(c("Jura", "Genève", "Neuchâtel"))

Translate function

Description

Translate function

Usage

gtl_translate_enfr(english, french, german = english)
gtl_translate_enfr(english, french, german = english)

Arguments

english

English string

french

French string

german

German string, English when not given

A function that returns the english, french or german argument depending on the current language setting. Any other language gets the english one.

Value

String depending on package language option

Examples

gtl_opt_set_i18n("fr_CH") # Set language to french
gtl_translate_enfr("Hello world!", "Bonjour le monde !")

gtl_opt_set_i18n("de_CH") # Set language to german
gtl_translate_enfr("Hello world!", "Bonjour le monde !", "Hallo Welt!")

gtl_opt_set_i18n("en_US") # Set language to english
gtl_translate_enfr("Hello world!", "Bonjour le monde !")
gtl_opt_set_i18n("fr_CH") # Set language to french
gtl_translate_enfr("Hello world!", "Bonjour le monde !")

gtl_opt_set_i18n("de_CH") # Set language to german
gtl_translate_enfr("Hello world!", "Bonjour le monde !", "Hallo Welt!")

gtl_opt_set_i18n("en_US") # Set language to english
gtl_translate_enfr("Hello world!", "Bonjour le monde !")

Creates translation function for named string list

Description

Creates translation function for named string list

Usage

gtl_translator(dictionary)
gtl_translator(dictionary)

Arguments

dictionary

A list of translations

Value

A function that translates

Examples

translations <- list(
  "maison" = "house",
  "chapeau" = "hat",
  "chat" = "cat"
)

translate_to_english <- gtl_translator(translations)
translate_to_english("maison")
translate_to_english("chat")

translations <- list(
  "maison" = "house",
  "chapeau" = "hat",
  "chat" = "cat"
)

translate_to_english <- gtl_translator(translations)
translate_to_english("maison")
translate_to_english("chat")

Package 'geotools'

Help Index

Provide custom countrycode function

Description

Usage

Arguments

Value

Examples

Check API connexion

Description

Usage

Arguments

Value

Check IDB API key

Description

Usage

Value

See Also

Examples

Check NOAA API key

Description

Usage

Value

Examples

NOAA country list

Description

Usage

Examples

World Bank country list

Description

Usage

Examples

Get a defined CRS definition for a given code

Description

Usage

Arguments

Details

Value

Examples

Get a defined proj4 string for a given country

Description

Usage

Arguments

Details

Value

Examples

Download JSON response from API

Description

Usage

Arguments

Value

Examples

French typography

Description

Usage

Arguments

Value

Examples

Format full date

Description

Usage

Arguments

Value

See Also

Examples

World Tissot Matrix

Description

Usage

Value

Examples

Return a list of color breaks for Higchart maps

Description

Usage

Arguments

Value

Examples

Return a list of color breaks for Higchart maps

Description

Usage

Arguments