📝 Update README

.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]

README.md

@@ -1,27 +1,22 @@
 # reskit ![R](https://www.r-project.org/favicon-32x32.png) 📦🍪🦺
 
 <!-- badges: start -->
-![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
 <!-- badges: end -->
 
-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