---
title: "SangerTools Vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{SangerTools Vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<p><img src = "sangertoolshex.png" width = "125px" height = "150px" align="right"></a></p>

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.height = 5, 
  fig.width = 8
)
```


```{r setup, echo=FALSE, include=FALSE}
library(SangerTools)
library(dplyr)
library(ggplot2)
library(scales)
library(kableExtra)
```


# Welcome to the SangerTools package

This package has been created to provide convenient functions for working with population health data.  It is  specifically aimed at healthcare providers and services that focus on population health management. 

Many of the functions are centered around the Master Patient Index format. Where each row is a patient and each column is an observation of that patient.

In the next sections we will take you through how you use the tool. 
***
***

## Loading in Health Data

To load in the Master Patient Index attached to the SangerTools package  follow these steps:

```{r load_data}

health_data <- SangerTools::master_patient_index

```

```{r load_data_print, echo = FALSE}
health_data %>% 
  head() %>% 
  kableExtra::kbl() %>%
  kableExtra::kable_styling(bootstrap_options = c("striped",
                                      "hover",
                                      "condensed",
                                      "responsive"))
```
The data contains:

- **PseudoNHSNumber** - A Pseudonymised NHS Patient Identifier
- **Sex** - The identifiable sex of the patient
- **Smoker** - Health Condition Flag: 1 denotes if the patient is a smoker
- **Diabetes** - Health Condition Flag: 1 denotes if the patient has diabetes
- **Dementia** - Health Condition Flag: 1 denotes if the patient has dementia
- **Obesity** - Health Condition Flag: 1 denotes if the patient is Obese
- **Age** - Age of the patient
- **IMD_Decile** - The decile of indices of multiple deprivation
- **Ethnicity** - The identifiable ethnicity of the patient}
- **Locality** - The region where the patient lives - sampled from Gloucestershire Clinical Commissioning Group (GCCG)
- **PrimaryCareNetwork** - The network of General Practioners that the patient is registered with - sampled from (GCCG)

With the data we can start to work with the function in the package.

***
## Age bands 



It is common practice to transform continuous age values into a smaller set of categories.  


There are two functions in the package for doing this.

* `age_bandizer` 
* `age_bandizer2` 

`age_bandizer` Uses a tidyverse philosophy of function creation with Non-Standard Evaluation. It will produce a new column with 5 year age bands as a factor. 

`age_bandizer2` uses Standard Evaluation and currently takes in puts of band size 2,5,10 & 20. 

```{r agebands}
health_data <- SangerTools::age_bandizer(df = health_data,
                                         Age_col = Age)

health_data <- SangerTools::age_bandizer_2(df = health_data,
                                           Age_col = "Age",
                                           Age_band_size = 5)
```

```{r agebands_print, echo = FALSE}
health_data %>% 
  select(Age,Ageband) %>%
  head() %>% 
  kableExtra::kbl() %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))
```


## Generating a categorical column chart easily

The package makes it very simple to create a categorical column chart. This will be implemented in the next example:

```{r categorical_column_chart}
# Group by Ethnicity
diabetes_df <- health_data %>% 
  dplyr::filter(Diabetes==1)
  
  SangerTools::categorical_col_chart(df = diabetes_df,
                                     grouping_var = Ethnicity)+
  scale_fill_sanger()+ 
  labs(title = "Diabetic Patients by Ethnicity",
       subtitle = "Nearly All Diabetics are White",
       x = NULL, 
       y = "Number of Patients") + 
  coord_flip() 

# Group by Sex
health_data %>% 
  dplyr::filter(Diabetes==1) %>% 
  SangerTools::categorical_col_chart(Sex) + 
  scale_fill_sanger()+
  labs(title = "Diabetic Patients by Gender",
       x = NULL, 
       y = "Number of Patients")  
```

It really is that simple to generate very nice looking proportional charts. 

## Crude Prevalence 


Here we will look at the crude rate of diabetes 
To obtain the crude prevalence rate, this can be achieved below:

```{r crude_rates}
 crude_prevalence <- SangerTools::crude_rates(df = health_data,
                                              Condition =  Diabetes, 
                                              Locality)
```
```{r crude_rates_print, echo=FALSE }
  kableExtra::kbl(crude_prevalence) %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))

```

## Age Standardised Rates

Let's revisit the example above. Diabetes is highly confounded by age. Most diabetics will be diagnosed after the age of 40.


```{r ASR}

asr_prevalence <- SangerTools::standardised_rates_df(df = health_data,
                                   Split_by = Locality,
                                   Condition = Diabetes, 
                                   Population_Standard = NULL,
                                   Granular = FALSE,
                                   Ageband )
```

```{r asr_print,echo=FALSE}

  kableExtra::kbl(asr_prevalence) %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))

```


Given that each of the Localities now has the population structure of the county as whole; we can see slight differences to the crude prevalence rates.

## Age Standardised Rates with User Defined Population Structure


We will use another dataset attached to the package; the UK population from the year 2018. 
This is broken down by 5 year age bands. 
For a user define population structure to integrate with `standardised_rates_df` ensure to change the name of the population column to 
`Pop_Weight`


## Load 2018 UK Population Structure 

```{r UK_pop}

uk_pop18<- SangerTools::uk_pop_standard

names(uk_pop18) <- c("Pop_Weight","Ageband")

```
```{r UK_pop_print,echo = FALSE}
uk_pop18 %>% 
  head() %>% 
  kableExtra::kbl(format.args = list(big.mark = ",")) %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))

```

## UK Age Standardised Diabetes Prevalence 

```{r ASR2}
asr_uk <- SangerTools::standardised_rates_df(df = health_data,
                                   Split_by = Locality,
                                   Condition = Diabetes, 
                                   Population_Standard = uk_pop18,
                                   Granular = FALSE,
                                   Ageband )
```

```{r ASR2_print,echo = FALSE}
asr_uk %>% 
  kableExtra::kbl() %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))
```
## Combining Results

To view both crude and standardised rates we can use dplyr::`left_join`

```{r combined_rates}
combined_rates <- crude_prevalence %>% 
  dplyr::left_join(asr_prevalence, by = c("Locality"))


```
```{r combined_rates_print, echo=FALSE}
combined_rates %>% 
  kableExtra::kbl() %>%
  kableExtra::kable_styling(bootstrap_options = c("striped", 
                                      "hover", 
                                      "condensed", 
                                      "responsive"))

```

Other functionality added into the package would be to use the multiple CSV reader and clipboard functions.

## Excel Clipboard function

This copies a data frame to the clipboard for you for then pasting into Excel sheets, or csvs, or raw text.

```{r copy_to_clipboard,eval=FALSE}

SangerTools::excel_clip(combined_rates)

```

There is the potential to read from multiple CSVs as well and then these can be fed into data frames.


## Multiple CSV reader

To implement this function you would need to have a number of CSVs contained in a folder. To read these in, follow the below instructions:

```{r multiple_csv_reader}
file_path = 'my_file_path_where_csvs_are_stored'

if (length(SangerTools::multiple_csv_reader(file_path))==0){
  message("This won't work without changing the variable input to a local file path with CSVs in")
}
```

`multiple_excel_reader` is the equivalent for excel files; however please read function documentation page as both functions have a strict
set of requirements for execute. 


## Splitting Dataframes and Saving

`split_and_save` is a quick way to split a dataframe on a specified column into subsequent dataframes after which each of dataframes is dynamically written to a location choice

```{r split_and_save,eval=FALSE}
SangerTools::split_and_save(
 df = health_data,
 Split_by = "Locality",
 file_path = "Inputs/",
 prefix = NULL
)
```

## Results to SQL 

Write your results to SQL Server ensuring that the table name appears as expected. 

This function makes a number of assumptions and is limited in scope; please read documentation.

```{r df_to_sql,eval = FALSE}
SangerTools::df_to_sql(df = combined_rates,
                       driver = "SQL SERVER",
                       server = "Org-sql-db",
                       database = "MyReports",
                       sql_table_name = "Diabetes_Prevalence",
                       overwrite = FALSE)


```



## See Brand Colours 

This is an anonymous function and can be called without any arguments
```{r show_brand_palette} 

show_brand_palette()
```

## See More Colours

This is also an anonymous function; it will show an extended colour palette 
```{r}
show_extended_palette()
```





## Closing 

More functions are being added to this tool and a new version of the file will be released on CRAN very soon. Keep an eye out on the associated [GitHub](https://github.com/ald0405/SangerTools) for updates.