---
title: "SC-IAT-example"
author: Ottavia M. Epifania
date: "`r Sys.Date()`"
bibliography: vignette.bib
# output: github_document
output: rmarkdown::html_vignette
#  pdf_document: default
vignette: >
  %\VignetteIndexEntry{SC-IAT-example}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
#  fig.path = "",
  comment = "#>",
  message = FALSE,
  warning = FALSE
)
```

```{r setup}
library(implicitMeasures)
```

This vignette illustrates how to use the `implicitMeasures` package for computing the SC-IAT *D* score. The illustration is based on the data set included in the package (i.e., `raw_data`). 

### First thing first: Import and explore data

The labels that contains the specification `sc_` in the`blockcode` variable  identify the SC-IAT blocks.

```{r}
data("raw_data")
# explore the dataframe
str(raw_data)

# explore the levels of the blockcode variable to identify the SC-IAT blocks
levels(raw_data$blockcode)
```

`raw_data` contains data from two different SC-IATs, one for the implicit assessment of the positive/negative evaluation of Milk chocolate (`sc_milk`), and one for the implicit assessment of the positive/negative evaluation of Dark chocolate (`sc_dark`). 

Once the SC-IATs blocks have been identified, it is possible to clean the data for computing the *D* score. 
Function `clean_sciat` allows for cleaning the data set of either just one SC-IAT or to clean the data sets of two SC-IATs concurrently. The labels identifying the test blocks must be specified as a character vector via argument `block_sciat_1` and argument `block_sciat_2` (use the `block_sciat_2` argument only if there is a second SC-IAT). 
The labels identifying the demographic information (if any) must be passed to the `trial_demo` argument, after specifying the column of the data set containing the labels of the demographic information (argument `demo_id`).

**DON'T USE THE `trial_eliminate` ARGUMENT TO ELIMINATE TRIALS EXCEEDING THE RESPONSE TIME WINDOW (rtw).**

The labels for identifying the responses beyond the rtw (that have to be eliminated) must be included in the variable identified by the`trial_id` label, but they have to be specified via the `non_response` argument in the `compute_sciat()` function to actually be deleted.


```{r}
data("raw_data")
sciat_data <- clean_sciat(raw_data, sbj_id = "Participant",
                         block_id = "blockcode",
                         latency_id = "latency",
                         accuracy_id = "correct",
                         block_sciat_1 = c("test.sc_dark.Darkbad",
                                           "test.sc_dark.Darkgood"),
                         block_sciat_2 = c("test.sc_milk.Milkbad",
                                           "test.sc_milk.Milkgood"),
                         trial_id  = "trialcode",
                         trial_eliminate = c("reminder",
                                             "reminder1"), 
                         demo_id = "blockcode", 
                         trial_demo = "demo")
```


Since two SC-IATs and demographic data were specified, `clean_sciat()` results in a list of 3 elements: 

```{r}
str(sciat_data) # structure of the resulting List
```

The first two elements (`sciat1` and `sciat2`) are two `data.frame` with class `sciat_clean`. They contain the data of the SC-IATs specified in the `block_sciat1` and `block_sciat2` arguments of the `clean_sciat()` function, respectively. The third element (`demo`) is a `data.frame` that contains the demographic information as specified in the `trial_demo` argument of function `clean_sciat()`. 

Each element of the resulting list can be stored in a separate object. 

```{r}
sciat1 <- sciat_data[[1]] # extract first SC-IAT data
sciat2 <- sciat_data[[2]] # extract second SC-IAT data
demo_data <- sciat_data[[3]] # extract demographic information

head(sciat1)
head(demo_data)
```

### Compute the SC-IAT D-score

Once the SC-IAT(s) data have been cleaned with the `clean_sciat()` function, it is possible to compute the *D* score by using function `compute_sciat()`. 

This function takes three mandatory arguments and one optional argument. The three mandatory arguments are the data set with class `sciat_clean`, and the labels identifying the two critical associative conditions (arguments `mappingA` and `mappingB`). If the SC-IAT administration included a rtw, the label identifying the trials exceeding the threshold must be specified via the (optional) argument `non_response`.


```{r}
# Compute the D-score for the first SC-IAT
 d_sciat1 <- compute_sciat(sciat1,
                  mappingA = "test.sc_dark.Darkbad",
                  mappingB = "test.sc_dark.Darkgood",
                  non_response = "alert")

# dataframe containing the SC-IAT D-score of the of the first SC-IAT
str(d_sciat1) 
 
# Compute D-score for the second SC-IAT
 d_sciat2 <- compute_sciat(sciat2,
                  mappingA = "test.sc_milk.Milkbad",
                  mappingB = "test.sc_milk.Milkgood",
                  non_response = "alert")
 
 # dataframe containing the SC-IAT D-score of the of the second SC-IAT
 head(d_sciat2)

```

The `compute_sciat()` function results in a `data.frame` with class `dsciat` containing a number of rows equal to the number of participants, their *D* score, and a bunch of useful information on their performance (see the documentation for the `compute_sciat()` function for further information). The `descript_d()`, `d_point()`, and `d_density()` functions require the object resulting from the `compute_sciat()` function to work. 

### Descriptive statistics

The descriptive statistics of the *D* score and of the response times in the two critical conditions can be easily obtained with the `descript_d()` function: 

```{r}
descript_d(d_sciat1) # Data frame containing SC-IAT D-scores
```


By specifying `latex = TRUE`, the `descript_d()` function prints the results in LaTeX code 

```{r}
descript_d(d_sciat2, # Data frame containing IAT D-scores
           latex = TRUE) # obtain the code for latex tables
```

### Plotting the results

The `implicitMeasures` package comes with several functions for obtaining nice and clear representations of the results at both individual respondent and sample levels. Additionally, it includes functions for plotting SC-IAT *D* scores resulting from two different SC-IATs. 

#### Individual respondent plot 

The `d_point()` function plots the SC-IAT *D* score for each respondent. 


```{r, fig.align='center', fig.width=6, fig.cap="Default use of function d_point()"}
 d_point(d_sciat1) # Data frame containing SC-IAT D-scores
```

In case of large sample size the label identifying each respondent is not easy to read, and it can be eliminated by setting  `x_values = FALSE`. 
Respondents can be arranged by increasing or decreasing *D* scores by setting argument `order_sbj` equal to `"D-increasing"` or `"D-decreasing"`, respectively. 
Descriptive statistics (i.e., $M_{\text{D-score}}\pm 2sd$) can be added by setting `include_stats = TRUE`. 
Finally, the color of the points can be changed by using the `col_point` argument. 

```{r scpointSettings, fig.align='center', fig.width=6, fig.cap="\\label{fig:scpointSettings} Function d_point() with settings change"}
d_point(d_sciat1, # dataframe containing SC-IAT D-scores
       order_sbj = "D-increasing", # change respondents' order
       x_values = FALSE,  # remove respondents' labels
       include_stats = TRUE, # include descriptive statistics
       col_point = "aquamarine3") # change points color
```


#### Sample  plot

The `d_density()` function plots the distribution of the SC-IAT *D* scores. It provides different options for choosing the most appropriate representation. 


```{r, fig.align='center', fig.width=6, fig.cap="Default use of function d_density() function"}
d_density(d_sciat1) # Data frame containing SC-IAT D-scores
```

The number of bins can be changed with the `n_bin` argument. The `graph` argument can be used for changing the graphical representation of the data. 
It is possible to choose an histogram representation (`graph = "histogram"`, default), a representation of the density distribution (`graph = "density"`), or a violin plot (`graph = "violin"`). The `col_fill` argument can be used to change the color of the points representing each respondent's score in the violin plot. 
Finally, also descriptive statistics (i.e., $M_{\text{D-score}}  \pm 2sd$) can be added to the graph by setting argument `include_stats = TRUE`. 

```{r sampleSettings, fig.align='center', fig.width=6, fig.cap="\\label{fig:sampleSettings}d_density() function with settings change"}
d_density(d_sciat1, # dataframe containing IAT Dscores
        graph = "density", # change graphical representation
        include_stats = TRUE) # include descriptive statistics
```


#### Multiple SC-IATs

The `multi_dsciat()` function plots the distributions of the *D* scores obtained from two different SC-IATs. This function takes only two mandatory arguments, which are the data frames containing the results of each SC-IAT obtained by using function `compute_sciat()`. 
The type of graphical representation can be changed by using `graph`, which is set to `"density" ` by default. Default representation also contains the lines that indicate the mean of each distribution. These lines can be taken out of the graph by setting  `dens_mean = FALSE`. 
 

```{r fig.align='center', fig.width=6, fig.cap="Default results representation of function multi_dsciat()"}
multi_dsciat(d_sciat1, # dataframe containing the results of the first SC-IAT
             d_sciat2) # dataframe containing the results of the second SC-IAT

```

The `graph` argument can be set equal to `"violin"` (violin plots of the SC-IATs *D* scores) or `"point"` (point representation of both SC-IATs *D* scores). 
The labels identifying each SC-IAT can be set with the `label_sc1` and `label_sc2` arguments (defaults are `"SC-IAT 1"` and `"SC-IAT 2"`). The values labels of the $x$-axis can be removed by setting `x-values = FALSE` (suggested in case of large sample size).
The `gcolors` argument can be used to change the colors of each SC-IAT (default is `"dark"`). Other colors options are `"greens"`, `"blues"`, and `"pink"`.


```{r fig.align='center', fig.width=6, fig.cap="Results representation of function multi_dsciat() with settings change"}
multi_dsciat(d_sciat1, # dataframe containing the results of the first SC-IAT
             d_sciat2, # dataframe containing the results of the second SC-IAT
             graph = "point", # change graph type
       x_values = FALSE, # take out x values
       gcolors = "greens", # change color
       label_sc1 = "Dark SC-IAT",  # change label first SC-IAT
       label_sc2 = "Milk SC-IAT") # change label second SC-IAT
```
