Skip to content

Commit

Permalink
Restructure README
Browse files Browse the repository at this point in the history
  • Loading branch information
@francisbarton
francisbarton committed Nov 10, 2023
1 parent f603d13 commit e334e37
Show file tree
Hide file tree
Showing 2 changed files with 94 additions and 89 deletions.
95 changes: 50 additions & 45 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,58 +28,13 @@ library(ggplot2)

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

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

The main purpose of this package is to download area lookups and
boundaries (in GeoJSON format) using the ONS Open Geography API, for all
areas at a specified level within a specified area.

The main script will return a data frame with the sub-area geometry
column, as an `sf` object ready to be visualised as a map.

### Package logic

The structure of the project looks a bit like this:

bounds() / points() [main UI functions]
^
|
|
<------- create_lookup_table() [available to the user]
| ^
| |
| <--------- return_query_data()
| |
| <--------- return_lookup_query_info()
| \
| \
<------- return_spatial_data() <----- opengeo_schema [data]
^ / ^
| / |
<-------- pull_geo_query_url() |
|
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 code.

`return_lookup_query_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 - but may need
updating.

`create_lookup_table()` 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.


## Installation

Expand Down Expand Up @@ -252,6 +207,50 @@ For certain geographic levels you can supply a more human-friendly alias, so you

Ideas for other useful aliases happily received.


## Package internal structure

The structure of the project looks a bit like this:

bounds() / points() [main UI functions]
^
|
|
<------- create_lookup_table() [available to the user]
| ^
| |
| <--------- return_query_data()
| |
| <--------- return_lookup_query_info()
| \
| \
<------- return_spatial_data() <----- opengeo_schema [data]
^ / ^
| / |
<-------- pull_geo_query_url() |
|
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 code.

`return_lookup_query_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 - but may need
updating.

`create_lookup_table()` 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
Expand All @@ -262,10 +261,16 @@ Please note that `boundr` is released with a [Contributor Code of
Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.



## News

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


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

### Licences

The code in this repo is MIT licensed.
Expand Down
88 changes: 44 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,57 +8,13 @@

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

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

The main purpose of this package is to download area lookups and
boundaries (in GeoJSON format) using the ONS Open Geography API, for all
areas at a specified level within a specified area.

The main script will return a data frame with the sub-area geometry
column, as an `sf` object ready to be visualised as a map.

### Package logic

The structure of the project looks a bit like this:

bounds() / points() [main UI functions]
^
|
|
<------- create_lookup_table() [available to the user]
| ^
| |
| <--------- return_query_data()
| |
| <--------- return_lookup_query_info()
| \
| \
<------- return_spatial_data() <----- opengeo_schema [data]
^ / ^
| / |
<-------- pull_geo_query_url() |
|
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 code.

`return_lookup_query_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 - but may need updating.

`create_lookup_table()` 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.

## Installation

You can install this package from the `R` console by entering
Expand Down Expand Up @@ -390,6 +346,47 @@ alias, so you don’t need to remember the abbreviated prefix.

Ideas for other useful aliases happily received.

## Package internal structure

The structure of the project looks a bit like this:

bounds() / points() [main UI functions]
^
|
|
<------- create_lookup_table() [available to the user]
| ^
| |
| <--------- return_query_data()
| |
| <--------- return_lookup_query_info()
| \
| \
<------- return_spatial_data() <----- opengeo_schema [data]
^ / ^
| / |
<-------- pull_geo_query_url() |
|
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 code.

`return_lookup_query_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 - but may need updating.

`create_lookup_table()` 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
Expand All @@ -403,6 +400,9 @@ By contributing to this project, you agree to abide by its terms.

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

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

### Licences

The code in this repo is MIT licensed.
Expand Down

0 comments on commit e334e37

Please sign in to comment.