nhs-r-community / nhsrwaitinglist

R-package to implement the waiting list management approach described in this paper by Fong et al: https://www.medrxiv.org/content/10.1101/2022.08.23.22279117v1.full-text

NHSRwaitinglist

An R-package to implement the waiting list management approach described in the paper Understanding Waiting Lists Pressures by Fong et al.

Installation

You can install the current version of {name of package} from GitHub with:

# install.packages("remotes")
remotes::install_github("nhs-r-community/NHSRwaitinglist", build_vignettes = TRUE)

Contributing

If you want to learn more about this project, please join the discussion at the NHS-R Community Slack group and the specific channel #managing-waiting-lists.

Please see our guidance on how to contribute.

This project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

The simplest way to contribute is to raise an issue detailing the feature or functionality you would like to see added, or any unexpected behaviour or bugs you have experienced.

Pull-Request workflow

You are welcome to also submit Pull Requests and, as the main branch is protected and won't accept pushes directly even if you have been added to the repository as a member, the workflow will be (from your own forked repository if you are not a member, or a clone of the repository if you are a member):

• Create new branch with a descriptive name
• Commit to the new branch (add code or delete code or make changes)
• Push the commits
• Create a pull-request in GitHub to signal that your work is ready to be merged
• Tag one or more reviewers (@ThomUK and @ChrisMainey) so that your contribution can be reviewed and merged into main

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jacqueline Grout 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

nhsrwaitinglist's Issues

Create pkgdown site and render to github pages

This will give us a link to point people to, and a first worked example using the initial package functions.

Set up CI/CD elements with GitHub actions

Switch on GitHub actions to:

• Build the package, run tests, and CRAN checks

As build progresses:

• Add pkgdown build to actions
• Add linting stage

Long hyperlink breaks pkgdown layout on mobile

We need to shorten the hyperlink in the readme to avoid breaking the mobile layout.

Add sections into function reference page of pkgdown site

The function reference page lists all the functions, which can be clicked to see a rendering of the help files.

These can be grouped into sections with short preambles to make it easier for users to understand the intent of the functions. See the example for {dplyr}'s site, for example. These groups can be declared in _pkgdown.yml.

Provide headings for (1) wl_* functions, (2) simulation, (3) 'building block' functions, etc. What should these groupings be?

Makes sense to wait for the function names to be confirmed before doing this.

Write tests for functions, using testthat framework

Write unit tests for functions, including expected outputs and calculation answers.

Equity in waiting lists

Is there any scope for the package to include or extend to Gini coefficient of inequalities to answer if waiting lists are equitable?

README examples of packages use

Add a couple of small examples from vignette or general use to the README to help users landing on the repo.

Adding metadata, descriptions and examples to the first functions

I've translated Neil's functions into R package format and added Roxygen skeletons. 'Roxygen2' is a package for writing the metadata for your R package. It creates tags for each function, where you can add your text to describe things, then R builds into the package help files. See the example function: here.

This is where we'd like you to get involved:

• Clone the repository on to your machine
• Create a new branch for your changes
• Pick one of the functions in the R folder, and a comment below to show which one you are taking, to reduce any duplication
• Add some description to the metadata tags, and an example (make some numbers up to plug into the function). Definitions can be found in the paper here, or webinar here
• Commit your changes to your branch, and push to changes to GitHub. You may need to set the 'upstream' (tell GitHub how to tie your branch up to a GitHub one), but it should tell you: git push --set up-stream origin branchname changing "branchname" to your branch.
• Go back to the repository on GitHub and make a 'Pull request' (this means you are requesting to merge your changes into the main branch.

If you get stuck on any of it, do ask for help. It's tricky first time round, but we don't make any progress if we don't have a go!

Rename `F` argument

Rename argument the F in thetarget_capacity() function. Related to #29.

Graduating this from the discussion in #10 to a proper issue now that it causes the linter to complain (it's not camel case, technically, and also has the connotation of FALSE).

Possibilities mentioned in the discussion by @ThomUK:

• capacity_variability
• capacity_variance (could be confused with variance)
• variability_factor

Pass check following addition of lint

Add .lintr to .Rbuildignore and add commented line to example in queue_load() function docs. Cleans up aftermath of #47.

Fixed synthetic data set

From the catch up on 12th April 2024 we discussed a fixed synthetic dataset which would complement the issue #23 and was also discussed in relation to the {NHSRdatasets} package.

Points to consider are if this should be a standalone data set if it's generalised enough and could be used for other example analysis and if that is the case, whether that go into the existing {NHSRdatasets} package or its own. A data set that's very specific to the examples of this package would suggest it's better placed here rather than somewhere else that would result in a dependency in the packages.

This doesn't necessarily have to be instead of the function and could complement the flexibility that generating particular data could offer.

Any other views on this are very welcome!

Check argument inputs to new `wl_*()` functions

Ensure class, etc.

Will then need testing as per #55.

Check ROxygen tags

Make sure function shave return tag, and check for appropriate use of details.

Add definition of F to function and documentation

Can someone please add a proper definition of F to target_capacity():

NHSRwaitinglist/R/target_capacity.R

Line 23 in 7d6930b

target_capacity <- function(demand, target_wait, F = 1) {

Prefer indexing input by column name than by position

Within function bodies and probably in arguments (e.g. we have referral_index in wl_simulator() that requires a numeric input value).

Add additional Open Gov licence

I think, given there's a crown copyright on public sector outputs and the Open Gov licence is encouraged by GDS, we should dual licence this (and potentially everything in the NHS-R organisation). I do this on my own organisations GitHub.

Vignette detailing usage of new wl_* functions

Write a vignette explaining the purpose of the functions and how to use them.

Create a cleaning function to shape raw data for use within the package

The function will take raw data (in the form returned by the function being authored in issue #23), and shape it into the demand data that will be used by the main package functions.

Create a reporting function for waiting list pressure across multiple sites and specialties

Take the output from the calculation function written in issue #25, and use it to produce an Rmd or Quarto html report summarising and visualising the waiting list position.

The return will be an html report containing an overview of the waiting list, and a dynamic table allowing various columns to be sorted (eg. by highest pressure, longest wait, etc). It may also contain some overview charts (eg comparing hospital sites, specialties, etc).

Create a function to make synthetic raw data

To be used in documentation and potentially during testing.

The function could be called something like create_waitinglist(n = 1000), which would return a dataframe of 1000 patients with columns for:

• Hospital Site
• Specialty
• OPCS4 Code
• Referral datetime
• Treatment datetime
• Removal without treatment datetime

Add function input checks

Accept only 'correct' argument inputs for each function. Provide useful error messaging to users on failure.

This will impact the range of tests that can be developed as part of #7.

It's probably best to put these checks in a utils.R file, given that similar checks can be used across functions.

This applies to the core functions that exist at time of writing. More checks will be required as the package's functionality expands.

Perhaps start with base stop() to begin with. Could make later use of the {cli} package for a slicker interface.

average_wait() function requires factor to be pre-calculated

I think this was touched upon at the last Teams meeting, but the function for 'average_wait' is actually the target mean wait required to achieve the specified waitlist performance criteria (is this correct?). Now that I am reading the documentation I think that there is some room for confusion and the code examples will make more sense if the function could be named 'mean_target_wait'.

I'm also thinking that instead of specifying a factor to achieve your desired performance % it would be better if you could specify the proportion and have the function do the factor calculation.

For example if I had a waitlist target of 95% of patients to be seen within 42 days I could call the function thus:

mean_target_wait(42,0.95)

This may have consequences for the other functions, but I think end users would assume they can just put their targets directly into the code without having to do some pre-calculations.

Apologies if I have misunderstood anything!

Provide more informative warning when argument vectors are recycled

Let the user know about mismatches in input-vector lengths. Related to #28.

Use {cli} and ... approach as per #50 to accept the length of any number of arguments, check them for length and report back to the user. Will likely need to be a tryCatch() to suppress the default R message and replace with our own.

We're doing this to provide a nicer user-interface. The default warning is terse:

> 1:2 + 1:3
[1] 2 4 4
Warning message:
In 1:2 + 1:3 :
  longer object length is not a multiple of shorter object length

And it prints multiple times with multiple violations:

> 1:2 + 1:3 + 1:4
[1] 3 6 7 6
Warning messages:
1: In 1:2 + 1:3 :
  longer object length is not a multiple of shorter object length
2: In 1:2 + 1:3 + 1:4 :
  longer object length is not a multiple of shorter object length

It's probably fine not to warn when one of the arguments is length 1, though. There's no warning for this in base either.

> 1 + 1:2
[1] 2 3

A vignette walking through the ENT example from the paper

The paper contains a running example centred around a P4 waiting list for ENT.
https://www.medrxiv.org/content/10.1101/2022.08.23.22279117v1

Create a vignette (Rmd) stepping through each of the stages in the paper, using the same figures as the paper uses.

average_wait() function has ambiguous name

The function for 'average_wait' is actually the target mean wait required to achieve the specified waitlist performance criteria (is this correct?). Now that I am reading the documentation I think that there is some room for confusion and the code examples will make more sense if the function could be named 'mean_target_wait'.

Add a link to the video overview to the README

Video here: https://www.youtube.com/watch?v=NWthhW5Fgls

Tests for new wl_* functions

Test coverage has dropped from 100% to 22% now the new functions are included.

Once the functions are stable, we need to write tests.

Create a data dictionary vignette

A document outlining the common terms use within the package. The aim is to help us align to:

• Consistent variable names (within the pacakage)
• Consistent "english" names (when describing the concepts represented by the variables)

This issue is to create a first version, which can be merged and added to as the package develops.

Update author name list to include @kaituna and @matt-dray

Significant contributions from both @kaituna and @matt-dray, however their names aren't listed as authors. They should be added

Create a bulk calculation function for multiple sites and specialties

The package is going to be used to process raw data into helpful visualisations for decision-makers.

Write a function to take data in the cleaned form (produced by issue #24), and to apply the package calculations.

The function will return a data frame of calculated data, including results for:

• Load
• Target queue size
• Target capacity
• Waiting list pressure

This result will be consumed by multiple downstream reporting functions, to visualise the information in different ways (eg. by specialty, by hospital site, by priority ranking)