---
title: "Introduction to rnaturalearth."
author: "Andy South"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
#to produce a pdf
#output: rmarkdown::pdf_document
vignette: >
  %\VignetteIndexEntry{Introduction to rnaturalearth.}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

This vignette is an introduction to [rnaturalearth](https://github.com/ropenscilabs/rnaturalearth), an R package to hold and facilitate interaction with natural earth vector map data. `rnaturalearth` is a data package designed to provide map data that can be visualised using other R packages.

[Natural Earth](http://www.naturalearthdata.com/) is a public domain map dataset including vector country and other administrative boundaries. 

[rnaturalearth](https://github.com/ropenscilabs/rnaturalearth) does two main things.

1. Contains pre-downloaded vector maps for : 
    + countries `ne_countries()`
    + states `ne_states()`
    + coastline `ne_coastline()`
    
1. Has `ne_download()` function to facilitate download of other vector and raster maps.


This vignette uses `sp::plot` as a simple, quick way to show how different data can be accessed.`rnaturalearth` is designed to provide data allowing creation of more elaborate maps in other visualisation packages (e.g. `ggplot2`, `tmap` and `choroplethr`).



#### load required packages
```{r, eval=TRUE, echo=TRUE, message=FALSE}
library(rnaturalearth)
library(sp)
```


## 1. Maps in the package.
Pre-downloaded maps can be accessed with : 

1. `ne_countries()` for country (admin-0) boundaries 
1. `ne_states()` for boundaries within countries (admin-1)
1. `ne_coastline()` for world coastline


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

# world at small scale (low resolution)
sp::plot(ne_countries(type = 'countries', scale = 'small'))

# countries, UK undivided
sp::plot(ne_countries(country = 'united kingdom', type='countries'))
# map_units, UK divided into England, Scotland, Wales and Northern Ireland
sp::plot(ne_countries(country = 'united kingdom', type='map_units'))

     
# countries, small scale
sp::plot(ne_countries(country = 'united kingdom', scale = 'small'))   

# countries, medium scale
sp::plot(ne_countries(country = 'united kingdom', scale = 'medium'))

```


```{r, eval=FALSE, echo=TRUE, message=FALSE}
# not evaluated because rely on rnaturalearthhires data which are on rOpenSci so CRAN check likely to fail

# countries, large scale
sp::plot(ne_countries(country = 'united kingdom', scale = 'large'))

# states country='united kingdom'
sp::plot(ne_states(country = 'united kingdom'))  
# states geounit='england'
sp::plot(ne_states(geounit = 'england')) 

# states country='france'
sp::plot(ne_states(country = 'france'))

```

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

# coastline of the world
# subsetting of coastline is not possible because the Natural Earth data are not attributed in that way
sp::plot(ne_coastline())

```




## 2. Downloading other Natural Earth vectors with ne_download().  

Each [Natural Earth](http://www.naturalearthdata.com/) dataset is characterised on the website according to `scale`, `type` and `category`. [rnaturalearth](https://github.com/ropenscilabs/rnaturalearth) allows you to specify `scale`, `type` and `category` and will construct the url and download the corresponding file.

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

# lakes
lakes110 <- ne_download(scale = 110, type = 'lakes', category = 'physical')
sp::plot(lakes110, col = 'blue')

# rivers
rivers110 <- ne_download(scale = 110, type = 'rivers_lake_centerlines', category = 'physical')
sp::plot(rivers110, col = 'blue')


```


