README.qmd

---
format: gfm
knitr:
  opts_chunk:
    fig.path: "man/figures/README-"
    cache: true
warning: false
---

<!-- README.md is generated from README.qmd. Please edit that file -->

```{r setup}
#| include: false

library(boundr)
library(ggplot2)
library(tmap)

```

# welcome to boundr

<!-- badges: start -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- badges: end -->

### Retrieve area boundaries and data from the ONS Open Geography Portal

<div style="display: flex; align-items: center;">
<div style="flex: 0 0 auto; margin-right: 20px;">
<img
    src="inst/boundr_hex_logo.png"
    height="300px" width="259px" hspace=20 vspace=20
    alt="The boundr package hexagonal logo - the word boundr superimposed on a
      cropped map of the Isles of Scilly, with the island parishes differently
      coloured, on a sea blue background."
/>
<br clear="all" />
</div>

<div>
The main purpose of this package is to download area lookups and boundaries to
  R tables, using the ONS Open Geography API, for all areas at a specified
  level within a specified area.

The main script `bounds()` will return a data frame with the sub-area geometry
  column, as an `sf` object ready to be visualised as a map.
</div>
</div>

## Installation

You can install this package from the `R` console by entering

> remotes::install_git("https://codeberg.org/francisbarton/boundr")

if you have the `remotes` package installed.

## Examples

### Basic lookup of areas within a larger area, by name

Returns `sfc` tibble with latest available data

```{r example-1}

bounds("msoa", "lad", "Swansea")

```


### Lookup areas with older dates

Trial and error may be required - or start by looking up what is available on
  the OpenGeography site.

```{r example-2}

bounds("wd", "lad", "Shepway", within_year = 2016) # Shepway no longer exists

```


### You can just request bare lookup tables - no spatial data attached

```{r example-3}

lookup("spc", "spr")

```


Sometimes boundr needs a little help finding what you are looking for.
Supplying a year or country filter can help get the right table.

### A lookup table for wards to Senedd electoral regions

Using `return_with = "full"` includes all available columns, not just those
  referred to by the `lookup_level` and `within_level` arguments.

```{r example-4}

lookup("wd", "sener", opts = opts(return_width = "full"))

```


### The sfc tibble is ready to be passed to a mapping tool like `tmap::qtm()`

(Here I've chosen to do something a little more complex with `tmap`, but
  `qtm()` works too).

```{r example-5}
#| message: false

bounds("par", "lad", "Isles of Scilly") |>
  tmap::tm_shape() +
  tmap::tm_polygons(
    col = "par23nm",
    palette = "-Accent",
    legend.show = FALSE,
    border.col = "grey40"
  ) +
  tmap::tm_style("natural", bg.color = "#7cb7bb")

```


### bounds now supports a shortcut syntax...

...which will return all bounds for a certain level, without having to specify
  a `within_level` argument

Take care - you might download a lot of data doing this!

```{r example-6}

bounds("spr")

```

### The "centroids" option returns area centroids where available

These are usually population-weighted (PWC) nowadays.
(Some older centroids are address-weighted (AWC).
Check the OpenGeography website).

```{r example-7}
#| message: false

sb <- bounds("msoa", "lad", "Swindon")
sp <- bounds("msoa", "utla", "Swindon", geometry = "centroids")

sb |>
  ggplot2::ggplot() +
  ggplot2::geom_sf(colour = "grey33", fill = "grey95") +
  ggplot2::geom_sf(data = sp, colour = "orange") +
  ggplot2::theme_void()

```

### A ggplot2 example

Here we specify a 'within_names' argument alongside the 'lookup' argument.
There's no 'within_level' argument to be specified because there's nothing to
  lookup against.
(There aren't any lookup tables for National Parks - just the boundaries).


```{r example-8}

bounds("npark", within_names = "Bannau Brycheiniog") |>
  ggplot2::ggplot() +
  ggplot2::geom_sf()

```


```{r example-9}

# https://github.com/francisbarton/mapirosa
library(mapirosa)

# https://dieghernan.github.io/tidyterra/reference/geom_spatraster_rgb.html
library(tidyterra)

bb <- bounds(
  "npark",
  within_names = "Bannau Brycheiniog",
  opts = boundr_options(crs = 27700)
)

bb_basemap <- mapirosa::build_basemap(
  bbox = sf::st_bbox(bb),
  zoom = 3,
  style = "outdoor",
  squarify = TRUE,
  crs = 27700
) |>
  rlang::with_interactive(FALSE)

ggplot2::ggplot(bb) +
  tidyterra::geom_spatraster_rgb(
    data = bb_basemap,
    maxcell = 1e7,
    max_col_value = 1
  ) +
  ggplot2::theme_void() +
  ggplot2::geom_sf(colour = "coral", fill = "aquamarine", alpha = 0.3)
```


## Package internal structure

The structure of the project looks a bit like this:

    bounds() [main UI function]
       ^
       |
       |
       ------- <----- add_geometry_to_table() [also available to user]
       |      |
       |      |
       |      lookup() [main function available to the user]
       |                ^
       |                |
       |                |
       |                 <-------- return_table_info() 
       |                                       \
       |                                        \
        <------- return_spatial_data()           <----- opengeo_schema
                        ^                       /          [pkg data]
                        |                      /               ^
                         <-------- return_bounds_info()        |
                                                          build_schema()

When you call `bounds()` you specify a lower level area (eg ward) and a higher
  level area (eg local authority), and you specify either the name of the higher
  level area (or areas) or its ONS code.
Multiple higher level areas can be submitted.
If no higher level area is specified then boundaries or a lookup will be
  returned directly (without an intermediate lookup table being created).

`return_table_info()` then finds the API query URL of a suitable lookup
  table - one that contains columns for both your lower and higher level areas.
It does this by filtering `opengeo_schema`, which is a cached copy of the
  various datasets available from the Open Geography API Services list.
This schema is available as internal data in the package,and is updated
  periodically by the maintainer but may be slightly out of date.

`lookup()` then builds a lookup table (a tibble) based on all the
  areas you have said you are interested in.

At the same time, `return_spatial_data()` will - if you have specified you want
  spatial boundaries data for your areas - retrieve the boundary data at your
  chosen resolution for your lower level areas.
These will then be joined onto the lookup table and provided to you as an
  `sfc` tibble.


## Contributing

Suggestions for improvements are welcome, preferably posted as an issue on
  Codeberg (or GitHub).
Contributions as pull requests are also welcome.

Please note that `boundr` is released with a [Contributor Code of Conduct][coc].
By contributing to this project, you agree to abide by its terms.

[coc]: https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html


## News

See [NEWS.md](NEWS.md) for version notes.


`boundr` was previously [`jogger`](https://github.com/francisbarton/jogger).

```{r}
#| echo: false

yr <- format(Sys.Date(), "%Y")
```

### Licences

The code in this repo is MIT licensed.

The data that the code helps you retrieve is issued under a variety of
  licences, including:

-   the [Open Government Licence v3.0][ogl3]

> Licensing statement [as stipulated by the ONS][ons-lic]:
>
> -   Source: Office for National Statistics licensed under the [Open
>     Government Licence v3.0][ogl3]
> -   Contains OS data © Crown copyright and database right `r yr`

[ogl3]: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
[ons-lic]: https://www.ons.gov.uk/methodology/geography/licences