dwp_get_data: Submit and receive table queries

In evanodell/dwpstat: Access 'Stat-Xplore' data on the UK benefits system

Description

Table queries contain the actual data from the DWP database. Due to the complexity of the API data being returned, and to preserve the flexibility of the API query, the API return is not processed into a data frame but is preserved as a list.

Usage

dwp_get_data(database, measures, column, row = NULL, wafer = NULL, ...)

Arguments

database	The ID of the database to query, as a single string. Must be specified.
measures	A character vector of fields to return measures for. Also accepts a string if one measure is being queried. Must be specified.
column	A character vector of fields for the column dimension. Also accepts a string if one measure is being queried. Must be specified.
row	A character vector of fields for the row dimension. Also accepts a string if one measure is being queried. Defaults to NULL.
wafer	A character vector of fields for the wafter dimension. Also accepts a string if one measure is being queried. Defaults to NULL.
...	For recode vector. Not in use.

Details

Returns a list of 6 levels. The descriptions of what each level contains are adapted from the API documentation.

Value

A list of six levels:

1. queryThe query submitted to the API, including the database used, the measures requested, the dimensions (row, column, wafer), and the record request.

2. database Details on the database queried. Contains two vectors:

   • id The ID of this dataset

   • annotationKeys An array of keys to annotations for the dataset. If there are annotations available, their descriptions will be in the annotationMap object.

3. fieldsDetails of the fields being queried.

   • uri Field ID, or Open Data ID, as returned by dwp_schema().

   • label The display name for given measure, as displayed in Stat-Xplore.

   • items An array with the field values returned for each field:

     • type The field type. The RecodeItem, if applicable.

     • labels Display name(s) for the given field item. If recodes are used, this will contain labels for each created field value.

     • annotationKeys An array of keys to annotations for the dataset. If there are annotations available, their descriptions will be in the annotationMap object.

     • uris Field ID, or Open Data ID, as returned by dwp_schema().

   • annotationKeys An array of keys to annotations for the dataset. If there are annotations available, their descriptions will be in the annotationMap object.

4. measures An array containing all the measures (summation options) returned for the query. For each measure, the API returns: - uri Field ID, or Open Data ID, as returned by dwp_schema(). - label The display name for the given measure, as displayed in Stat-Xplore.

5. cubes An array containing the API query results. There will be one item in the array for each requested measure. Each item specifies a measure, with the values for each cell in the cube for the given measure.

6. annotationMap The annotations applicable to this query. If there are annotations for the dataset or its fields, the annotation keys and descriptions will be returned here.

Examples

## Not run: 
# A complex query
x <- dwp_get_data(database = "str:database:ESA_Caseload",
                  measures = "str:count:ESA_Caseload:V_F_ESA",
                  column = c("str:field:ESA_Caseload:V_F_ESA:CCSEX",
                             "str:field:ESA_Caseload:V_F_ESA:CTDURTN"),
                  row = "str:field:ESA_Caseload:V_F_ESA:ICDGP",
                  wafer = "str:field:ESA_Caseload:V_F_ESA:IB_MIG")

# A more straightforward query returning the number of PIP recipients in
# the most recent month, split by sex
z <- dwp_get_data(database = "str:database:PIP_Monthly",
                  measures = "str:count:PIP_Monthly:V_F_PIP_MONTHLY",
                  column = "str:field:PIP_Monthly:V_F_PIP_MONTHLY:SEX")

## End(Not run)

evanodell/dwpstat documentation built on Feb. 14, 2020, 3:54 p.m.