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%"
)
```

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- [![R-CMD-check](https://github.com/BBCS-PHI/BBCSutils/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/BBCS-PHI/BBCSutils/actions/workflows/R-CMD-check.yaml) -->
<!-- [![Codecov test coverage](https://codecov.io/gh/Birmingham-and-Solihull-ICS/BSOLutils/branch/main/graph/badge.svg)](https://app.codecov.io/gh/Birmingham-and-Solihull-ICS/BSOLutils?branch=main) -->
  
 <!-- badges: end -->


# BBCSutils 

This repository contains an R package to help with various day-to-day tasks in BBCS ICB Cluster Population Health Improvement - Analytics team.
It contains various helper functions for things like:

* confidence intervals
* ICB colour palette functions
* ggplot2 and plotly helpers, themes and colour scales
* SQL conversion functions for estimating data types and lengths
* Dispersion ratios and overdispersion calculations
* Standardisation and inequality comparison ratios

This package is not released on CRAN, but can be installed from GitHub using the following command:

```{r, eval=FALSE}
# install.packages("remotes")
remotes::install_github("https://github.com/BBCS-PHI/BBCSutils")
```

# Examples

## Confidence interval calcualtions

We often calculate rates, ratios and standardised methods.  We have, broadly, followed PHE / UKHSA guidance on methods, with an exception for using Ulm's methods for standardised rates.

```{r cis, message=FALSE, warning=FALSE}
library(BBCSutils)
library(NHSRdatasets)
library(dplyr)
data("LOS_model")

#calculate crude and indirectly (Age and LOS) standardised rates (ISR)
model1 <- glm(Death ~ Age * LOS, data = LOS_model, family = "binomial")

# Use the predicted risk of death per patient from your model
LOS_model$risk_death <- predict(model1, newdata = LOS_model, type = "response")

# Summarise by organisation
LOS_summary <-
  LOS_model |> 
  group_by(Organisation) |> 
  summarise(Patients = n(),
            Deaths = sum(Death),
            Predicted_deaths = sum(risk_death))

# Add rate calculations
LOS_summary <-
  LOS_summary |> 
  mutate(Crude_Rate = Deaths / Patients,
         ISR_Rate = Deaths / Predicted_deaths)

# Calcualting in isolation
byars_ci(LOS_summary$Deaths, LOS_summary$Patients)

exact_SMR_ci(LOS_summary$Deaths, LOS_summary$Predicted_deaths)

# Adding in to a table
LOS_summary <-
  LOS_summary |> 
  mutate(Crude_LowerCI = byars_ci(Deaths, Patients)$LowerCI,
         Crude_UpperCI = byars_ci(Deaths, Patients)$UpperCI,
         ISR_LowerCI = exact_SMR_ci(Deaths, Predicted_deaths)$LowerCI,
         ISR_UpperCI = exact_SMR_ci(Deaths, Predicted_deaths)$UpperCI
  )
```



## SQL-helper functions

When loading data into SQL Server using R, we can rely on implicit conversation but it is not always right.
The function below takes a data.frame input (for example the `mtcars` demo data) and suggests suitable data types for SQL Server import.

```{r sql_dt}
derive_sql_data_types(LOS_model)
```


## Colour palettes and themes

Colour palettes and associated function for `ggplot2` are included.  The default is set to the new, clustered ICB graphic.
There are other palettes, based off the old BSOL ICB styling and style guide colours, including hue-based single colour palettes.

Plotting the standardisation example from above, we'll apply both the ICB colour scale and the ICB theme.

```{r ggplot1}
library(ggplot2)
library(tidyr)
library(stringr)

# First pivot it round for easy plotting.
LOS_summary |> 
  pivot_longer(
    cols = matches("^(Crude|ISR)_(Rate|LowerCI|UpperCI)$"),
    names_to = c("Rate_type", ".value"),
    names_sep = "_"
  ) %>%
  select(Organisation, Rate, Rate_type, LowerCI, UpperCI, everything()) |> 
  ggplot(aes(x = Organisation, colour = Rate_type, y = Rate)) +
  geom_point() +
  geom_errorbar(aes(ymax = UpperCI, ymin = LowerCI)) +
  facet_grid(~Rate_type, scales = "free_y") +
  scale_colour_icb() +
  labs(title = "Example plot of death rates using simulated data",
       subtitle = "Crude rate vs. Indirectly Age/LOS standardised",
       colour = "Rate type") +
  theme_icb() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))
```

Using a colour gradient:

```{r ggplot2}
# Create a density object
Age_density <- density(LOS_model$Age, n = 2 ^ 12)

ggplot(data.frame(x = Age_density$x, y = Age_density$y),
       aes(x = x, y = y)) +
  geom_line() + 
  geom_segment(aes(xend = x, yend = 0, colour = x), alpha = 0.2) +
  {{scale_colour_icb(discrete = FALSE)}} +
  labs(title = "Age density in LOS_model dataset",
       subtitle = "Example of ICB colour gradient",
       x = "Age",
       y = "Density") +
  {{theme_icb()}}

```


## Date functions

We often work with dates, which can be a bit cumbersome in `R`.  These functions perform common transformations of dates:

Generating a sequence of years:

```{r dates1}
generate_year_series(2014, 2024, 3)
# Non-overlapping sequence
generate_year_series(2014, 2024, 3, overlapping = FALSE)
```

Functions for pulling out the financial year, e.g. 2025/25 for 30th April 2025.
```{r dates2}
f_year(Sys.Date())

f_year_start(Sys.Date())
f_year_end(Sys.Date())
```

## Dispersion

Dispersion is the 'variance' of poisson or binomial models, where 'overdispersion' is common because real-world data shows more variability than Poisson or binomial models expect.  We can test for it using by calculating the dispersion ratio, and we can calculate 'between' variance to pair with 'within' variance in random-intercept type models.

```{r dispersion}
# The dispersion ratio of the model above:
disp_ratio(model1)

# 1.13377 is not really overdispersed (1 = equidispersion)

# Calculate the dispersion ratio of a series of z-scores
phi <- phi_func(6, c(1.3,0.75, 1.5, 2, -1.2, -2.2))

phi
```

# Licence

This repository is dual licensed under the [Open Government v3]([https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) & MIT. All code and outputs are subject to Crown Copyright.


<img src="./man/figures/signature.svg" align="center"/>