Package 'geobounds'

Clear the geobounds cache directory

Description

Use this function with caution. It clears cached data and configuration by deleting the geobounds configuration directory (tools::R_user_dir("geobounds", "config")), deleting the active cache directory and clearing Sys.getenv("GEOBOUNDS_CACHE_DIR").

Usage

gb_clear_cache(config = FALSE, cached_data = TRUE, quiet = TRUE)

Arguments

config	Logical. If TRUE, delete the geobounds configuration directory.
cached_data	Logical. If TRUE, delete the active cache directory and all its contents.
quiet	Logical. If TRUE, suppress informational messages.

Details

This reset restores the cache state of a fresh geobounds installation.

Value

invisible(). This function is called for its side effects.

See Also

Cache utilities: gb_detect_cache_dir(), gb_set_cache_dir()

Examples

# Caution: this may modify your current state.

## Not run: 
my_cache <- gb_detect_cache_dir()
# Set an example cache.
ex <- file.path(tempdir(), "example", "cache")
gb_set_cache_dir(ex, quiet = TRUE)

gb_clear_cache(quiet = FALSE)

# Restore the initial cache.
gb_set_cache_dir(my_cache)
identical(my_cache, gb_detect_cache_dir())

## End(Not run)

---

Detect the geobounds cache directory

Description

Detects the active cache directory. See gb_set_cache_dir().

Usage

gb_detect_cache_dir(x = NULL)

Arguments

x

Ignored.

Value

A character vector containing the path to the active cache directory. It also appears in a clickable message. See cli::inline-markup.

See Also

Cache utilities: gb_clear_cache(), gb_set_cache_dir()

Examples

gb_detect_cache_dir()

---

Get individual country files from geoBoundaries

Description

Returns individual country files that reflect how countries represent their own boundaries, without special identification of disputed areas.

Use gb_get_world() for global composite files that standardize disputed areas and fill gaps between borders.

Attribution is required whenever these data are used.

Usage

gb_get(
  country,
  adm_lvl = "adm0",
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

Arguments

country	A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return data for all countries. See also countrycode::countrycode().
adm_lvl	ADM level. Accepted values are "all" (all available boundaries) or the ADM level ("adm0" is the country boundary, "adm1" is the first level of subnational boundaries, "adm2" is the second level and so on). Uppercase versions ("ADM1") and level numbers (1, 2, 3, 4, 5) are also accepted.
simplified	Logical. If TRUE, return simplified boundaries. The default FALSE uses the primary geoBoundaries file. See simplified boundaries at https://www.geoboundaries.org/.
release_type	One of "gbOpen", "gbHumanitarian" or "gbAuthoritative". For most users, use "gbOpen" (the default), which is CC BY 4.0 compliant and suitable for most purposes when attribution is provided. "gbHumanitarian" files are mirrored from UN OCHA and may have less open licensing. "gbAuthoritative" files are mirrored from UN SALB, verified through in-country processes and cannot be used for commercial purposes.
quiet	Logical. If TRUE, suppress informational messages.
overwrite	Logical. If TRUE, force a fresh download of the source .zip archive.
cache_dir	A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files are stored in a temporary cache directory. See base::tempdir() and the cache strategies in gb_set_cache_dir().

Details

Each individual country file is governed by the license identified in its boundary metadata. See gb_get_metadata(). Users should also cite the sources listed in the boundary metadata for each file. See Examples.

The wrappers gb_get_adm0(), gb_get_adm1(), gb_get_adm2(), gb_get_adm3(), gb_get_adm4() and gb_get_adm5() are also available for requesting a single ADM level.

Value

An sf object containing the requested boundaries.

Source

geoBoundaries API.

References

Runfola et al. (2020) geoBoundaries: A global database of political administrative boundaries. PLOS ONE 15(4), e0231866. doi:10.1371/journal.pone.0231866.

See Also

gb_get_metadata(), gb_get_max_adm_lvl().

API functions: gb_get_adm, gb_get_world()

Examples

# Map ADM2 in Sri Lanka.
sri_lanka <- gb_get(
  "Sri Lanka",
  adm_lvl = 2,
  simplified = TRUE
)

sri_lanka

library(ggplot2)
ggplot(sri_lanka) +
  geom_sf() +
  labs(caption = "Source: www.geoboundaries.org")


# Inspect boundary metadata.
library(dplyr)
gb_get_metadata(
  "Sri Lanka",
  adm_lvl = 2
) |>
  # Check the individual license.
  select(boundaryISO, boundaryType, licenseDetail, licenseSource) |>
  glimpse()

---

Get individual country files for an ADM level

Description

These functions wrap gb_get() for a single ADM level. gb_get_adm0() returns country boundaries, gb_get_adm1() returns first-level subnational boundaries (for example, states in the United States) and gb_get_adm2() returns second-level subnational boundaries (for example, counties in the United States). gb_get_adm3(), gb_get_adm4() and gb_get_adm5() return third-, fourth- and fifth-level administrative boundaries, respectively.

Not all countries have the same number of ADM levels. Use gb_get_max_adm_lvl() to check availability.

Attribution is required whenever these data are used.

Usage

gb_get_adm0(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

gb_get_adm1(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

gb_get_adm2(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

gb_get_adm3(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

gb_get_adm4(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

gb_get_adm5(
  country,
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

Arguments

country	A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return data for all countries. See also countrycode::countrycode().
simplified	Logical. If TRUE, return simplified boundaries. The default FALSE uses the primary geoBoundaries file. See simplified boundaries at https://www.geoboundaries.org/.
release_type	One of "gbOpen", "gbHumanitarian" or "gbAuthoritative". For most users, use "gbOpen" (the default), which is CC BY 4.0 compliant and suitable for most purposes when attribution is provided. "gbHumanitarian" files are mirrored from UN OCHA and may have less open licensing. "gbAuthoritative" files are mirrored from UN SALB, verified through in-country processes and cannot be used for commercial purposes.
quiet	Logical. If TRUE, suppress informational messages.
overwrite	Logical. If TRUE, force a fresh download of the source .zip archive.
cache_dir	A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files are stored in a temporary cache directory. See base::tempdir() and the cache strategies in gb_set_cache_dir().

Details

Each individual country file is governed by the license identified in its boundary metadata. See gb_get_metadata(). Users should also cite the sources listed in the boundary metadata for each file.

Value

An sf object containing the requested boundaries.

Source

geoBoundaries API.

References

Runfola et al. (2020) geoBoundaries: A global database of political administrative boundaries. PLOS ONE 15(4), e0231866. doi:10.1371/journal.pone.0231866.

See Also

gb_get_metadata(), gb_get_max_adm_lvl().

API functions: gb_get(), gb_get_world()

Examples

lev2 <- gb_get_adm2(
  c("Italia", "Suiza", "Austria"),
  simplified = TRUE
)

library(ggplot2)

ggplot(lev2) +
  geom_sf(aes(fill = shapeGroup)) +
  labs(
    title = "Second-level administrative boundaries",
    subtitle = "Selected countries",
    caption = "Source: www.geoboundaries.org"
  )

---

Get the highest available ADM level

Description

Returns a summary of selected country codes and their highest available ADM level in geoBoundaries.

Usage

gb_get_max_adm_lvl(
  country = "all",
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative")
)

Arguments

country

A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return data for all countries. See also countrycode::countrycode().

release_type

One of "gbOpen", "gbHumanitarian" or "gbAuthoritative". For most users, use "gbOpen" (the default), which is CC BY 4.0 compliant and suitable for most purposes when attribution is provided. "gbHumanitarian" files are mirrored from UN OCHA and may have less open licensing. "gbAuthoritative" files are mirrored from UN SALB, verified through in-country processes and cannot be used for commercial purposes.

Value

A tibble containing ISO 3166-1 alpha-3 country codes and their highest available ADM levels.

Source

geoBoundaries API.

See Also

Metadata functions: gb_get_metadata()

Examples

all <- gb_get_max_adm_lvl()
library(dplyr)

# Countries with only one ADM level available.
all |>
  filter(maxBoundaryType == 1)

# Countries with ADM4 available.
all |>
  filter(maxBoundaryType == 4)

---

Get boundary metadata from geoBoundaries

Description

Returns boundary metadata from the geoBoundaries API.

Usage

gb_get_metadata(
  country = "all",
  adm_lvl = "all",
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative")
)

Arguments

country	A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return data for all countries. See also countrycode::countrycode().
adm_lvl	ADM level. Accepted values are "all" (all available boundaries) or the ADM level ("adm0" is the country boundary, "adm1" is the first level of subnational boundaries, "adm2" is the second level and so on). Uppercase versions ("ADM1") and level numbers (1, 2, 3, 4, 5) are also accepted.
release_type	One of "gbOpen", "gbHumanitarian" or "gbAuthoritative". For most users, use "gbOpen" (the default), which is CC BY 4.0 compliant and suitable for most purposes when attribution is provided. "gbHumanitarian" files are mirrored from UN OCHA and may have less open licensing. "gbAuthoritative" files are mirrored from UN SALB, verified through in-country processes and cannot be used for commercial purposes.

Details

The result is a tibble with the following columns:

• boundaryID: The ID for this layer. It combines the ISO code, boundary type and a unique identifier generated from the input metadata and geometry. This only changes if the underlying data changes.

• boundaryName: The name of the country represented by the layer.

• boundaryISO: ISO 3166-1 alpha-3 code for the country.

• boundaryYearRepresented: The year or range of years in "START to END" format that the boundary layers represent.

• boundaryType: The type of boundary.

• boundaryCanonical: The canonical name of the boundary.

• boundarySource: A comma-separated list of the primary sources for the boundary.

• boundaryLicense: The original license under which the primary source released the boundary data.

• licenseDetail: Any notes regarding the license.

• licenseSource: The URL of the primary source.

• sourceDataUpdateDate: The date the source information was integrated into the geoBoundaries repository.

• buildDate: The date the source data was most recently standardized and built into a geoBoundaries release.

• Continent: The continent the country is associated with.

• UNSDG-region: The United Nations Sustainable Development Goals (SDG) region the country is associated with.

• UNSDG-subregion: The United Nations Sustainable Development Goals (SDG) subregion the country is associated with.

• worldBankIncomeGroup: The World Bank income group the country is associated with.

• admUnitCount: The number of administrative units in the file.

• meanVertices: Mean number of vertices defining the boundaries of each administrative unit in the layer.

• minVertices: Minimum number of vertices defining a boundary.

• maxVertices: Maximum number of vertices defining a boundary.

• minPerimeterLengthKM: The minimum perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• meanPerimeterLengthKM: The mean perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• maxPerimeterLengthKM: The maximum perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• meanAreaSqKM: The mean area of all administrative units in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• minAreaSqKM: The minimum area of an administrative unit in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• maxAreaSqKM: The maximum area of an administrative unit in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• staticDownloadLink: The static download link for the aggregate ZIP file containing all boundary information.

• gjDownloadURL: The static download link for the GeoJSON.

• tjDownloadURL: The static download link for the TopoJSON.

• imagePreview: The static download link for an automatically rendered PNG image of the layer.

• simplifiedGeometryGeoJSON: The static download link for the simplified GeoJSON.

Value

A tibble with one row per matching boundary file and the columns described in Details.

Source

geoBoundaries API.

See Also

gb_get().

Metadata functions: gb_get_max_adm_lvl()

Examples

# Get boundary metadata for ADM4.

library(dplyr)

gb_get_metadata(adm_lvl = "ADM4") |>
  glimpse()

---

Get global composite files from geoBoundaries

Description

Returns global composite files for the requested ADM level. Files are clipped to international boundaries, with gaps between borders filled.

Attribution is required whenever these data are used.

Usage

gb_get_world(
  country = "all",
  adm_lvl = "adm0",
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

Arguments

country	A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return data for all countries. See also countrycode::countrycode().
adm_lvl	ADM level. Accepted values are levels 0, 1 and 2 ("adm0" is the country boundary, "adm1" is the first level of subnational boundaries and "adm2" is the second level). Uppercase versions ("ADM1") and level numbers (0, 1, 2) are also accepted.
quiet	Logical. If TRUE, suppress informational messages.
overwrite	Logical. If TRUE, force a fresh download of the source .zip archive.
cache_dir	A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files are stored in a temporary cache directory. See base::tempdir() and the cache strategies in gb_set_cache_dir().

Details

Comprehensive Global Administrative Zones (CGAZ) are global composites for administrative boundaries. Compared with individual country files, the global composite files use extensive simplification so file sizes are small enough for most desktop software. They remove disputed areas, replace them with polygons following US Department of State definitions and fill gaps between borders.

Value

An sf object containing the requested boundaries.

Source

geoBoundaries API.

References

Runfola et al. (2020) geoBoundaries: A global database of political administrative boundaries. PLOS ONE 15(4), e0231866. doi:10.1371/journal.pone.0231866.

See Also

API functions: gb_get(), gb_get_adm

Examples

# This download may take some time.
## Not run: 
world <- gb_get_world()

library(ggplot2)

ggplot(world) +
  geom_sf() +
  coord_sf(expand = FALSE) +
  labs(caption = "Source: www.geoboundaries.org")

## End(Not run)

---

Set the geobounds cache directory

Description

Sets the active cache directory and optionally saves it for future sessions. Use gb_detect_cache_dir() to find the active cache directory.

Usage

gb_set_cache_dir(cache_dir, overwrite = FALSE, install = FALSE, quiet = FALSE)

Arguments

cache_dir	A path to a cache directory. If missing, the function stores cache files in a temporary directory. See base::tempdir().
overwrite	Logical. If TRUE, replace a cache directory already saved in the configuration file.
install	Logical. If TRUE, save the cache directory for use in future sessions. Defaults to FALSE. If cache_dir is missing or empty, this parameter is set to FALSE automatically.
quiet	Logical. If TRUE, suppress informational messages.

Details

By default, when no cache_dir is set, the package uses a directory inside base::tempdir(). Files in this directory are removed when the R session ends. To reuse a cache directory across R sessions, use gb_set_cache_dir(cache_dir = "a/path/here", install = TRUE). This saves the directory in a configuration file under tools::R_user_dir("geobounds", "config").

Value

An invisible character vector containing the path to the cache directory.

Cache strategies

• For occasional use, use the default temporary cache directory.

• Set the cache directory for the current session with gb_set_cache_dir(cache_dir = "a/path/here").

• Save a persistent cache directory for future R sessions with gb_set_cache_dir(cache_dir = "a/path/here", install = TRUE).

• Set the cache directory for an individual download with the cache_dir argument. See gb_get().

See Also

tools::R_user_dir().

Cache utilities: gb_clear_cache(), gb_detect_cache_dir()

Examples

# Caution: this may modify your current state.

## Not run: 
my_cache <- gb_detect_cache_dir()

# Set an example cache.
ex <- file.path(tempdir(), "example", "cachenew")
gb_set_cache_dir(ex)

gb_detect_cache_dir()

# Restore the initial cache.
gb_set_cache_dir(my_cache)
identical(my_cache, gb_detect_cache_dir())

## End(Not run)

gb_detect_cache_dir()

---