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

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

```{r setup, echo = FALSE}
library(implicitMeasures)
library(knitr)
library(tidyverse)
```

This vignette gives an overview of the `implicitMeasures` package. 
The structure of the Implicit Association Test [IAT; @Greenwald:1998] and that of the Single Category IAT [SC-IAT; @karp:2006] are illustrated, as well as the algorithms used for the computation of their scores. A brief description of the data set included in the package (i.e., `raw_data`) is given as well. 

## The Implicit Association Test

The IAT is used for assessing the strength and direction of automatic associations between two target categories (i.e., *Object 1* and *Object 2* in Table 1) and two evaluative dimensions, *Positive* and *Negative*. It is mostly used in social psychology for obtaining a measure of people's attitudes towards different social groups. It is also used in marketing research for assessing people preferences towards contrasting brands, or in clinical psychology to assess both functional (i.e., self-esteem) and dysfunctional (i.e., personality disorders) personality traits. 
The advantages of the IAT are related to the fact that it provides a measure of all the above-mentioned constructs without directly asking them, but by measuring the speed and accuracy with which prototypical exemplars of the two targets and of the two evaluative dimensions are sorted in the category to which they belong. 

The IAT (Table 1) is usually composed of seven blocks. Three blocks (B1, B2 and B5 in Table 1) are pure practice blocks in which either target stimuli (Blocks B1 and B5) or attribute stimuli (Block B2) are sorted in their reference categories. The remaining blocks are the associative blocks that constitute the two mappings conditions of the IAT (e.g., Mapping A and Mapping B). In Blocks B3 and B4, exemplars of *Object 1* share the response key with *Positive* exemplars, while exemplars of *Object 2* share the response key with *Negative* exemplars. In the contrasting associative condition (i.e., Blocks B6 and B7), the categorization task is reversed. Exemplars of *Object 1* share the response key with *Negative* exemplars and exemplars of *Object 2* share the response key with *Positive* exemplars. 
Usually, the practice and associative practice blocks are composed of 20 trials each, while the associative test blocks are composed of 40 trials each. The two mapping conditions result in 60 trials each. 


```{r, echo = FALSE}
library(data.table)
iat <- data.table(Block = paste0("B",1:7), Function = c(rep("Practice", 2), "Associative Practice Mapping A", "Associative Test Mapping A", "Practice", "Associative Practice Mapping B", "Associative Test Mapping B"), "Left response key" = c("Object 1", "Positive", "Object 1 + Positive", "Object 1 + Positive",  "Object 2", "Object 2 + Positive", "Object 2 + Positive"), "Right response key" = c("Object 2", "Negative", "Object 2 + Negative", "Object 2 + Negative", "Object 1", "Object 1 + Negative", "Object 1 + Negative") )

kable(iat)

```

During IAT administration, respondents might be given a feedback. In case a stimulus is sorted into the incorrect category, a red cross appears on the screen and the response must be corrected to proceed with the experiment. If a feedback strategy is not included, the error response is not signaled to participants, and they can go on with the experiment. 

The *IAT effect* is given by the difference in respondents' performance between the two associative conditions, under the assumption that the categorization task is easier (i.e., faster response times and higher response accuracy) in the associative condition consistent with respondents' automatic association. The *D* score [@Greenwald:2003] is usually employed for expressing the strength and direction of the IAT effect. Six different algorithms are available for the computation of the *D* score (Table 2). The differences between the algorithms lie in the strategies used for treating error and fast responses, while the core procedure remains the same. 

```{r, echo = FALSE}
data.table(Dscore = paste0(rep("D", 6), 1:6), 
                      "Error treatment" = c(rep("Built-in", 2), "Mean + 2sd", "Mean + 600ms", 
                                            "Mean +2 sd", "Mean + 600ms"), 
                      "Lower tail treatment" = c("No", "< 400ms", "No", "No", "< 400ms", "< 400ms")) %>% kable()

```

Irrespective of the algorithm, trials with a response latency exceeding 10,000ms must be excluded. When participants are given a feedback for their error responses, the algorithms using a built-in correction (*D1* and *D2*) must be used. In these cases, the error responses are replaced by the time at the incorrect response increased by the time needed to correct it. All the other algorithms (*D3* to *D6*) are used when IAT administration does not include a feedback. The error responses are replaced by the average response time of the block in which the error occurred increased by a standard penalty (i.e., either 600ms or twice the standard deviation of the block). The other feature distinguishing the algorithms regards the decision to include responses faster than 400ms or not. 

Once the algorithm has been chosen and the error and fast responses have been treated accordingly, it is possible to compute the *D* score following a 3-step procedure: 

1. Compute the *D* score for the associative practice blocks (i.e., $D_{practice}$) by taking the difference between the average response time in the two contrasting associative practice blocks (Blocks B3 and B6 in Table 1). The difference is divided by the standard deviation computed on the pooled trials of both blocks.

2. Compute the *D* score for the associative test blocks (i.e., $D_{test}$) by taking the difference between the average response time in the two contrasting associative test blocks (Blocks B4 and B7 in Table 1). The difference is divided by the standard deviation computed on the pooled trials of both blocks.

3. Compute the actual *D* score as the mean of $D_{practice}$ and $D_{test}$. 

`implicitMeasures` also includes a function (`IAT_rel()`) for computing IAT reliability as the correlation between $D_{practice}$ and $D_{test}$ [see @gaw2017]. 

## The Single Category Implicit Association Test

The IAT is particularly suitable when the aim is to obtain a comparative measure of the attitudes towards *Object 1* in relation to *Object 2*. However, there are cases in which it is more useful to have an absolute information of the positive or negative evaluation of just one of the target categories.
The SC-IAT [Table 3; @karp:2006] has been proposed as an alternative to the IAT to provide a measure of the absolute positive or negative evaluation towards just one target. It results from a modification of the IAT procedure, where one of the target categories is dropped. Blocks B1 and B3 are associative practice blocks, usually composed by 24 trials. Blocks B2 and B4 are the actual test blocks, usually composed by 72 trials. 
The first associative condition is composed of Blocks B1 and B2, where exemplars of the target category *Object 1* share the response key with *Positive* exemplars while *Negative* exemplars are mapped with the other response key. In the opposite condition, exemplars of the target category *Object 1* share the response key with *Negative* exemplars, and *Positive* exemplars are sorted with the opposite response key. 

```{r, echo = F}
data.table(Block = paste0("B",1:4), 
           Function = paste(rep(c("Associative practice", "Associative test"), 2), 
                            rep(c("Mapping A", "Mapping B"), c(2,2))),
           "Left response Key" = c(rep("Object 1 + Positive", 2), rep("Positive", 2)), 
           "Right response Key" = c(rep("Negative", 2), rep("Object 1 + Negative", 2))) %>% kable()
```

During the SC-IAT administration, respondents receive a feedback signaling whether the response was correct (a green "O") or incorrect (a red "X"). A response time window (rtw) at 1,500ms is included in the administration, after which the stimulus on the screen disappears. Responses exceeding the rtw are considered non-response. However, there also cases in which the SC-IAT administration does not include any of these features. 

The *SC-IAT effect* results from the difference in respondents' performance between the two associative conditions, under the assumption that the task is easier in the condition consistent with respondents' automatic association. 

A modification of the IAT *D* score has been proposed to interpret the SC-IAT effect [@karp:2006]. Only Blocks B2 and B4 are used for the computation of the SC-IAT *D* score. Fast responses (responses under 350ms) are discarded, as well as non-responses (responses exceeding the rtw). Error responses are replaced by the average response time in which the error occurred increased by a standard penalty of 400ms. The difference between the average response time in the two contrasting conditions is standardized by the standard deviation of the correct trials in both conditions. 


## The `raw_data` data set

The `raw_data` contains the data from `r length(unique(raw_data$Participant))` respondents administered with an IAT for the implicit assessment of the preference between Dark and Milk chocolate (Chocolate IAT), a SC-IAT for the assessment of the absolute positive or negative evaluation of Milk chocolate (Milk SC-IAT), and a SC-IAT for the implicit assessment of the absolute positive or negative evaluation of Dark Chocolate SC-IAT (Dark SC-IAT), along with their demographic information. These data are published in @epifania2020.

The IAT administration did not include a feedback strategy, hence only the *D* score algorithms not including a built-in correction should be computed. 

```{r}
# upload the data set
data(raw_data)

# explore the dataset
head(raw_data)

str(raw_data)
```

The data set contains respondents' IDs (`Participant`), response times in milliseconds for each trial (`latency`), response accuracy (`correct`, 1 for correct responses and 0 for incorrect responses), trials and blocks labels of the implicit measures (`trialcode` and `blockcode` labels, respectively), and the type of response (`response`, identifying the trials of either the implicit measures or of the demographic information).

## Importing data from SPSS

If you are importing data from SPSS, no worries. Both `clean_iat()` and `clean_sciat()` functions recognize whether the data set is coming from SPSS and will take care of that. To import the data set from SPSS, you can use either `haven::read_sav("dataset.sav")` or `foreign::read.spss("dataset.sav")`. Please leave all the defaults settings unaltered.

# References
