Title: World Map Data from Natural Earth
Version: 1.0.1
Description: Facilitates mapping by making natural earth map data from https://www.naturalearthdata.com/ more easily available to R users.
License: MIT + file LICENSE
LazyData: true
LazyDataCompression: xz
Encoding: UTF-8
URL: https://docs.ropensci.org/rnaturalearth/, https://github.com/ropensci/rnaturalearth, https://docs.ropensci.org/rnaturalearthhires/
BugReports: https://github.com/ropensci/rnaturalearth/issues
Additional_repositories: http://packages.ropensci.org
Depends: R (≥ 3.1.1)
Imports: httr (≥ 1.1.0), jsonlite, sf (≥ 0.3-4), terra, utils (≥ 3.2.3)
Suggests: devtools (≥ 1.10.0), dplyr, ggplot2, ggrepel, knitr (≥ 1.12.3), lifecycle (≥ 1.0.3), pbapply, purrr, rlang, rmarkdown, rnaturalearthdata (≥ 0.1.0), rnaturalearthhires (≥ 0.1.0), testthat (≥ 0.9.1), tmap
Config/Needs/website: ropensci/rnaturalearthhires
VignetteBuilder: knitr
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2023-12-14 12:23:14 UTC; filoche
Author: Philippe Massicotte ORCID iD [aut, cre], Andy South [aut], Koen Hufkens ORCID iD [ctb]
Maintainer: Philippe Massicotte <pmassicotte@hotmail.com>
Repository: CRAN
Date/Publication: 2023-12-15 11:00:02 UTC

rnaturalearth: World Map Data from Natural Earth

Description

logo

Facilitates mapping by making natural earth map data from https://www.naturalearthdata.com/ more easily available to R users.

Author(s)

Maintainer: Philippe Massicotte pmassicotte@hotmail.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

check whether the requested data exist on Natural Earth

Description

checks from a list dependent on type, category and scale. If it returns FALSE the data may still exist on the website. Doesn't yet do checking on raster names because I found the naming convention too tricky.

Usage

check_data_exist(
  scale = 110,
  type,
  category = c("cultural", "physical", "raster")
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

type of natural earth file to download one of 'countries', 'map_units', 'map_subunits', 'sovereignty', 'states' OR the portion of any natural earth vector url after the scale and before the . e.g. for 'ne_50m_urban_areas.zip' this would be 'urban_areas' OR the raster filename e.g. for 'MSR_50M.zip' this would be 'MSR_50M'

category

one of natural earth categories : 'cultural', 'physical', 'raster'

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

TRUE or FALSE

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

check_data_exist(scale = 110, category = "cultural", type = "countries")

# Type not in list for this category
check_data_exist(scale = 110, category = "physical", type = "airports")

# Type in list but scale shows FALSE
check_data_exist(scale = 110, category = "cultural", type = "airports")

Check whether to install rnaturalearthdata and install if necessary

Description

If the rnaturalearthdata package is not installed, install it from GitHub using devtools. If it is not up to date, reinstall it.

Usage

check_rnaturalearthdata()

Check whether to install rnaturalearthhires and install if necessary

Description

If the rnaturalearthhires package is not installed, install it from GitHub using devtools. If it is not up to date, reinstall it.

Usage

check_rnaturalearthhires()

check that this scale is present in Natural Earth

Description

check name or numeric scale representations, return numeric one

Usage

check_scale(x)

Arguments

x

scale of map to return, one of 110, 50, 10 or 'small', 'medium', 'large'

Value

integer scale of map

Convert from/to sf/sv objects

Description

returns downloaded data as a spatial object or the filename if load=FALSE. if destdir is specified the data can be reloaded in a later R session using ne_load with the same arguments.

Usage

convert_spatial_class(x, returnclass = c("sf", "sv"))

Arguments

x

Object to be converted

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

Object of class "sf" or "sv"

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

## Not run: 
spdf_world <- ne_download(scale = 110, type = "countries")

plot(spdf_world)
plot(ne_download(type = "populated_places"))

# reloading from the saved file in the same session with same arguments

spdf_world2 <- ne_load(scale = 110, type = "countries")

# download followed by load from specified directory will work across sessions
spdf_world <- ne_download(scale = 110, type = "countries", destdir = getwd())
spdf_world2 <- ne_load(scale = 110, type = "countries", destdir = getwd())

# for raster, here an example with Manual Shaded Relief (MSR) download & load

rst <- ne_download(scale = 50, type = "MSR_50M", category = "raster", destdir = getwd())

# load after having downloaded
rst <- ne_load(
  scale = 50, type = "MSR_50M", category = "raster", destdir =
    getwd()
)

# plot
library(terra)
terra::plot(rst)
# end dontrun

## End(Not run)

world country polygons from Natural Earth

Description

at 1:110m scale (small). Other data and resolutions are in the packages rnaturalearthdata and rnaturalearthhires.

Usage

countries110

Format

A sf object.

An object of class sf (inherits from data.frame) with 177 rows and 169 columns.

Slots

data

A data frame with country attributes.

Source

https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_admin_0_countries.zip

list of cultural layers available from Natural Earth

Description

list of cultural layers available from Natural Earth

Usage

df_layers_cultural

Format

A DataFrame

An object of class data.frame with 43 rows and 4 columns.

list of physical layers available from Natural Earth

Description

list of physical layers available from Natural Earth

Usage

df_layers_physical

Format

A DataFrame

An object of class data.frame with 29 rows and 4 columns.

Get data from within the package

Description

returns world country polygons at a specified scale, used by ne_countries()

Usage

get_data(
  scale = 110,
  type = c("countries", "map_units", "sovereignty", "tiny_countries")
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

country type, one of 'countries', 'map_units', 'sovereignty', 'tiny_countries'

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

A sf object.

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

## Not run: 
spdf_world <- ne_download(scale = 110, type = "countries")

plot(spdf_world)
plot(ne_download(type = "populated_places"))

# reloading from the saved file in the same session with same arguments

spdf_world2 <- ne_load(scale = 110, type = "countries")

# download followed by load from specified directory will work across sessions
spdf_world <- ne_download(scale = 110, type = "countries", destdir = getwd())
spdf_world2 <- ne_load(scale = 110, type = "countries", destdir = getwd())

# for raster, here an example with Manual Shaded Relief (MSR) download & load

rst <- ne_download(scale = 50, type = "MSR_50M", category = "raster", destdir = getwd())

# load after having downloaded
rst <- ne_load(
  scale = 50, type = "MSR_50M", category = "raster", destdir =
    getwd()
)

# plot
library(terra)
terra::plot(rst)
# end dontrun

## End(Not run)

Install the naturalearthdata package after checking with the user

Description

Install the naturalearthdata package after checking with the user

Usage

install_rnaturalearthdata()

Install the naturalearthhires package after checking with the user

Description

Install the naturalearthhires package after checking with the user

Usage

install_rnaturalearthhires()

Get natural earth world coastline

Description

returns world coastline at specified scale

Usage

ne_coastline(scale = 110, returnclass = c("sf", "sv"))

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

An object of class 'sf' for simple feature (from 'sf', the default) or 'SpatVector' (from 'terra').

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

if (requireNamespace("rnaturalearthdata")) {
  coast <- ne_coastline()
  plot(coast)
}

Get natural earth world country polygons

Description

returns world country polygons at a specified scale, or points of tiny_countries

Usage

ne_countries(
  scale = 110,
  type = "countries",
  continent = NULL,
  country = NULL,
  geounit = NULL,
  sovereignty = NULL,
  returnclass = c("sf", "sv")
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

country type, one of 'countries', 'map_units', 'sovereignty', 'tiny_countries'

continent

a character vector of continent names to get countries from.

country

a character vector of country names.

geounit

a character vector of geounit names.

sovereignty

a character vector of sovereignty names.

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

An object of class 'sf' for simple feature (from 'sf', the default) or 'SpatVector' (from 'terra').

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

world <- ne_countries()
africa <- ne_countries(continent = "africa")
france <- ne_countries(country = "france")

plot(world$geometry)
plot(africa$geometry)
plot(france$geometry)

# get as SpatVector
world <- ne_countries(returnclass = "sv")
terra::plot(world)

tiny_countries <- ne_countries(type = "tiny_countries", scale = 50)
plot(tiny_countries)

Download data from Natural Earth and (optionally) read into R

Description

returns downloaded data as a spatial object or the filename if load=FALSE. if destdir is specified the data can be reloaded in a later R session using ne_load with the same arguments.

Usage

ne_download(
  scale = 110,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  destdir = tempdir(),
  load = TRUE,
  returnclass = c("sf", "sv")
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

type of natural earth file to download one of 'countries', 'map_units', 'map_subunits', 'sovereignty', 'states' OR the portion of any natural earth vector url after the scale and before the . e.g. for 'ne_50m_urban_areas.zip' this would be 'urban_areas'. See Details. OR the raster filename e.g. for 'MSR_50M.zip' this would be 'MSR_50M'

category

one of natural earth categories : 'cultural', 'physical', 'raster'

destdir

where to save files, defaults to tempdir(), getwd() is also possible.

load

'TRUE' load the spatial object into R, 'FALSE' return the filename of the downloaded object.

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

An object of class 'sf' for simple feature (from 'sf', the default) or 'SpatVector' (from 'terra').

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

## Not run: 
spdf_world <- ne_download(scale = 110, type = "countries")

plot(spdf_world)
plot(ne_download(type = "populated_places"))

# reloading from the saved file in the same session with same arguments

spdf_world2 <- ne_load(scale = 110, type = "countries")

# download followed by load from specified directory will work across sessions
spdf_world <- ne_download(scale = 110, type = "countries", destdir = getwd())
spdf_world2 <- ne_load(scale = 110, type = "countries", destdir = getwd())

# for raster, here an example with Manual Shaded Relief (MSR) download & load

rst <- ne_download(scale = 50, type = "MSR_50M", category = "raster", destdir = getwd())

# load after having downloaded
rst <- ne_load(
  scale = 50, type = "MSR_50M", category = "raster", destdir =
    getwd()
)

# plot
library(terra)
terra::plot(rst)
# end dontrun

## End(Not run)

return a natural earth filename based on arguments

Description

returns a string that can then be used to download the file.

Usage

ne_file_name(
  scale = 110,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  full_url = FALSE
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

type of natural earth file to download one of 'countries', 'map_units', 'map_subunits', 'sovereignty', 'states' OR the portion of any natural earth vector url after the scale and before the . e.g. for 'ne_50m_urban_areas.zip' this would be 'urban_areas' OR the raster filename e.g. for 'MSR_50M.zip' this would be 'MSR_50M'

category

one of natural earth categories : 'cultural', 'physical', 'raster'

full_url

whether to return just the filename (default) or the full URL needed for download

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

string

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

ne_name <- ne_file_name(scale = 110, type = "countries")
ne_url <- ne_file_name(scale = 110, type = "countries", full_url = TRUE)

Return a dataframe of available vector layers on Natural Earth

Description

Checks the Natural Earth Github repository for current vector layers and provides the file name required in the type argument of ne_download.

Usage

ne_find_vector_data(
  scale = 110,
  category = c("cultural", "physical"),
  getmeta = FALSE
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

category

one of natural earth categories : 'cultural', 'physical'

getmeta

whether to get url of the metadata for each layer

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

dataframe with two variables: layer and metadata

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples

## Not run: 
ne_find_vector_data(scale = 10, category = "physical")

## End(Not run)

Return contents of Natural Earth Github directory

Description

Uses the Github API to return contents of Natural Earth Github directories.

Usage

ne_git_contents(path)

Arguments

path

string, one of: '110m_physical', '110m_cultural', '50m_physical', '50m_cultural', '10m_physical', '10m_cultural'

Value

list. Includes parsed json content, http path, and response code.

Create list of layer names and metadata links

Description

Parses Natural Earth Github folder content for layer names and metadata links.

Usage

ne_git_layer_names(x, scale, getmeta)

Arguments

x

object returned by ne_git_contents

scale

one of 110, 50, 10

getmeta

whether to get url of the metadata for each layer

Value

list of lists with layer names and metadata links.

load a Natural Earth vector that has already been downloaded to R using ne_download

Description

returns loaded data as a spatial object.

Usage

ne_load(
  scale = 110,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  destdir = tempdir(),
  file_name = NULL,
  returnclass = c("sf", "sv")
)

Arguments

scale

The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.

type

type of natural earth file one of 'countries', 'map_units', 'map_subunits', 'sovereignty', 'states' OR the portion of any natural earth vector url after the scale and before the . e.g. for 'ne_50m_urban_areas.zip' this would be 'urban_areas' OR the raster filename e.g. for 'MSR_50M.zip' this would be 'MSR_50M'

category

one of natural earth categories : 'cultural', 'physical', 'raster'

destdir

folder to load files from, default=tempdir()

file_name

OPTIONAL name of file (excluding path) instead of natural earth attributes

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

An object of class 'sf' for simple feature (from 'sf', the default) or 'SpatVector' (from 'terra').

See Also

ne_download

Examples

## Not run: 
# download followed by load from tempdir() works in same R session
spdf_world <- ne_download(scale = 110, type = "countries")
spdf_world2 <- ne_load(scale = 110, type = "countries")

# download followed by load from specified directory works between R sessions
spdf_world <- ne_download(scale = 110, type = "countries", destdir = getwd())
spdf_world2 <- ne_load(scale = 110, type = "countries", destdir = getwd())

# for raster download & load
rst <- ne_download(scale = 50, type = "OB_50M", category = "raster", destdir = getwd())

# load after having downloaded
rst <- ne_load(scale = 50, type = "OB_50M", category = "raster", destdir = getwd())

# plot
library(terra)
plot(rst)
# end dontrun

## End(Not run)

Get natural earth world state (admin level 1) polygons

Description

returns state polygons (administrative level 1) for specified countries

Usage

ne_states(
  country = NULL,
  geounit = NULL,
  iso_a2 = NULL,
  spat_object = NULL,
  returnclass = c("sf", "sv")
)

Arguments

country

a character vector of country names.

geounit

a character vector of geounit names.

iso_a2

a character vector of iso_a2 country codes

spat_object

an optional alternative states map

returnclass

A string determining the spatial object to return. Either "sf" for for simple feature (from 'sf', the default) or "sv" for a 'SpatVector' (from 'terra').

Details

Note that the filename of the requested object will be returned if 'load = FALSE'.

Value

An object of class 'sf' for simple feature (from 'sf', the default) or 'SpatVector' (from 'terra').

See Also

ne_load, pre-downloaded data are available using ne_countries, ne_states. Other geographic data are available in the raster package : getData.

Examples


# comparing using country and geounit to filter
if (requireNamespace("rnaturalearthhires")) {
  spdf_france_country <- ne_states(country = "france")
  spdf_france_geounit <- ne_states(geounit = "france")

  plot(spdf_france_country)
  plot(spdf_france_geounit)

  plot(ne_states(country = "united kingdom"))
  plot(ne_states(geounit = "england"))
}