diff --git a/README.Rmd b/README.Rmd index 2e6417b..9df2d4e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -45,9 +45,11 @@ You can install the development version of ukgeographies from devtools::install_github("WarwickCIM/ukgeographies") ``` -## Example +## Getting geographical boundaries -This is a basic example which shows you how to solve a common problem: +So far, this package provides two functions to download a selected boundary from ONS geoportal and convert it into a `sf` object: `boundaries_get()` and `boundaries_select()` + +`boundaries_get()` will construct the API query to download the desired boundary based on the parameters. ```{r example} library(ukgeographies) @@ -63,6 +65,11 @@ plot(countries_2023["CTRY23NM"]) ``` +Because not every boundary is available for every year or detail level, some combination of parameters may yield invalid queries. To address that issue, `boundaries_select()` provides an interface that exposes the available options based on the previous selection, so the combination will always be valid. + +![](vignettes/media/boundaries_select_demo.webm) + + ## Boundaries ```{r echo=FALSE} diff --git a/README.md b/README.md index 36a77d5..9f52643 100644 --- a/README.md +++ b/README.md @@ -40,21 +40,32 @@ You can install the development version of ukgeographies from devtools::install_github("WarwickCIM/ukgeographies") ``` -## Example +## Getting geographical boundaries -This is a basic example which shows you how to solve a common problem: +So far, this package provides two functions to download a selected +boundary from ONS geoportal and convert it into a `sf` object: +`boundaries_get()` and `boundaries_select()` + +`boundaries_get()` will construct the API query to download the desired +boundary based on the parameters. ``` r library(ukgeographies) # Get a sf object from countries_2023 <- boundaries_get("CTRY", 2023, "BUC") +#> ℹ Querying ONS API +#> ✔ Querying ONS API [48ms] +#> +#> ⠙ Downloading the selected dataset from ONS services #> Warning in CPL_read_ogr(dsn, layer, query, as.character(options), quiet, : GDAL #> Message 1: organizePolygons() received a polygon with more than 100 parts. The #> processing may be really slow. You can skip the processing by setting #> METHOD=SKIP, or only make it analyze counter-clock wise parts by setting #> METHOD=ONLY_CCW if you can assume that the outline of holes is counter-clock #> wise defined +#> ✔ Downloading the selected dataset from ONS services [3.2s] +#> ``` ``` r @@ -72,12 +83,12 @@ countries_2023 #> Bounding box: xmin: -8.649996 ymin: 49.88234 xmax: 1.763706 ymax: 60.86087 #> Geodetic CRS: WGS 84 #> # A tibble: 4 × 12 -#> FID CTRY23CD CTRY23NM CTRY23NMW BNG_E BNG_N LONG LAT Shape__Area -#> -#> 1 1 E92000001 England Lloegr 394883 370883 -2.0… 53.2… 1.31e11 -#> 2 2 N92000002 Northern Irel… Gogledd … 86544 535337 -6.8… 54.6… 1.43e10 -#> 3 3 S92000003 Scotland Yr Alban 277744 700060 -3.9… 56.1… 7.86e10 -#> 4 4 W92000004 Wales Cymru 263405 242881 -3.9… 52.0… 2.08e10 +#> FID CTRY23CD CTRY23NM CTRY23NMW BNG_E BNG_N LONG LAT Shape__Area +#> +#> 1 1 E92000001 England Lloegr 394883 370883 -2.08 53.2 1.31e11 +#> 2 2 N92000002 Northern Irel… Gogledd … 86544 535337 -6.86 54.6 1.43e10 +#> 3 3 S92000003 Scotland Yr Alban 277744 700060 -3.97 56.2 7.86e10 +#> 4 4 W92000004 Wales Cymru 263405 242881 -3.99 52.1 2.08e10 #> # ℹ 3 more variables: Shape__Length , GlobalID , #> # geometry ``` @@ -89,35 +100,43 @@ plot(countries_2023["CTRY23NM"]) +Because not every boundary is available for every year or detail level, +some combination of parameters may yield invalid queries. To address +that issue, `boundaries_select()` provides an interface that exposes the +available options based on the previous selection, so the combination +will always be valid. + +![](vignettes/media/boundaries_select_demo.webm) + ## Boundaries #> - #> Attaching package: 'dplyr' - #> The following objects are masked from 'package:stats': + #> S'està adjuntant el paquet: 'dplyr' + #> Els següents objectes estan emmascarats des de 'package:stats': #> #> filter, lag - #> The following objects are masked from 'package:base': + #> Els següents objectes estan emmascarats des de 'package:base': #> #> intersect, setdiff, setequal, union -| boundary_type | boundary | BFC | BFE | BGC | BUC | NA | -|:------------------|:---------|:-----------------------------------------------|:-----------------------------------------------------------|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------------------------------------------| -| Administrative | CAUTH | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2016; 2017; 2018; 2019; 2020; 2023 | -| Administrative | CED | 2023 | 2023 | 2023 | 2023 | 2017; 2018; 2019; 2020 | -| Administrative | CTRY | 1961; 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2011; 2016; 2017; 2018; 2019; 2020; 2023 | -| Administrative | CTY | 1961; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 1991; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2023 | -| Administrative | CTYUA | 2017; 2019; 2020; 2021; 2022; 2023 | 2017; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2017; 2021; 2022; 2023 | 2011; 2017; 2018; 2019; 2023 | -| Administrative | LAD | 2008; 2011; 2016; 2017; 2019; 2021; 2022; 2023 | 2008; 2011; 2012; 2013; 2014; 2016; 2019; 2021; 2022; 2023 | 2008; 2011; 2017; 2019; 2021; 2022; 2023 | 2016; 2017; 2019; 2020; 2021; 2022; 2023 | 2011; 2016; 2017; 2018; 2019; 2022; 2023 | -| Administrative | LPA | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021 | -| Administrative | MCTY | NA | NA | NA | NA | 2016; 2017; 2018; 2019; 2020 | -| Administrative | PAR | 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020 | 2011; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2022; 2023 | -| Administrative | PARNCP | 2020; 2021; 2022; 2023 | 2020; 2022; 2023 | 2020; 2021; 2022; 2023 | NA | 2018; 2019; 2020; 2021; 2022; 2023 | -| Administrative | RGN | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2015; 2016; 2017; 2018; 2019; 2020; 2023 | -| Administrative | UTLA | 2022 | 2022 | 2022 | 2022 | 2022 | -| Administrative | WD | 2019; 2020; 2021; 2022; 2023 | 1998; 2016; 2019; 2020; 2021; 2022; 2023; 2024 | 2019; 2020; 2021; 2022; 2023 | NA | 1991; 1998; 2011; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2022; 2023; 2024 | -| Census Boundaries | LSOA | NA | 2011 | 2001 | NA | NA | -| Census Boundaries | MSOA | NA | 2001; 2011 | 2001 | NA | NA | -| Census Boundaries | OA | 2001; 2011; 2021 | 2001; 2021 | 2001; 2011; 2021 | NA | 2001; 2011; 2021 | +| boundary_type | boundary | BFC | BFE | BGC | BUC | NA | +|:---|:---|:---|:---|:---|:---|:---| +| Administrative | Combined Authorities | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2016; 2017; 2018; 2019; 2020; 2023 | +| Administrative | Counties | 1961; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 1991; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2023 | +| Administrative | Counties and Unitary Authorities | 2017; 2019; 2020; 2021; 2022; 2023 | 2017; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2017; 2021; 2022; 2023 | 2011; 2017; 2018; 2019; 2023 | +| Administrative | Countries | 1961; 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2016; 2020; 2021; 2022; 2023 | 2011; 2016; 2017; 2018; 2019; 2020; 2023 | +| Administrative | County Electoral Division | 2023 | 2023 | 2023 | 2023 | 2017; 2018; 2019; 2020 | +| Administrative | Local Authority Districts | 2008; 2011; 2016; 2017; 2019; 2021; 2022; 2023; 2024 | 2008; 2011; 2012; 2013; 2014; 2016; 2019; 2021; 2022; 2023; 2024 | 2008; 2011; 2017; 2019; 2021; 2022; 2023; 2024 | 2016; 2017; 2019; 2020; 2021; 2022; 2023; 2024 | 2011; 2016; 2017; 2018; 2019; 2022; 2023; 2024 | +| Administrative | Local Planning Authorities | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2019; 2020; 2021 | +| Administrative | Metropolitan Counties | NA | NA | NA | NA | 2016; 2017; 2018; 2019; 2020 | +| Administrative | Parishes | 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020 | 2011; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2022; 2023 | +| Administrative | Parishes and Non Civil Parished Areas | 2020; 2021; 2022; 2023 | 2020; 2022; 2023 | 2020; 2021; 2022; 2023 | NA | 2018; 2019; 2020; 2021; 2022; 2023 | +| Administrative | Regions | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2020; 2021; 2022; 2023 | 2019; 2020; 2021; 2022; 2023 | 2015; 2016; 2017; 2018; 2019; 2020; 2023 | +| Administrative | Upper Tier | 2022 | 2022 | 2022 | 2022 | 2022 | +| Administrative | Wards | 2019; 2020; 2021; 2022; 2023 | 1998; 2016; 2019; 2020; 2021; 2022; 2023; 2024 | 2019; 2020; 2021; 2022; 2023; 2024 | NA | 1991; 1998; 2011; 2015; 2016; 2017; 2018; 2019; 2020; 2021; 2022; 2023; 2024 | +| NA | Lower Layer Output Areas | NA | 2011 | 2001 | NA | NA | +| NA | Middle Layer Output Areas | NA | 2001; 2011 | 2001 | NA | NA | +| NA | Output Areas | 2001; 2011; 2021 | 2001; 2021 | 2001; 2011; 2021 | NA | 2001; 2011; 2021 | [^1]: To get you started, ONS has edited a [A Beginner’s Guide to UK Geography](https://geoportal.statistics.gov.uk/datasets/c0db0e8c67d04935bcf1749ca6027fef/about) diff --git a/man/figures/README-example-1.png b/man/figures/README-example-1.png index 941a8e9..cac6d3e 100644 Binary files a/man/figures/README-example-1.png and b/man/figures/README-example-1.png differ diff --git a/vignettes/media/boundaries_select_demo.webm b/vignettes/media/boundaries_select_demo.webm new file mode 100644 index 0000000..c91facb Binary files /dev/null and b/vignettes/media/boundaries_select_demo.webm differ