diff --git a/.Renviron.example b/.Renviron.example index 2ec62af..dfb7bdd 100644 --- a/.Renviron.example +++ b/.Renviron.example @@ -3,4 +3,4 @@ # (You can alternatively add these values to your global `.Renviron` but they # might be more appropriately kept as project-specific values.) # Contact a member of SU Data Science to get the required values for these. -AZ_STORAGE_EP = +AZ_STORAGE_EP=[your azure blob storage endpoint url] diff --git a/README.md b/README.md index 26c5085..caa4695 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,22 @@ # reskit ![R](https://www.r-project.org/favicon-32x32.png) 📦🍪🦺 -![GitHub License][gh_licence] -[![Project Status: WIP – Initial development is in progress, but there -has not yet been a stable release][repostatus_svg]][repostatus_info] -[![Lifecycle: experimental][lifecycle_svg]][lifecycle] +[![License: MIT][mit_svg]](https://opensource.org/licenses/MIT) +[![Project Status: Active – The project has reached a stable, usable state and +is being actively developed][repostatus_svg]][repostatus_info] ![GitHub R package version][gh_ver] - -[gh_licence]: https://img.shields.io/github/license/The-Strategy-Unit/nhp_reskit -[gh_ver]: https://img.shields.io/github/r-package/v/The-Strategy-Unit/nhp_reskit -[repostatus_info]: https://www.repostatus.org/#wip -[repostatus_svg]: https://www.repostatus.org/badges/latest/wip.svg -[lifecycle]: https://lifecycle.r-lib.org/articles/stages.html#experimental -[lifecycle_svg]: https://img.shields.io/badge/lifecycle-experimental-orange.svg +[![R CMD check status][cmd_svg]][cmd_yaml] + +[mit_svg]: https://img.shields.io/badge/License-MIT-yellow.svg?label=licence +[repostatus_svg]: https://www.repostatus.org/badges/latest/active.svg +[repostatus_info]: https://www.repostatus.org/#active +[gh_ver]: https://img.shields.io/github/r-package/v/The-Strategy-Unit/azkit?logo=r&label=version +[cmd_svg]: https://github.com/The-Strategy-Unit/nhp_reskit/actions/workflows/R-CMD-check.yaml/badge.svg?event=release +[cmd_yaml]: https://github.com/The-Strategy-Unit/nhp_reskit/actions/workflows/R-CMD-check.yaml -An R package (just called `{reskit}`) helping process NHP model results. - -## Status +An R package (just called `reskit`) that helps process NHP model results. -This is just a framework repository at present, while the package scope and -design are being explored. -This README will be fleshed out as the package is developed. ## Installation @@ -37,36 +32,73 @@ already installed in order to install reskit. ## Usage -You will need certain environment variables to be available (see section below). +As this package relies on [`{azkit}`][azk] for some of its functionality, you +will need certain environment variables to be available (see section below) in +order for these to work. + +It is a good idea to check that your [azkit authentication][azkt] is set up +correctly before using this package. +Try: + +``` +az login +``` + +at your terminal, or + +```r +azkit::get_auth_token() +``` + +to check these are running correctly. + +### Examples of usage Some key functions and workflows you might want to use include: + +1. Use {azkit} to access an Azure data container, and read in all results +parquet files from a specific location on that container: + ```r -# Compiles a table of metadata for each model run for each scheme -compile_run_metadata_tbl() +# This assumes you have Azure authentication working, and the correct +# Azure endpoint variables in your environment. +# NB the file/data locations used here are invented examples. +# The best way to obtain a real results folder location is probably to read and +# filter a table of model runs metadata and extract the appropriate path +# variable; see `azkit::read_azure_table` for help with this. +data_container <- azkit::get_container("data_container") +results_location <- "results/dev/national/test" +results <- reskit::read_results_parquet_files(data_container, results_location) +``` + +This should return a named list of tibbles, stored as `results`, one for each +parquet file in the results location folder. -# Get the Azure storage container for results data -get_results_container() # uses the environment variable "AZ_RESULTS_CONTAINER" +2. Re-using some of the variables above, you could instead retrieve data for +just some of the parquet files: -# Return a vector of provider codes from the supporting data container -get_providers() # requires the environment variable "AZ_SUPPORT_CONTAINER" +```r +# NB do not add the `.parquet` ext; just the basename of the file is required +selected_tables <- c("acuity", "default") -# Get the path to a folder of results data -# (the below example will succeed only if there is a single scenario and a -# single model run within the particular version and scheme combination below) -get_results_dir_path(version = "v4.0", scheme = "national", scenario = "test") +selected_results <- data_container |> + reskit::read_results_parquet_files(results_location, selected_tables) +``` -# Read all parquet data files from a location -results_dir <- get_results_dir_path(version = "v4.0", scheme = "national") -read_results_parquet_files(results_dir) +3. You can use your results list to support the creation of summary tables and +charts. For example: -# Read only selected results files from multiple scenarios -c("scenario1", "scenario2") |> - purrr::map(\(x) get_results_dir_path("v3.6", "RZZ", scenario = x)) |> - purrr::map(\(x) read_results_parquet_files(x, files = c("default", "age"))) +```r +# generates a {gt} (HTML) table +reskit::compile_principal_pod_data(results) |> + reskit::make_principal_pod_table() ``` +See the "Plots and tables with reskit" vignette for more examples of things you +can do. + ## Environment variables To access Azure Storage you need to add some variables to a @@ -81,15 +113,15 @@ Your `.Renviron` file should contain the variables below. Ask a member of [the Data Science team][suds] for the necessary values. ``` -AZ_STORAGE_EP = -AZ_SUPPORT_CONTAINER = -AZ_RESULTS_CONTAINER = -AZ_RESULTS_DIRECTORY = +AZ_STORAGE_EP=[your azure storage blob endpoint url] +AZ_TABLE_EP=[your azure storage table endpoint url] ``` -An example `.Renviron.example` file is provided in this repository. -Copy it, renamed as just `.Renviron`, into the root of any project folder where -you are using {reskit}. +For convenience, an example `.Renviron.example` file is provided in this +repository. +You can copy/save it, renamed to just `.Renviron`, to the root of any project +folder where you are using {reskit}. + ## Getting help @@ -99,6 +131,8 @@ or problems, including with the package documentation. Alternatively, to ask any questions about the package you may contact [Fran Barton](mailto:francis.barton@nhs.net). +[azk]: https://the-strategy-unit.github.io/azkit/ +[azkt]: https://the-strategy-unit.github.io/azkit/articles/troubleshooting.html [posit_env]: https://docs.posit.co/ide/user/ide/guide/environments/r/managing-r.html#renviron [github]: https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files [suds]: https://the-strategy-unit.github.io/data_science/about.html