README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# nhstt

<!-- badges: start -->
[![R-CMD-check](https://github.com/bennettoxford/nhstt/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/bennettoxford/nhstt/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/bennettoxford/nhstt/graph/badge.svg)](https://app.codecov.io/gh/bennettoxford/nhstt)
<!-- badges: end -->

> **This package is under active development. Breaking changes are likely.**

`nhstt` provides access to publicly available NHS Talking Therapies reports in a tidy data format.

## Installation

Install the development version from GitHub:

``` r
# install.packages("pak")
pak::pak("bennettoxford/nhstt")
```

## Usage

```{r example, eval = FALSE}
library(nhstt)

# Load annual key measures dataset for financial year 2024-25
km_annual <- get_key_measures_annual(periods = "2024-25")

# Load all monthly activity performance datasets
# Note, this will take a few minutes
ap_monthly <- get_activity_performance_monthly()
```

## Available NHS Talking Therapies data

### Annual data

```{r datasets-annual, echo = FALSE, message = FALSE}
df_nhstt_reports <- nhstt:::available_nhstt_reports() |>
  dplyr::filter(!stringr::str_detect(title, "metadata")) |>
  dplyr::filter(frequency == "annual") |>
  dplyr::select(
    get_function,
    first_period,
    last_period,
    n_periods,
    version
  ) |>
  dplyr::mutate(get_function = paste0("`", get_function, "()`"))

knitr::kable(
  df_nhstt_reports,
  row.names = FALSE,
  col.names = c(
    "Function",
    "First period",
    "Last period",
    "Count periods",
    "Version"
  ),
  align = c("l", "l", "l", "r", "r")
)
```

### Monthly data

```{r datasets-monthly, echo = FALSE, message = FALSE}
df_nhstt_reports <- nhstt:::available_nhstt_reports() |>
  dplyr::filter(!stringr::str_detect(title, "metadata")) |>
  dplyr::filter(frequency == "monthly") |>
  dplyr::select(
    get_function,
    first_period,
    last_period,
    n_periods,
    version
  ) |>
  dplyr::mutate(get_function = paste0("`", get_function, "()`"))

knitr::kable(
  df_nhstt_reports,
  row.names = FALSE,
  col.names = c(
    "Function",
    "First period",
    "Last period",
    "Count periods",
    "Version"
  ),
  align = c("l", "l", "l", "r", "r")
)
```

### Metadata

```{r datasets-metadata, echo = FALSE, message = FALSE}
df_nhstt_reports <- nhstt:::available_nhstt_reports() |>
  dplyr::filter(stringr::str_detect(title, "metadata")) |>
  dplyr::select(
    get_function,
    first_period,
    last_period,
    n_periods,
    version
  ) |>
  dplyr::mutate(get_function = paste0("`", get_function, "()`")) |>
  dplyr::distinct()

knitr::kable(
  df_nhstt_reports,
  row.names = FALSE,
  col.names = c(
    "Function",
    "First period",
    "Last period",
    "Count periods",
    "Version"
  ),
  align = c("l", "l", "l", "r", "r")
)
```

## Time to download and tidy the data

```{r run-benchmarks, echo = FALSE, message = FALSE, warning = FALSE}
library(nhstt)

format_time <- function(elapsed) {
  if (elapsed < 1) {
    paste0(round(elapsed, 2), " sec")
  } else if (elapsed < 60) {
    paste0(round(elapsed, 1), " sec")
  } else {
    paste0(round(elapsed / 60, 1), " min")
  }
}

benchmark_dataset <- function(dataset, period, frequency, get_function) {
  n_periods <- length(nhstt:::list_available_periods(dataset, frequency))

  raw_path <- nhstt:::get_raw_cache_path(dataset, period, frequency)
  tidy_path <- nhstt:::get_tidy_cache_path(dataset, period, frequency)
  if (file.exists(raw_path)) {
    unlink(raw_path)
  }
  if (file.exists(tidy_path)) {
    unlink(tidy_path)
  }

  download_time <- system.time({
    nhstt:::read_raw(dataset, period, frequency, use_cache = FALSE)
  })["elapsed"]

  tidy_time <- system.time({
    get_function(periods = period, use_cache = TRUE)
  })["elapsed"]

  total_time <- (download_time + tidy_time) * n_periods

  list(
    download = format_time(download_time),
    tidy = format_time(tidy_time),
    total = format_time(total_time)
  )
}

time_km_annual <- benchmark_dataset(
  "key_measures_annual",
  "2024-25",
  "annual",
  get_key_measures_annual
)
time_proms_annual <- benchmark_dataset(
  "proms_annual",
  "2024-25",
  "annual",
  get_proms_annual
)
time_therapy_position_annual <- benchmark_dataset(
  "therapy_position_annual",
  "2024-25",
  "annual",
  get_therapy_position_annual
)
time_ap_monthly <- benchmark_dataset(
  "activity_performance_monthly",
  "2025-08",
  "monthly",
  get_activity_performance_monthly
)
```

Approximate download and processing times per period.
Your times might be a bit faster or slower depending on your internet speed and computer setup.

```{r performance-table, echo = FALSE}
performance_data <- tibble::tibble(
  Function = c(
    "`get_key_measures_annual()`",
    "`get_proms_annual()`",
    "`get_therapy_position_annual()`",
    "`get_activity_performance_monthly()`"
  ),
  download_per_period = c(
    time_km_annual$download,
    time_proms_annual$download,
    time_therapy_position_annual$download,
    time_ap_monthly$download
  ),
  tidy_per_period = c(
    time_km_annual$tidy,
    time_proms_annual$tidy,
    time_therapy_position_annual$tidy,
    time_ap_monthly$tidy
  ),
  total_all_periods = c(
    time_km_annual$total,
    time_proms_annual$total,
    time_therapy_position_annual$total,
    time_ap_monthly$total
  )
)

knitr::kable(
  performance_data,
  row.names = FALSE,
  col.names = c(
    "Function",
    "Download per period",
    "Tidy per period",
    "Total (all periods)"
  ),
  align = c("l", "r", "r", "r")
)
```

## For developers

See [DEVELOPERS.md](DEVELOPERS.md).

## Licence

### R package

The `nhstt` package is licensed under the [MIT License](LICENSE.md).

### NHS Talking Therapies data

All NHS Talking Therapies data is Copyright NHS England and licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
Contains public sector information licensed under the Open Government Licence v3.0.