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