readme.Rmd

---
title: "rgeoportal"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE,
                      fig.path = "man/figures/README-")
library(dplyr)
library(sf)
```

## Installing rgeoportal
Install from github using devtools:

```{r install, message = F, eval = F}
library(devtools)
install_github('Chrisjb/rgeoportal')
```

## get_boundary

```{r get_boundary_top_levels, eval = FALSE}
get_boundary(boundary_type = c("administrative", "census", "electoral",
                               "eurostat", "health", "other", "postcodes"),
             boundary_name = NA,
             bbox = NA,
             redius = NA,
             point = NA,
             names_like = NA,
             names_equal = NA,
             custom_polygon = NA)
```


### boundary_type

We can get the boundary names available within each boundary type by specifying `boundary_type` with no `boundary_name` option:

```{r boundary_census_options}
library(rgeoportal)
census_boundaries <- get_boundary(boundary_type = 'census')

head(census_boundaries)
```

```{r boundary_admin_options}
administrative <- get_boundary(boundary_type = 'administrative')

head(administrative)
```

Some of the boundary names come with a range of suffixes:

* BFC: Full resolution - clipped to the coastline (Mean High Water mark). 
* BFE: Full resolution - extent of the realm (usually this is the Mean Low Water mark but in some cases boundaries extend beyond this to include off shore islands).
* BGC: Generalised (20m) - clipped to the coastline (Mean High Water mark).
* BUC: Ultra Generalised (500m) - clipped to the coastline (Mean High Water mark). Contains both Ordnance Survey and ONS Intellectual Property Rights. 


Note that most boundaries have a maximim record count of 200. Large requests will typically be limited to 200 observations.


### boundary_name

We can select one of the boundary names returned from the above request and set it as the `boundary_name`:

```{r boundary_name, cache=TRUE}
merged_auth <- get_boundary(boundary_type = 'census',
                                  boundary_name='Census_Merged_Local_Authority_Districts_December_2011_Boundaries')

```


```{r}
head(merged_auth)
```


```{r}
library(ggplot2)
ggplot() + 
  geom_sf(data=merged_auth)
```


## Specifying the request
In general we don't want to request more data than we need. Many boundaries also limit the amount of polygons any given request will return to 200. There are several ways to request only the subset of the total boundary data we need:

* bbox: return only results in the specified bbox
* radius: return only results within a given distance of a specified point
* names_like: return only results where the polygon name contains the given string(s)
* names_equal: return only results where the polygon name matches the given string(s)
* custom_polygon: return only results in the specified polygon


### bbox 

One way to request a subset of boundary data is to add a `bbox` to the request. We can set a bounding box in the form 'xmin,ymin,xmax,ymax' or as an `sf` `bbox` as generated by `sf::st_bbox()`.


One way to get a bounding box is to use `st_bbox` on another set of polygons:
```{r}
my_auths <- merged_auth %>% filter(cmlad11nm %in% c('Wandsworth'))
my_bbox <- st_bbox(my_auths)
```



```{r cache=TRUE}
msoa_in_bbox <- get_boundary(boundary_type = 'census',
                             boundary_name='Middle_Super_Output_Areas_December_2011_Boundaries',
                             bbox = my_bbox)

head(msoa_in_bbox)

```


```{r}
ggplot() + 
  geom_sf(data=msoa_in_bbox) +
  geom_sf(data = st_as_sfc(my_bbox), colour = 'black', fill=NA)
```


We can also specify a `bbox` from a user specified string:

```{r cache = TRUE}
msoa_in_bbox_2 <- get_boundary(boundary_type = 'census',
                             boundary_name='Middle_Super_Output_Areas_December_2011_Boundaries',
                             bbox = '-2.65,51.41,-2.52,51.50')

head(msoa_in_bbox)
```


```{r}
ggplot() + 
  geom_sf(data=msoa_in_bbox_2) +
  coord_sf(xlim = c(-2.65,-2.52),  ylim =c(51.41, 51.50))
```


### radius
Another way to filter the request is to get boundaries within a set radius of a given point. If radius is set, `point` must be set too.

`point` should be a longitude latitude point in the form 'lng,lat'
`radius` is specified in meters

```{r cache = TRUE}
ward_in_radius <- get_boundary(boundary_type = 'admin',
                             boundary_name='Wards_May_2019_Boundaries_UK_BFC',
                             point = '-2.58791,51.45451',
                             radius = 2000)
```




### names_like
If we don't want to list the exact names of the wards, we can do partial matching by specifying `names_like`. This is especially useful for boundaries where the area name forms a predictable pattern such as msoa names which all start with their local authority name.

Specifying `names_like` will return polygons that (partially) match the name of the polygon

```{r cache = TRUE}
msoa_dartford <- get_boundary(boundary_type = 'census',
                             boundary_name='Middle_Super_Output_Areas_December_2011_Boundaries',
                             names_like = c('Dartford'))

head(msoa_dartford)
```



### names_equal
If we know the exact name(s) of the polygon we want to return, we should specify `names_equal`:

```{r cache=TRUE}
dg <- get_boundary(boundary_type = 'admin',
                             boundary_name='Local_Authority_Districts_December_2019_Boundaries_UK_BFC',
                             names_equal = c('Dartford', 'Gravesham'))

head(dg)
```

### custom_polygon
There is also the option to use a custom polygon and return boundaries that intersect the given polygon. 

We may need to simplify the polygon before sending the request:

```{r simplify_polygon}
custom_poly <- ward_in_radius %>% filter(wd19nm == 'Clifton')
custom_poly_simp <- rmapshaper::ms_simplify(custom_poly)
```


```{r cache=TRUE}
lsoa_in_poly <- get_boundary(boundary_type = 'census',
                             boundary_name='Lower_Super_Output_Areas_December_2011_Boundaries',
                             custom_polygon = custom_poly_simp)


ggplot() +
  geom_sf(data = st_intersection(lsoa_in_poly, custom_poly)) +
  geom_sf(data =custom_poly, color = 'red', fill=NA ) 
```