| Title: | Aid Querying 'nomis' and 'Office for National Statistics Open Geography' APIs |
|---|---|
| Description: | Facilitates extraction of geospatial data from the 'Office for National Statistics Open Geography' and 'nomis' Application Programming Interfaces (APIs). Simplifies process of querying 'nomis' datasets <https://www.nomisweb.co.uk/> and extracting desired datasets in dataframe format. Extracts area shapefiles at chosen resolution from 'Office for National Statistics Open Geography' <https://geoportal.statistics.gov.uk/>. |
| Authors: | Andrew Christy [aut, cre], James Macpherson [aut], Hadyn Jenkins [aut], Crown Copyright (Department for Environment Food and Rural Affairs) [cph] |
| Maintainer: | Andrew Christy <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.1 |
| Built: | 2025-02-16 05:31:46 UTC |
| Source: | https://github.com/defra-data-science-centre-of-excellence/sgapi |
Evaluate condition and return error message if condition not satisfied.
assert_function(condition, msg)assert_function(condition, msg)
condition |
a logical expresssion (e.g. is.null(test_variable)) |
msg |
the error message returned if the condition is not met. |
No return value, called for side effects.
assert_function(1==2,"Incorrect inequality")assert_function(1==2,"Incorrect inequality")
A list of the available boundary layers that the Office for National Statistics (ONS) has for ArcGIS queries
availableBoundariesavailableBoundaries
A list of with 3348 rows and 1 variable:
name of boundary table within 'ONS Open geography'
availableBoundaries.rda
Retrieve available spatial scales for a given 'nomis' table id. This is useful as each table only has data at a specific set of scales, e.g. many census tables are available at MSOA and LSOA resolutions but not at Regional level.
get_available_scales(id)get_available_scales(id)
id |
A valid 'nomis' table id given as a string. |
A tidy dataframe listing the geographical scales available for the 'nomis' table selected.
get_available_scales(id="NM_1003_1")get_available_scales(id="NM_1003_1")
Retrieve boundaries from the Office for National Statistics (ONS) 'ONS Geography Portal' given a valid boundary name and layer name. If the submitted geometry is outwith the ONS Boundary, e.g. the geometry is in France, the function will return an empty shape file.
get_boundaries(boundary, geometry_filter = NULL)get_boundaries(boundary, geometry_filter = NULL)
boundary |
A valid ONS boundary name given as a string. |
geometry_filter |
geospatial shape or point (using latitude and longitude). Currently limited to a rectangular box or dropped pin. |
An sf object for all constituencies in the geospatial area submitted through the geometry_filter, at the chosen ONS Boundary.
## Not run: get_boundaries(boundary="MSOA_Dec_2011_Boundaries_Generalised_Clipped_BGC_EW_V3_2022", geometry_filter="-1.282825,52.354169,0.206626,52.7106") ## End(Not run)## Not run: get_boundaries(boundary="MSOA_Dec_2011_Boundaries_Generalised_Clipped_BGC_EW_V3_2022", geometry_filter="-1.282825,52.354169,0.206626,52.7106") ## End(Not run)
Extract a geojson shapefile of the chosen areas at the user-selected resolution.
get_boundaries_areaname(boundary,col_name_var,chosen_constituency_list)get_boundaries_areaname(boundary,col_name_var,chosen_constituency_list)
boundary |
The resolution of constituencies, e.g. Census Output Areas or Westminster Constituencies. Available boundaries can be found here: https://geoportal.statistics.gov.uk/ |
col_name_var |
The name of the datafield where the constituency name is held, e.g. PCON22NM for 2022 Parliamentary Constituencies. |
chosen_constituency_list |
List of chosen constituencies. |
An sf object of the constituencies submitted to the function. If there are no constituencies, return is NULL.
get_boundaries_areaname(boundary="Local_Authority_Districts_December_2022_UK_BGC_V2", col_name_var="LAD22NM",chosen_constituency_list=c("Westminster","Tower Hamlets","County Durham"))get_boundaries_areaname(boundary="Local_Authority_Districts_December_2022_UK_BGC_V2", col_name_var="LAD22NM",chosen_constituency_list=c("Westminster","Tower Hamlets","County Durham"))
Function to return dataframe of all 'nomis' tables, and their corresponding codes and descriptions, which have the chosen keyword.
get_keyword_table_id(usr_keyword)get_keyword_table_id(usr_keyword)
usr_keyword |
Keyword to search 'nomis' tables for, e.g. "religion", "employment", "housing" |
A tidy dataframe of all nomis tables and their ids, which contain the chosen keyword.
get_keyword_table_id(usr_keyword="passports")get_keyword_table_id(usr_keyword="passports")
Retrieve dataset overview for a valid 'nomis' table id. Returned object includes description of the dataset, last update date, contact for the data. It also extracts all of the available instances of the available table dimensions, which can then be used to filter the dataset 'nomis' table.
get_overview(id)get_overview(id)
id |
A valid 'nomis' id. |
An object with overview information of chosen data set. Object has the structure of the extracted JSON object.
get_overview(id="NM_1_1")get_overview(id="NM_1_1")
Retrieve dataset for a valid 'nomis' table id and dimension. This extracts all of the available instances of the chosen dimension, which can then be used to filter the 'nomis' table.
get_structure(id, dim)get_structure(id, dim)
id |
A valid 'nomis' id. |
dim |
The name of the g which dimension is queried. |
An object with JSON structure for the chosen dimension of the selected 'nomis' table.
get_structure(id="NM_187_1",dim="industry")get_structure(id="NM_187_1",dim="industry")
Retrieve a 'nomis' table, containing the columns of interest, using a given table ID. Option to apply filters to the query, and to circumnavigate the limit on number of rows returned using your 'nomis' uid.
get_table(id, options, selection = NULL, uid = NULL)get_table(id, options, selection = NULL, uid = NULL)
id |
a table ID recognised by 'nomis' (e.g. "NM_1_1") |
options |
a list of paramaters to pass to the API query. |
selection |
a vector of column names to return. NULL returns all. Defaults to NULL. |
uid |
Unique 'nomis' identifier to enable larger 'nomis' queries - https://www.nomisweb.co.uk/. Defaults to NULL. |
A tidy dataframe of selected 'nomis' table with the selected parameters and user filters applied.
get_table(id="NM_1_1", options = list("geography" = "TYPE480", "time" = "latest")) get_table(id="NM_1002_1", options = list("geography" = "TYPE265", "time" = "latest"), selection = "GEOGRAPHY_NAME,C_AGE_NAME,OBS_VALUE",uid=NULL)get_table(id="NM_1_1", options = list("geography" = "TYPE480", "time" = "latest")) get_table(id="NM_1002_1", options = list("geography" = "TYPE265", "time" = "latest"), selection = "GEOGRAPHY_NAME,C_AGE_NAME,OBS_VALUE",uid=NULL)
Extract dimensions available for a given 'nomis' table ID. e.g. the dimensions of the table 'RM011 - Country of birth by age ' are age, country and geography; this function will return all of the available age, country and geography filters available on the table.
get_table_dimensions(id)get_table_dimensions(id)
id |
A table ID recognised by 'nomis' (e.g "NM_1_1"). |
A tidy dataframe of the dimensions, and available filtering values, of your chosen 'nomis' table.
get_table_dimensions(id="NM_1240_1")get_table_dimensions(id="NM_1240_1")
Extract unique table ids for 'nomis' tables containing given name in their title, these unique table ids can be used to rapidly query census data in other functions e.g. 'get_overview("NM_102_1")'
get_table_id(name)get_table_id(name)
name |
A string to search for within 'nomis' table titles. |
A dataframe of 'nomis' table codes and names, as strings, for all 'nomis' tables containing the selected 'name' in their title.
get_table_id(name="employment")get_table_id(name="employment")
Retrieve summary information about a given 'nomis' dataset. This is useful as it provides the description of the dataset and any caveats. It also returns information about the current status of the data, and when it was last updated.
get_table_info_brief(id)get_table_info_brief(id)
id |
A valid 'nomis' table id given as a string, e.g. NM_46_1. |
A json file containing the DatasetInfo, DatasetMetadata, Dimensions (variables), Dataset Contact, Units from the target 'nomis' table.
get_table_info_brief(id="NM_1_1")get_table_info_brief(id="NM_1_1")
Extract a lookup table between two boundary scales from 'ONS Open Geography' portal, e.g. get a lookup between Regions and Parliamentary constituencies.
get_table_link_lookup( lookup_table, col_name_1, col_name_2, col_name_3, col_name_4 )get_table_link_lookup( lookup_table, col_name_1, col_name_2, col_name_3, col_name_4 )
lookup_table |
A valid ONS lookup table |
col_name_1 |
Field in ONS table containing the constituency code of the smaller scale resolution. |
col_name_2 |
Field in ONS table containing the constituency code of the larger scale resolution. |
col_name_3 |
Field in ONS table containing the constituency name of the smaller scale resolution. |
col_name_4 |
Field in ONS table containing the constituency name of the larger scale resolution. |
A tidy dataframe, providing a lookup between two chosen boundary resolutions.
## Not run: get_table_link_lookup(lookup_table="LAD22_CTY22_EN_LU",col_name_1="LAD22CD", col_name_2="CTY22CD",col_name_3="LAD22NM",col_name_4="CTY22NM") ## End(Not run)## Not run: get_table_link_lookup(lookup_table="LAD22_CTY22_EN_LU",col_name_1="LAD22CD", col_name_2="CTY22CD",col_name_3="LAD22NM",col_name_4="CTY22NM") ## End(Not run)
Retrieve all available ArcGIS boundary layers from the 'ONS Open Geography Portal'.
list_boundaries()list_boundaries()
A vector of available boundary layers on 'ONS Open Geography'.
Return a list of the data sources available on 'nomis'.
Returns a list including the name, id and description of each data source available on 'nomis'. More information can be found here: https://www.nomisweb.co.uk/api/v01/help
list_data_sources()list_data_sources()
A tidy dataframe of all available data sources accessible through the 'nomis' API system.
list_data_sources()list_data_sources()
List all available datasets on 'nomis'. User can then use the items on this list to query 'nomis' data.
list_tables(base_url = "https://www.nomisweb.co.uk/api/v01/")list_tables(base_url = "https://www.nomisweb.co.uk/api/v01/")
base_url |
Url of the API from which the available tables are listed. |
A tidy dataframe containing the name and ID of each table available on 'nomis'.
Lookup table providing ONS and 'nomis' references for a given ONS boundary layer. The variables are as follows:
lookuplookup
A data frame with 30 rows and 4 variables:
boundary layer, written in interpretable manner
corresponding boundary layer in the format that the 'ONS Open Geography' API will interpret
corresponding boundary layer in the format that the 'nomis' API will interpret
lookup file containing the constituency names and codes of the boundary layer
lookup.rda
A dataset containing the available tables, codes and sources of data available on 'nomis'. The variables are as follows:
nomisTablesnomisTables
A data frame with 1605 rows and 3 variables:
name of dataset
code corresponing to dataset
source of dataset
nomisTables.rda
A dataset containing the available tables on 'nomis', and the boundary layers at which this data is held, e.g. demographic information may only be held in the Census output areas and not NHS regions. The variables are as follows:
scalesForEachDatasetscalesForEachDataset
A data frame with 22564 rows and 3 variables:
name of boundary layer
type of data
nomis code for the table
scalesForEachDataset.rda