Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ropensci/rnaturalearth

An R package to hold and facilitate interaction with natural earth map data :earth_africa:
https://github.com/ropensci/rnaturalearth

peer-reviewed r r-package rstats

Last synced: about 1 month ago
JSON representation

An R package to hold and facilitate interaction with natural earth map data :earth_africa:

Host: GitHub
URL: https://github.com/ropensci/rnaturalearth
Owner: ropensci
License: other
Created: 2015-06-14T18:50:13.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2024-08-10T18:42:53.000Z (about 1 month ago)
Last Synced: 2024-08-10T19:59:43.289Z (about 1 month ago)
Topics: peer-reviewed, r, r-package, rstats
Language: R
Homepage: http://ropensci.github.io/rnaturalearth/
Size: 123 MB
Stars: 216
Watchers: 16
Forks: 24
Open Issues: 6
Metadata Files:
- Readme: README.Rmd
- License: LICENSE

Awesome Lists containing this project

jimsghstars - ropensci/rnaturalearth - An R package to hold and facilitate interaction with natural earth map data :earth_africa: (R)

README

        ---

output: github_document

---

```{r, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  fig.path = "man/figures/README-",

  comment = "",

  dev = "png"

)

```

[![CRAN status](https://www.r-pkg.org/badges/version/rnaturalearth)](https://CRAN.R-project.org/package=rnaturalearth)

[![](https://badges.ropensci.org/22_status.svg)](https://github.com/ropensci/software-review/issues/22)

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

[![R-CMD-check](https://github.com/ropensci/rnaturalearth/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rnaturalearth/actions/workflows/R-CMD-check.yaml)

# rnaturalearth

An R package to hold and facilitate interaction with [Natural Earth](https://www.naturalearthdata.com/) map data.

This package provides :

- access to a pre-downloaded subset of Natural Earth v4.1.0 (March 2018) vector data commonly used in world mapping

- easy subsetting by countries and regions

- functions to download other Natural Earth vector and raster data

- a simple, reproducible and sustainable workflow from Natural Earth data to rnaturalearth enabling updating as new versions become available

- clarification of differences in world maps classified by countries, sovereign states and map units

- consistency with Natural Earth naming conventions so that rnaturalearth users can use Natural Earth documentation

- data in `sf` or `sv` formats

The [Natural Earth](https://www.naturalearthdata.com/) website structures vector data by scale, category and type. These determine the filenames of downloads. rnaturalearth uses this structure to facilitate download (like an API).

## Install rnaturalearth

Install from CRAN :

```r

install.packages("rnaturalearth")

```

or install the development version from GitHub using [devtools](https://github.com/r-lib/devtools).

```r

devtools::install_github("ropensci/rnaturalearth")

```

Data to support much of the package functionality are stored in two data packages that you will be prompted to install when required if you do not do so here.

```r

devtools::install_github("ropensci/rnaturalearthdata")

devtools::install_github("ropensci/rnaturalearthhires")

```

## First usage

Here using `plot` as a simple, quick way to plot maps. Maps could also be made with `ggplot2`, `tmap` or other options. All retrieval functions accept an argument `returnclass = "sf"` to return package `sf` (Simple Features) or `returnclass = "sv"` (SpatVector) objects.

```{r, eval=TRUE}

library(rnaturalearth)

# world countries

plot(ne_countries())

# uk

plot(ne_countries(country = "united kingdom"))

# states, admin level1 boundaries

plot(ne_states(country = "spain"))

```

## Introductory vignette

```{r, eval=FALSE}

vignette("rnaturalearth", package = "rnaturalearth")

```

## To download Natural Earth data not already in the package

There are a wealth of other data available at the [Natural Earth](https://www.naturalearthdata.com/) website. `rnaturalearth` has functions to help with download of these data.

The data available are outlined in the two tables below and online [here](https://www.naturalearthdata.com/downloads/50m-physical-vectors/).

```{r, eval=TRUE, echo=FALSE}

for (category in c("cultural", "physical")) {

  df_data <- read.csv(

    system.file(

      "extdata",

      paste0("data_list_", category, ".csv"),

      package = "rnaturalearth"

    )

  )

  cat("\ncategory  ", category, "\n")

  df_data

}

```

Specify the `scale`, `category` and `type` of the vector you want as in the examples below.

```{r, eval=FALSE}

# lakes

lakes110 <- ne_download(scale = 110, type = "lakes", category = "physical")

plot(lakes110)

# rivers

rivers50 <- ne_download(

  scale = 50,

  type = "rivers_lake_centerlines",

  category = "physical",

  returnclass = "sf"

)

library(ggplot2)

library(sf)

ggplot(rivers50) +

  geom_sf() +

  theme_minimal()

```

## Details of different country definitions and scales

```{r, eval=FALSE}

vignette("what-is-a-country", package = "rnaturalearth")

```

## Reproducible download of Natural Earth data into the package

[Script](https://github.com/ropensci/rnaturalearthdata/blob/master/data-raw/data_download_script.r) used to get data into the accompanying data packages.

## Errors in the data?

If you believe there is an issue with data provided by [Natural Earth](https://www.naturalearthdata.com/), please do not report it here. We are not responsible for the accuracy or maintenance of Natural Earth data. For any concerns regarding this data, please contact [Natural Earth](https://www.naturalearthdata.com/).

## Acknowledgements

Thanks to [Lincoln Mullen](https://github.com/lmullen) for code structure inspiration from [USAboundaries](https://github.com/ropensci/USAboundaries), [Hadley Wickham](https://github.com/hadley) for comments and prompting, [Bob Rudis](https://github.com/hrbrmstr) for answers to stackoverflow questions about downloading Natural Earth data into R. The [Natural Earth team](https://www.naturalearthdata.com/about/contributors/) and [Nathan Kelso](https://github.com/nvkelso) for providing such a great resource.

## Potential future work

### Potential additional data

- Country synonyms lookup

  - dataframe with ISO3 and country synonyms

  - similar to https://github.com/AndySouth/rworldmap/blob/master/data/countrySynonyms.rda

- Country larger regions lookup

  - dataframe with ISO3 and membership of different regional groupings, e.g. continent, least developed countries etc.

  - similar to https://github.com/AndySouth/rworldmap/blob/master/data/countryRegions.rda

### Potential additional functions

- facilitate joining of user data to country boundaries

  - similar to https://github.com/AndySouth/rworldmap/blob/master/R/joinCountryData2Map.R

  - ... but with a better name

  - similar allowing of join by ISO codes or names, with attempted synonym matching

  - similar reporting of country joining success and failure

- facilitate subsetting by country groupings

  - e.g. least developed countries etc.