---
title: "Pittsburgh Sleep Quality Inventory"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{psqi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
options(rmarkdown.html_vignette.check_title = FALSE)
frag_path <- here::here("man", "fragments", "psqi")
paths <- list.files(frag_path, "Rmd", full.names = TRUE)
names(paths) <- gsub("\\.Rmd", "", basename(paths))
paths <- as.list(paths)
```

## Background
```{r child=paths$background, eval = TRUE} 
```

## Scoring
```{r child=paths$scoring, eval = TRUE} 
```

## Data requirements  
```{r child=paths$datareq, eval = TRUE} 
```

## Use the `psqi` functions
All the functions necessary to compute the components and the global score for the psqi are included in this package, and loading it in your R-environment makes them accessible to you. 
All the functions for the PSQI, are prefixed with `psqi_`, so they are easy to find.

There are a total of 7 `psqi_` functions in this package. 
One for each component, except 1 and 6 which are just the raw answers from questions 4 and 7. 
In addition, there is a function to calculate the global, which must be done _after_ having computed the 7 components. 
Lastly, there is a function `psqi_compute` which will do it all for you, compute all the components and the global.
All the functions are documented as any function in R, and so you may call `?psqi_compute` to see the user documentation for the functions.

There are many options you can utilize for these functions, so you may explore them as you wish. 
The functions are also made such that you can use them on datasets other than the LCBC MOAS dataset, but you will then have to specify the columns to use for the various components your self.
The functions are made to work directly with the MOAS, and require no extra input other that the object containing the MOAS to run all calculations. 
Running `psqi_compute(MOAS)` will calculate all components and append them to the data you provided.
Running `psqi_compute(MOAS, keep_all = FALSE)` will only return the computed components and the global score in a data frame.

```{r}
library(questionnaires)
library(dplyr)

# Create some data to test on
data <- data.frame(
  psqi_01 = c("22:30:00", "07:00:00", "22:30:00", "NaN", "23:30:00"), 
  psqi_02 = c(5, 10, 30, 20, 30), 
  psqi_03 = c("05:50:00", "17:00:00", "06:30:00", "NaN", "06:45:00"), 
  psqi_04 = c(7, 9.75, 8, 9, 6), 
  psqi_05a = c(0L, 0L, 1L, 2L, 2L), 
  psqi_05b = c(0L, 0L, 2L, 0L, 2L), 
  psqi_05c = c(0L, 0L, 3L, 1L, 2L), 
  psqi_05d = c(0L, 0L, 0L, 0L, 0L), 
  psqi_05e = c(0L, 3L, 1L, 0L, 0L), 
  psqi_05f = c(0L, 0L, 1L, 0L, 1L),
  psqi_05g = c(0L, 0L, 1L, 1L, 3L), 
  psqi_05h = c(0L, 0L, 0L, 0L, 0L), 
  psqi_05i = c(0L, 0L, 0L, 0L, 0L), 
  psqi_05j_Coded = c(NA,NA, "No", NA, NA), 
  psqi_05j = c(0L, 0L, NA, NA, NA), 
  psqi_06 = c(0L, 1L, 2L, 1L, 1L), 
  psqi_07 = c(0L, 0L, 0L, 0L, 0L), 
  psqi_08 = c(0L, 0L, 0L, 1L, 0L), 
  psqi_09 = c(0L, 0L, 1L, 0L, 1L), 
  psqi_10 = c(3L, 1L, 3L, NA, 3L), 
  psqi_10a = c(1L, NA, 1L, NA, 0L), 
  psqi_10b = c(0L, NA, 0L, NA, 0L), 
  psqi_10c = c(2L, NA, 2L, NA, 0L), 
  psqi_10d = c(0L, NA, 0L, NA, 0L), 
  psqi_10e_Coded = c(NA, NA, "", NA, NA), 
  psqi_10e = c(NA_integer_, NA_integer_, NA_integer_, NA_integer_, NA_integer_), 
  psqi_11a = c(0L, 2L, 1L, 1L, 2L), 
  psqi_11b = c(0L, 0L, 2L, 0L, 2L), 
  psqi_11c = c(0L, 0L, 1L, 1L, 2L), 
  psqi_11d = c(0L, 3L, 2L, 0L, 2L)
)

data
```

### Component-wise calculations
There are 7 components in the PSQI, and the functions in the package allow you to calculate 5 components based on two or more columns in the data. 
Two components do not have their own functions as they are just the raw answers to two questions.

Each component has unique arguments needed to calculate.

```{r}
psqi_compute_comp2(min_before_sleep = data$psqi_02, 
                   no_sleep_30min = data$psqi_05a)

psqi_compute_comp3(hours_sleep = data$psqi_04)

psqi_compute_comp4(hours_sleep = data$psqi_04, 
                   bedtime = data$psqi_01, 
                   risingtime = data$psqi_03)

# Requires many columns, so for conveniece must be specified in another way than others.
psqi_compute_comp5(data = data, 
                   sleep_troubles = matches("^psqi_05[b-j]$"))

psqi_compute_comp7(keep_awake = data$psqi_08, 
                   keep_enthused = data$psqi_09)
```

If you want to add these directly to your data.frame, you can wrap then insire a `dplyr::mutate`.

```{r}
data2 <- data %>% 
  mutate(
    comp1 = psqi_06,
    comp2 = psqi_compute_comp2(min_before_sleep = psqi_02, 
                                no_sleep_30min = psqi_05a),
    comp3 = psqi_compute_comp3(hours_sleep = psqi_04),
    comp4 = psqi_compute_comp4(hours_sleep = psqi_04, 
                               bedtime = psqi_01, 
                               risingtime = psqi_03),
    comp5 = psqi_compute_comp5(data = data, 
                               sleep_troubles = matches("^psqi_05[b-j]$")),
    comp6 = psqi_07,
    comp7 = psqi_compute_comp7(keep_awake = psqi_08, 
                               keep_enthused = psqi_09)
  )
data2
```


### Global calculation
After having all components calculated, the global is the sum of all these.
The `psqi_compute_global` function takes an entire data frame, and a tidy-selected collection of columns of the calculated components. 
In this case we called the components with names starting with "Comp", and can use this logic for the computation.

```{r}
psqi_compute_global(data2, starts_with("comp"))
```

We get one `NA` because someone has omitted to answer to a question, and so a component is missing, and thus a global cannot be computed.
You have the option to specify how many missing components the global calculation will allow, but remember that this will skew the data somewhat.

```{r}
psqi_compute_global(data2, starts_with("comp"), max_missing = 2)
```

### Calculating all components and global in one go
It is quite cumbersome to mutate and fix every component manually, so the `psqi_compute` function is there to make everything in one go.
If you are working on MOAS-like data, this is easy to use, as column names and specifications are pre-set to work with the MOAS.
If you are working on other data, you will need to set each option to the column names in the data for each question manually.

```{r}
psqi_compute(data)

psqi_compute(data, keep_all = FALSE)

psqi_compute(data, keep_all = FALSE, max_missing = 1)
```


## References  
```{r child=paths$references, eval = TRUE} 
```
