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

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

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

This vignette illustrates how to use the `implicitMeasures` package for computing the IAT *D* score. The illustration is based on the data set `raw_data` that comes with the package.

### First thing first: Import and explore data

Labels containing specification `.iat` in variable `blockcode` identify IAT blocks.

```{r}
data("raw_data")
# explore the dataframe
str(raw_data)
# explore the levels of the blockcode variable to identify the IAT blocks
levels(raw_data$blockcode)
```

Once the IAT blocks have been identified, it is possible to clean the IAT data by using the `clean_iat()` function. Since the data set also includes respondents' demographic information (`demo` in the `blockcode` variable), it is possible to extract and store these information in a separate data frame:  

```{r eval = T}
iat_cleandata <- clean_iat(raw_data, sbj_id = "Participant",
                          block_id = "blockcode",
                          mapA_practice = "practice.iat.Milkbad",
                          mapA_test = "test.iat.Milkbad",
                          mapB_practice = "practice.iat.Milkgood",
                          mapB_test = "test.iat.Milkgood",
                          latency_id = "latency",
                          accuracy_id = "correct",
                          trial_id = "trialcode",
                          trial_eliminate = c("reminder", "reminder1"),
                          demo_id = "blockcode",
                          trial_demo = "demo")
```

Since also the demographic data has been specified, `clean_iat()` results in a list of 3 elements: 

```{r}
str(iat_cleandata)
```

`data_keep` is a `data.frame` with class `iat_clean`. It contains the data set for the `compute_iat()` function. 

`data_eliminate` is a `data.frame` that contains all the discarded blocks and trials. 

`demo` is a `data.frame` that contains all the trials identified as `demo` in the `blockcode` variable.

Store the first `data_keep` element in a data frame for the `compute_iat()` function. 

```{r}
iat_data <- iat_cleandata[[1]]
head(iat_data)
```


### Compute IAT D score

Once that IAT data have been cleaned with the `clean_iat()` function, it is possible to compute the *D* score by using the `compute_iat()` function.

This function only takes two arguments. The first argument is the data frame with class `iat_clean`, the second argument is a character specifying the *D* score algorithm for the computation.  To compute multiple *D* score algorithms at the same time, use the`multi_dscore()` function. 

```{r}
dscore <- compute_iat(iat_data, Dscore = "d3")
str(dscore)
```

The `compute_iat()` function results in a `data.frame` with class `dscore` containing a number of rows equal to the number of participants. The columns contain the *D* score and otehr useful information on the performance  of each respondent (see the documentation of the `compute_iat()` function for further details). The `IAT_rel()`, `descript_d()`, `d_point()`, and `d_density()` functions  require the object resulting from function `compute_iat()`. 

The IAT D is computed as such that positive scores indicate slower response times in condition identified by Mapping B. 

### IAT descriptive statistics and reliability

The `summary` method applied to the S3 object with class `dscore` returns basic descriptive statistics on the computed scores, as well as the label of the specific algorithm: 

```{r}
summary(dscore) 
```

The `IAT_rel()` function computes the reliability of the IAT by correlating the *D* score obtained from practice blocks with the *D* score obtained from test blocks [see @gaw2017 for further details]: 

```{r}
IAT_rel(dscore)
```

### Plotting the results

The `implicitMeasures` package comes with several functions for obtaining clear representations of the results at both individual respondent and sample levels by using the `plot` method on the S3 object of class `dscore`.

The default graphical representation is the histogram of the sample scores, depicted on the x-axis.

```{r, fig.align='center', fig.width=8, fig.height=6}
plot(dscore) # Data frame containing IAT D scores
```

The `graph` argument controls the specific type of graphical representation that is illustrated. For instance, `graph = "points"` allows for obtaing the representation of the individual scores.

```{r, fig.align='center', fig.width=8, fig.height=6}
plot(dscore, graph = "points",
       order_sbj = "D-decreasing", # change respondents order
       x_values = FALSE, # remove respondents' labels
       include_stats = TRUE, # include descriptive statistics
       col_point = "lightskyblue") # change points color
```





# Multiple D scores

The `multi_dscore()` function computes multiple *D* score algorithms. The *D* score algorithms that can be computed depend on the IAT administration. If the IAT administration included a feedback strategy (i.e., built-in correction), only *D1* and *D2* algorithms should be computed. If the IAT administration did not include a feedback strategy, then algorithms *D3*, *D4*, *D5*, and *D6* should be computed. An exhaustive and detailed illustration of the *D* score algorithms is provided in the "Implicit Measures" vignette. To specify the algorithms that can be computed, argument `ds` must be set equal to either `"built-in"` (for the computation of *D1* and *D2*) or `error-inflation` (for the computation of all other algorithms). Nonetheless, the function allows y default to compute all algorithms.

```{r}
multi_scores <- multi_dscore(iat_data, # object with class "iat_clean"
                             algorithms  = "error-inflation") # string specifying the 
                                            # algorithms to compute
```

The scores can be graphically compared by using the `plot` method, returning either the boxplots of the scores for each algorithm (default) or the by investigating the score of each respondent according to different algorithms, hence allowing for the investigation of potential inversions.

```{r}
plot(multi_scores)
plot(multi_scores, graph = "individual")
```


# References