Package 'rnaturalearth' reference manual

Title:	World Map Data from Natural Earth
Description:	Facilitates mapping by making natural earth map data from <https://www.naturalearthdata.com/> more easily available to R users.
Authors:	Philippe Massicotte [aut, cre] , Andy South [aut], Koen Hufkens [ctb]
Maintainer:	Philippe Massicotte <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.1.9000
Built:	2025-03-16 22:50:50 UTC
Source:	https://github.com/ropensci/rnaturalearth

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(
  type,
  scale = 110L,
  category = c("cultural", "physical", "raster")
)
check_data_exist(
  type,
  scale = 110L,
  category = c("cultural", "physical", "raster")
)

Arguments

`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'
`scale`	The scale of map to return, one of '110', '50', '10' or 'small', 'medium', 'large'.
`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

Examples

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

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

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

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

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

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

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_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_rnaturalearthhires()

check that this scale is present in Natural Earth

Description

check name or numeric scale representations, return numeric one

Usage

check_scale(x)
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"))
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"

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)

## 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
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
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
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 = 110L,
  type = c("countries", "map_units", "sovereignty", "tiny_countries")
)
get_data(
  scale = 110L,
  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.

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)

## 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_rnaturalearthdata()

Install the naturalearthhires package after checking with the user

Description

Install the naturalearthhires package after checking with the user

Usage

install_rnaturalearthhires()
install_rnaturalearthhires()

Get natural earth world coastline

Description

returns world coastline at specified scale

Usage

ne_coastline(scale = 110L, returnclass = c("sf", "sv"))
ne_coastline(scale = 110L, 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').

Examples

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

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 = 110L,
  type = "countries",
  continent = NULL,
  country = NULL,
  geounit = NULL,
  sovereignty = NULL,
  returnclass = c("sf", "sv")
)
ne_countries(
  scale = 110L,
  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').

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)

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 = 110L,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  destdir = tempdir(),
  load = TRUE,
  returnclass = c("sf", "sv")
)
ne_download(
  scale = 110L,
  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').

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)

## 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 = 110L,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  full_url = FALSE
)
ne_file_name(
  scale = 110L,
  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

Examples

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

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 = 110L,
  category = c("cultural", "physical"),
  getmeta = FALSE
)
ne_find_vector_data(
  scale = 110L,
  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

Examples

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

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

## End(Not run)

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 = 110L,
  type = "countries",
  category = c("cultural", "physical", "raster"),
  destdir = tempdir(),
  file_name = NULL,
  returnclass = c("sf", "sv")
)
ne_load(
  scale = 110L,
  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').

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)

## 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")
)
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').

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"))
}

# 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"))
}

Package 'rnaturalearth'

Help Index

check whether the requested data exist on Natural Earth

Description

Usage

Arguments

Details

Value

See Also

Examples

Check whether to install rnaturalearthdata and install if necessary

Description

Usage

Check whether to install rnaturalearthhires and install if necessary

Description

Usage

check that this scale is present in Natural Earth

Description

Usage

Arguments

Value

Convert from/to sf/sv objects

Description

Usage

Arguments

Details

Value

See Also

Examples

world country polygons from Natural Earth

Description

Usage

Format

Slots

Source

list of cultural layers available from Natural Earth

Description

Usage

Format

list of physical layers available from Natural Earth

Description

Usage

Format

Get data from within the package

Description

Usage

Arguments

Details

Value

See Also

Examples

Install the naturalearthdata package after checking with the user

Description

Usage

Install the naturalearthhires package after checking with the user

Description

Usage

Get natural earth world coastline

Description

Usage

Arguments

Details

Value

See Also

Examples

Get natural earth world country polygons

Description

Usage

Arguments

Details

Value

See Also

Examples

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

Description

Usage

Arguments

Details

Value

See Also

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