---
title: "Beck Depression Inventory (BDI)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{bdi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, eval = TRUE}
library(questionnaires)
```

## Background

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

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

### Questionnaire items
**1:**  Sadness  
**2:**  Pessimism  
**3:**  Past failure  
**4:**  Loss of pleasure  
**5:**  Guilty feelings  
**6:**  punishment feelings  
**7:**  Self-dislike  
**8:**  Self-criticalness  
**9:**  Suicidal thought or wishes*  
**10:** Crying  
**11:** Agitation  
**12:** Loss of interest  
**13:** Indecisiveness  
**14:** Worthlessness  
**15:** Loss of energy   
**16:** Changes in sleep pattern  
**17:** Irritability  
**18:** Changes in appetite (including specification of weight loss intentions if applicable)  
**19:** Concentration difficulty  
**20:** Tiredness or fatigue  
**21:** Loss of interest in sex  

**Weight loss format:**  
For item 18, weight loss intention if applicable should be punched as numbers with decimals.

#### Suicidality
Please note that this questionnaire includes one question (q 9) regarding suicidal thoughts. 
In the case of scores above 1 on this item, the participant should be contacted to for a follow up. 
This should be described in the **clinical observation document** . 
If the participant scores 3 on this question ("_Jeg vil ta livet mitt om jeg fikk sjansen_" / "_I would killl my self if I had the chance"_), this should obviously be taken very seriously, and the participant should be contacted immediately.

## Data requirements  

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

## Using the `bdi` functions

There are two main bdi functions: `bdi_compute_sum` and `bdi_factorise`.
If you have MOAS-like data they can be applied directly without any other specification.
```{r, eval=FALSE}
# Creates a vector with the BDI sums, given they are in the dataset
bdi_sum <- bdi_compute_sum(yourData)

# Creates a vector of BDI clasification based on the sums from above
bdi_factorise(bdi_sum)
```

Some participants may have missed answering some questions. 
By default, the `bdi_compute_sum` function allows no missing values for a participant, and will give NA if there are any.
This is to ensure you are fully aware of what is happening to the output. 
You can alter the number of missing for a participant you allow through the `max_missing` argument. 

```{r, eval=FALSE}
# Allows each participant to have at most two missing questions
bdi_sum <- bdi_compute_sum(yourData, max_missing = 2)
```

If you are working with non-MOAS data, the naming of columns might be different. 
Hopefully, the naming is consistent in some way so you easily can you tidy-selectors. 

```{r eval=FALSE}
# Base calculation on columns with names that start with "bdi"
otherData %>% 
  bdi_compute_sum(cols = starts_with("bdi"))

# Base calculation on columns with names that contain the string "Beck"
otherData %>% 
  bdi_compute_sum(cols = contains("Beck"))

# Base calculation on columns with names matching a regular expression
otherData %>% 
  bdi_compute_sum(cols = matches("bdi_[0-9][0-9]$"))
```

The function can be used within `dplyr:mutate` but requires the use of the special `.` to work, as it needs the entire data frame to do calculations.
the `.` within a `mutate` (or other dplyr function) means "insert piped object in here", and thus the below example the entire `data` object is placed where the `.` is. 
In this case, you would make a new column in the piped data called `bdi_sum`, 
and using that column also create the factorised version in a column named `bdi_fact`.


```{r}
data %>% 
  mutate(
    bdi_sum = bdi_compute_sum(., cols = matches("bdi_[0-9][0-9]$")),
    bdi_fact = bdi_factorise(bdi_sum))
```

This last part can also be done in a single step with the `bdi_compute` function.
This function will return a data.frame with columns `BDI` (the sum)  and `bdi_Coded` (the factor), based on the given data set. 
By default, these two columns will be added to the end of the dataset provided, and use the default arguments to the two other bdi functions it calls. 

```{r}
data %>% 
  bdi_compute()
```

You may also choose to only have the two computed columns returned by setting `keep_all` to `FALSE`
```{r}
data %>% 
  bdi_compute(keep_all = FALSE)
```

Lastly, this function also takes a `predicate`, a logical statement (of length 1 or the number of rows of the data) for the calculation of the sum.
For instance, in the MOAS, we do not have the single question answers for projects before nettskjema implementation.
That means that we have a pre-calculated sum in the data, and the sum cannot be calculated based on single question data. 
In this case, we use the predicate `!is.na(bdi_01)`, so that the `bdi_compute_sum` function is only run on data that actually has single question data.
If we don't do this, the punched `BDI` score will be overwritten with `NA`. 

```{r}
data %>% 
  bdi_compute(predicate = !is.na(bdi_01))
```

### Nettskjema special case
Data collected through nettskjema has some special features because of the way the data gets structured with you can choose multiple options. 
For this reason, a special function to handle the way Nettskjema data is structures is made `bdi_restructure`. 
If data come from Nettskjema, the structure is in wide format, with each question option as columns, creating 21*4 columns of data. 
This function allows you to gather and create single columns for questions. 

The columns must adhere to some specific logic to work.
It is recommended that the column names are in  the format `bdi_01_2` `bdi_01_3`, where the first two numbers are the question number, and the last number is the option number.
The `bdi_restructure` function transforms the last numbers in the column name a cell value, as this is the BDI score for that option, and then calculates the mean of all options _per question answered_. 

```{r, eval=TRUE}
dat <- data.frame(
    ID = 1:4, 
    bdi_01_0 = c(NA,1, NA, NA),
    bdi_01_1 = c(1, NA, 1, NA),
    bdi_01_2 = c(NA, NA, 1, NA),
    bdi_01_3 = c(NA, NA, NA, NA),
    bdi_02_0 = c(1, NA, NA, NA),
    bdi_02_1 = c(NA,NA, NA, NA),
    bdi_02_2 = c(NA,1, NA, NA),
    bdi_02_3 = c(NA, NA, NA, 1)
  )

dat

bdi_restructure(dat)
```


## References

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