diff --git a/DESCRIPTION b/DESCRIPTION index dace40c..3bb430e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -61,6 +61,7 @@ Imports: Suggests: covr, devtools, + nhp.inputs.selection.app, mockery, rcmdcheck, rsconnect, @@ -69,7 +70,8 @@ Suggests: usethis, watcher Remotes: - github::the-strategy-unit/azkit + github::the-strategy-unit/azkit, + nhp.inputs.selection.app=github::the-strategy-unit/nhp_inputs_selection_app Config/testthat/edition: 3 Encoding: UTF-8 Language: en-GB diff --git a/README.Rmd b/README.Rmd index 5917751..9d5d415 100644 --- a/README.Rmd +++ b/README.Rmd @@ -38,7 +38,7 @@ The guidance below is for the members of [the Strategy Unit's Data Science team] ### Structure -Technically there are two apps: the main app in the `main` branch, and the inputs selection app (where users start or edit a scenario) in the `inputs_selection_app` branch. +Technically there are two apps: the main app in the `main` branch, and the [inputs selection app](https://github.com/The-Strategy-Unit/nhp_inputs_selection_app) (where users start or edit a scenario). Users arrive at the selection app before being routed to the main app. Both apps are built with [Shiny](https://shiny.posit.co/) and the main app uses the [the {golem} package](https://thinkr-open.github.io/golem/). @@ -50,30 +50,12 @@ Run the app locally on your machine to test that your changes work as expected. #### Setup -First, install the required packages listed in the DESCRIPTION with `pak::local_install_deps(dependencies = TRUE)`. +First, install the required packages listed in the DESCRIPTION with `pak::local_install_dev_deps(dependencies = TRUE)`. Then add an `.Renviron` file to the project root that contains the required environment variables. Copy into it the required variables, which are listed in the `.Renviron.example`. You can get the values you need from a member of the Data Science team. -Then, from the `main` branch (or your development branch of it), use Git's `worktree` function to put the `inputs_selection_app` branch (or your development branch of it) in its own subfolder. - -In the terminal: - -``` -git fetch origin inputs_selection_app -git worktree add inputs_selection_app inputs_selection_app -``` - -The first argument is the name of the folder in which to put the branch content. -If you want a development version of the inputs selection app, you can specify the branch name as the second of the arguments to `git worktree add`. - -If you need to remove the selection-app folder at any point, you can terminate the background job (if running) and in the terminal run: - -``` -git worktree remove inputs_selection_app -``` - #### Run the app Once setup, we can run the app. diff --git a/README.md b/README.md index bda5d75..c647fba 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,141 @@ - - - -# NHP Inputs - - - -[![Project Status: Active – The project has reached a stable, usable -state and is being actively -developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![check](https://github.com/The-Strategy-Unit/nhp_inputs/actions/workflows/check.yaml/badge.svg)](https://github.com/The-Strategy-Unit/nhp_inputs/actions/workflows/check.yaml) - - -## About - -A web app to input the parameters needed to run scenarios through the -New Hospital Programme (NHP) demand model. - -The app is [deployed to Posit -Connect](https://connect.strategyunitwm.nhs.uk/nhp/inputs/). You must -have an account and sufficient permissions to view it. - -Results can then be viewed in [the outputs -app](https://connect.strategyunitwm.nhs.uk/nhp/outputs/), which is -generated from the -[nhp_outputs](https://github.com/The-Strategy-Unit/nhp_outputs) -repository. - -You can find more information on [the NHP model project information -site](https://connect.strategyunitwm.nhs.uk/nhp/project_information/), -including [a -diagram](https://connect.strategyunitwm.nhs.uk/nhp/project_information/project_plan_and_summary/components-overview.html) -of how the components of the modelling process fit together. - -## For developers - -The app is built and maintained by members of [the Strategy Unit’s Data -Science team](https://the-strategy-unit.github.io/data_science/). - -### Structure - -Technically there are two apps: the main app in the `main` branch, and -the inputs selection app (where users start or edit a scenario) in the -`inputs_selection_app` branch. Users arrive at the selection app before -being routed to the main app. - -Both apps are built with [Shiny](https://shiny.posit.co/) and the main -app uses the [the {golem} -package](https://thinkr-open.github.io/golem/). Server and UI modules -can be found in `R/`, configuration in `inst/golem-config.yml` and -supporting data and text in `inst/app/`. - -Packages used in the app are listed in `DESCRIPTION`, and can be -installed with `devtools::install_deps(dependencies = TRUE)`. - -### Run locally - -Run the app locally on your machine to test that your changes work as -expected. - -To prepare, add an `.Renviron` file to the project root that contains -the required environment variables. There is an `.Renviron.example` file -which describes the required variables. You can get these from a member -of the Data Science team. - -Then, from the `main` branch (or your development branch of it), use -Git’s `worktree` function to put the `inputs_selection_app` branch (or -your development branch of it) in its own subfolder. - -In the terminal: - - git fetch origin inputs_selection_app - git worktree add inputs_selection_app inputs_selection_app - -If you want a development version of the inputs selection app, you can -specify the branch name as the second of the arguments to -`git worktree add`. - -To run the app from RStudio, start up the selection app by opening the -`dev/watch.R` script, go to the ‘Background Jobs’ tab of the console -pane and click the ‘Start Background Job’ button. In the ‘Run Script as -Background Job’ dialog box select the project root as the ‘Working -Directory’, then hit ‘Start’. When ready, the app will tell you to visit -`http://127.0.0.1:9081/` in your browser. - -Note that your selections in the app remain local to you and the -resulting json file of parameters for your scenario will live in your -local `params/development/` directory. These scenarios will be -selectable and editable in future from your locally-run inputs selection -app. - -If you need to remove the selection-app folder at any point, you can -terminate the background job (if running) and in the terminal run: - - git worktree remove inputs_selection_app - -### Test in dev - -During pre-release QA we test both apps on the server. This helps us -spot any issues that are server-specific and might be overlooked if -running the apps locally. - -To test the unreleased app in our development environment: - -1. Merge any PRs you want to test into the `main` branch. -2. If you’ve changed any dependencies, run `dev/generate_manifest.R` to - update `manifest.json`. -3. If you’ve made any changes to the inputs selection app, run the - manual `deploy()` call under the ‘development’ heading in the - `deploy.R` script in your selection app development branch. - -When using the dev inputs selection app on Connect, make sure to set the -‘Model Version’ dropdown to ‘dev’ in the expandable ‘Advanced Options’ -box. That way you’ll be taken to the dev inputs app when you hit -‘Start’. - -### Data extraction - -The app displays trust-specific data to users. The data is processed via -Databricks scripts in [the nhp_data -repository](https://github.com/The-Strategy-Unit/nhp_data) and stored in -Azure storage. - -### Deployment - -Deployment is controlled by GitHub Actions, where: - -- pushes to the `main` branch redeploy the app to /nhp/dev/inputs/ for - purposes of quality assurance -- tagged releases trigger a new deployment to /nhp/vX-Y/inputs/, where - ‘vX-Y’ is the current version (note the hyphen) + + + +# NHP Inputs + + + +[![Project Status: Active – The project has reached a stable, usable +state and is being actively +developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![check](https://github.com/The-Strategy-Unit/nhp_inputs/actions/workflows/check.yaml/badge.svg)](https://github.com/The-Strategy-Unit/nhp_inputs/actions/workflows/check.yaml) + + +## About + +A web app to input the parameters needed to run scenarios through the +New Hospital Programme (NHP) demand model. + +The app is [deployed to Posit +Connect](https://connect.strategyunitwm.nhs.uk/nhp/inputs/). You must +have an account and sufficient permissions to view it. + +Results can then be viewed in [the outputs +app](https://connect.strategyunitwm.nhs.uk/nhp/outputs/), which is +generated from the +[nhp_outputs](https://github.com/The-Strategy-Unit/nhp_outputs) +repository. + +You can find more information on [the NHP model project information +site](https://connect.strategyunitwm.nhs.uk/nhp/project_information/), +including [a +diagram](https://connect.strategyunitwm.nhs.uk/nhp/project_information/project_plan_and_summary/components-overview.html) +of how the components of the modelling process fit together. + +## For developers + +The guidance below is for the members of [the Strategy Unit’s Data +Science team](https://the-strategy-unit.github.io/data_science/), who +built and maintain this app. + +### Structure + +Technically there are two apps: the main app in the `main` branch, and +the [inputs selection +app](https://github.com/The-Strategy-Unit/nhp_inputs_selection_app) +(where users start or edit a scenario). Users arrive at the selection +app before being routed to the main app. + +Both apps are built with [Shiny](https://shiny.posit.co/) and the main +app uses the [the {golem} +package](https://thinkr-open.github.io/golem/). Server and UI modules +can be found in `R/`, configuration in `inst/golem-config.yml` and +supporting data and text in `inst/app/`. + +### Run locally + +Run the app locally on your machine to test that your changes work as +expected. + +#### Setup + +First, install the required packages listed in the DESCRIPTION with +`pak::local_install_dev_deps(dependencies = TRUE)`. + +Then add an `.Renviron` file to the project root that contains the +required environment variables. Copy into it the required variables, +which are listed in the `.Renviron.example`. You can get the values you +need from a member of the Data Science team. + +#### Run the app + +Once setup, we can run the app. This is done by launching a background +Shiny app and then watching the files for changes, which causes an +auto-reload. The method for doing this depends on your IDE. + +In RStudio: + +1. Open the `dev/watch.R` script and go to the ‘Background Jobs’ tab of + the console pane and click the ‘Start Background Job’ button. +2. Click ‘Start’ after checking that the ‘R Script’ path is + pre-populated with the path to `watch.R` (otherwise select it + yourself). +3. When ready, a message will tell you to visit + `http://127.0.0.1:9081/` in your browser. + +In Positron: run `source('dev/watch.R')` and click the link to the URL +when complete. + +In VS Code: open the command palette +(Ctrl+Shift+P), search for ‘Tasks: Run +Task’, then select ‘R: Run App (watch)’ and finally click the link to +the URL when complete. + +Making selections in the app will cause values to be written to a local +json file, which will live in your local `params/development/` +directory. These scenarios will be selectable and editable in future +from your locally-run inputs selection app. They will not be available +from the deployed app. + +### Test in dev + +During pre-release QA we test both apps on the server. This helps us +spot any issues that are server-specific and might be overlooked if +running the apps locally. + +To test the unreleased app in our development environment: + +1. Merge any PRs you want to test into the `main` branch. +2. If you’ve changed any dependencies, run `dev/generate_manifest.R` to + update `manifest.json`. +3. If you’ve made any changes to the inputs selection app, run the + manual `deploy()` call under the ‘development’ heading in the + `deploy.R` script in your selection-app development branch. + +When using the dev inputs selection app on Connect, make sure to set the +‘Model Version’ dropdown to ‘dev’ in the expandable ‘Advanced Options’ +box. That way you’ll be taken to the dev inputs app when you hit +‘Start’. + +### Data + +The app displays trust-specific data to users. The data is processed via +Databricks scripts in [the nhp_data +repository](https://github.com/The-Strategy-Unit/nhp_data) and stored in +Azure storage. + +If the data updates and you need to invalidate the current cache, you +force a reset by appending `?reset_cache=true` to the app’s canonical +URL at `https://connect.strategyunitwm.nhs.uk/nhp/inputs/` (authorised +devs only). + +### Deployment + +Deployment is controlled by GitHub Actions in `.github/workflows/`, +where: + +- pushes to the `main` branch redeploy the app to /nhp/dev/inputs/ for + purposes of quality assurance +- tagged releases trigger a new deployment to /nhp/vX-Y/inputs/, where + ‘vX-Y’ is the current version (note the hyphen) +- manual deployment is possible with `connect-publish-manual.yaml` diff --git a/dev/watch.R b/dev/watch.R index 34a7991..5656bf9 100644 --- a/dev/watch.R +++ b/dev/watch.R @@ -1,10 +1,7 @@ shiny::devmode() selection_app <- callr::r_bg(\() { - app <- shiny::runApp( - "inputs_selection_app", - port = 9080 - ) + app <- nhp.inputs.selection.app::run_app(port = 9080) print(app) })