From 83ea8bb58192f52addb1e697f8c33f194438320e Mon Sep 17 00:00:00 2001 From: rmgpanw Date: Wed, 15 May 2024 23:11:40 +0100 Subject: [PATCH] update examples to use item 394; add footnote to README on finding an item release number from its URL --- R/download_item.R | 11 ++++++++-- R/get_item_metadata.R | 8 +++++-- README.Rmd | 14 ++++++------ README.md | 46 ++++++++++++++++++++++++++++++---------- man/download_item.Rd | 11 ++++++++-- man/get_item_metadata.Rd | 8 +++++-- 6 files changed, 73 insertions(+), 25 deletions(-) diff --git a/R/download_item.R b/R/download_item.R index 12e9a3f..511da39 100644 --- a/R/download_item.R +++ b/R/download_item.R @@ -23,11 +23,18 @@ #' #' @examples #' \dontrun{ -#' # Download NHS Continuing Health Care (CHC) Data Set - JSON Schema -#' x <- download_item(1760, directory = tempdir()) +#' # Download Community Services Data Set pre-deadline extract XML Schema +#' x <- download_item(394, directory = tempdir()) #' #' # List downloaded files #' unzip(x, list = TRUE) +#' +#' # Download a previous release +#' release <- get_item_metadata(394)$releases[[2]]$id +#' +#' y <- download_item(394, directory = tempdir(), release = release) +#' +#' unzip(y, list = TRUE) #' } download_item <- function(item, directory = ".", diff --git a/R/get_item_metadata.R b/R/get_item_metadata.R index 80efe88..059b79e 100644 --- a/R/get_item_metadata.R +++ b/R/get_item_metadata.R @@ -12,8 +12,12 @@ #' #' @examples #' \dontrun{ -#' # Get metadata for NHS Continuing Health Care (CHC) Data Set - JSON Schema -#' get_item_metadata(1760) |> +#' # Get metadata for Community Services Data Set pre-deadline extract XML Schema +#' get_item_metadata(394) |> +#' purrr::map_at("releases", \(release) purrr::map(release, names)) +#' +#' # Include metadata for any previous releases using `latest_only = FALSE` +#' get_item_metadata(394, latest_only = FALSE) |> #' purrr::map_at("releases", \(release) purrr::map(release, names)) #' } get_item_metadata <- function(item, diff --git a/README.Rmd b/README.Rmd index 26fe502..dd57ce1 100644 --- a/README.Rmd +++ b/README.Rmd @@ -34,12 +34,14 @@ devtools::install_github("rmgpanw/trud") You will also need to: -- [Sign up for an account](https://isd.digital.nhs.uk/trud/users/guest/filters/0/account/form) with NHS TRUD -- Set your API key (shown on your account information page) as an environmental variable named `TRUD_API_KEY`. The best way to do this is by placing your API key in a [`.Renviron` file](https://rstats.wtf/r-startup.html#renviron). +- [Sign up for an account](https://isd.digital.nhs.uk/trud/users/guest/filters/0/account/form) with NHS TRUD +- Set your API key (shown on your account information page) as an environmental variable named `TRUD_API_KEY`. The best way to do this is by placing your API key in a [`.Renviron` file](https://rstats.wtf/r-startup.html#renviron). ## Examples -Retrieve available endpoints: +Retrieve available endpoints[^1]: + +[^1]: Item numbers can also be found in the URLs of releases pages, between `items` and `releases`. For example, the URL for the [Community Services Data Set pre-deadline extract XML Schema](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases) releases page is `https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases` and the item number is `394`. ```{r trud-items} library(trud) @@ -50,14 +52,14 @@ trud_items() Get metadata for an item: ```{r get-item-metadata} -get_item_metadata(1760) |> +get_item_metadata(394) |> purrr::map_at("releases", \(release) purrr::map(release, names)) ``` Download an item: ```{r download-item} -# by default this will be downloaded to the current working directory -x <- download_item(1760, directory = tempdir()) +# by default the latest release will be downloaded to the current working directory +x <- download_item(394, directory = tempdir()) unzip(x, list = TRUE) ``` diff --git a/README.md b/README.md index bc093e9..c510656 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ You will also need to: ## Examples -Retrieve available endpoints: +Retrieve available endpoints[^1]: ``` r library(trud) @@ -61,13 +61,25 @@ trud_items() Get metadata for an item: ``` r -get_item_metadata(1760) |> +get_item_metadata(394) |> purrr::map_at("releases", \(release) purrr::map(release, names)) #> $apiVersion #> [1] "1" #> #> $releases -#> $releases$CHC_JSON_v1.0.2.zip +#> $releases$CSDS_Provpredextract_1.6.6_20221115000001.zip +#> [1] "id" "name" +#> [3] "releaseDate" "archiveFileUrl" +#> [5] "archiveFileName" "archiveFileSizeBytes" +#> [7] "archiveFileSha256" "archiveFileLastModifiedTimestamp" +#> [9] "checksumFileUrl" "checksumFileName" +#> [11] "checksumFileSizeBytes" "checksumFileLastModifiedTimestamp" +#> [13] "signatureFileUrl" "signatureFileName" +#> [15] "signatureFileSizeBytes" "signatureFileLastModifiedTimestamp" +#> [17] "publicKeyFileUrl" "publicKeyFileName" +#> [19] "publicKeyFileSizeBytes" "publicKeyId" +#> +#> $releases$DMDSSCHEMAS_1.5.21_20200805000001 #> [1] "id" "name" #> [3] "releaseDate" "archiveFileUrl" #> [5] "archiveFileName" "archiveFileSizeBytes" @@ -90,14 +102,26 @@ get_item_metadata(1760) |> Download an item: ``` r -# by default this will be downloaded to the current working directory -x <- download_item(1760, directory = tempdir()) -#> ⠙ Downloading archive file for TRUD item 1760... -#> ✔ Successfully downloaded `CHC_JSON_v1.0.2.zip` to '/var/folders/zt/jltqykf54y3… +# by default the latest release will be downloaded to the current working directory +x <- download_item(394, directory = tempdir()) +#> ⠙ Downloading archive file for TRUD item 394... +#> ✔ Successfully downloaded `CSDS_Provpredextract_1.6.6_20221115000001.zip` to '/… #> unzip(x, list = TRUE) -#> Name Length Date -#> 1 JSON_CHC_V1_0_2_Simple_Schema_v1.1.json 14224 2022-01-27 12:01:00 -#> 2 JSON_CHC_V1_0_2_Simple_Schema_SAMPLE_DATA.json 5492 2022-01-27 14:23:00 -#> 3 CHC Production Log - JSON SIMPLE.xlsx 21520 2022-01-27 14:33:00 +#> Name Length +#> 1 CSDS_ProvPreExtract__V1_6_6_SAMPLE_XML.xml 7887 +#> 2 CSDS_ProvPreExtract__V1_6_6_FinalV1.XSD 75650 +#> 3 CSDS ProvPreDExtract v1.6.6 Production Log v0.1.xlsx 32216 +#> Date +#> 1 2022-11-15 12:48:00 +#> 2 2022-10-31 11:36:00 +#> 3 2022-11-15 11:57:00 ``` + +[^1]: Item numbers can also be found in the URLs of releases pages, + between `items` and `releases`. For example, the URL for the + [Community Services Data Set pre-deadline extract XML + Schema](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases) + releases page is + `https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases` + and the item number is `394`. diff --git a/man/download_item.Rd b/man/download_item.Rd index 6e1b50a..6364f89 100644 --- a/man/download_item.Rd +++ b/man/download_item.Rd @@ -43,10 +43,17 @@ default this is the latest release. } \examples{ \dontrun{ - # Download NHS Continuing Health Care (CHC) Data Set - JSON Schema - x <- download_item(1760, directory = tempdir()) + # Download Community Services Data Set pre-deadline extract XML Schema + x <- download_item(394, directory = tempdir()) # List downloaded files unzip(x, list = TRUE) + + # Download a previous release + release <- get_item_metadata(394)$releases[[2]]$id + + y <- download_item(394, directory = tempdir(), release = release) + + unzip(y, list = TRUE) } } diff --git a/man/get_item_metadata.Rd b/man/get_item_metadata.Rd index 37d5b5f..bf8e8de 100644 --- a/man/get_item_metadata.Rd +++ b/man/get_item_metadata.Rd @@ -25,8 +25,12 @@ pertaining to the specified NHS TRUD item. } \examples{ \dontrun{ - # Get metadata for NHS Continuing Health Care (CHC) Data Set - JSON Schema - get_item_metadata(1760) |> + # Get metadata for Community Services Data Set pre-deadline extract XML Schema + get_item_metadata(394) |> + purrr::map_at("releases", \(release) purrr::map(release, names)) + +# Include metadata for any previous releases using `latest_only = FALSE` +get_item_metadata(394, latest_only = FALSE) |> purrr::map_at("releases", \(release) purrr::map(release, names)) } }