---
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. 

The computation of the SC-IAT D is such that positive scores indicate slower response times in the condition labeled as mapping A.

### Descriptive statistics

The summary method can be applied on the SC-IAT results as well.

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



### 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. 

The plot method can be used as well on the SC-IAT results.


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


