--- title: "arse_walkthrough" author: - Nathaniel Ratcliff - Devika Nair - Joshua Goldstein date: "5/12/2019" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{arse_walkthrough} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## Introduction This document is intended to serve as a step-by-step guide to using the area of resilience to stress event (ARSE) method of quantifying the resilience process using the 'arse' R package. This guide is a companion to a paper introducing the ARSE method (Ratcliff, Nair, & Goldstein, *under review*). For ARSE, the resilience process is conceptualized as: for a given ‘y’ outcome occurring over time, resilience is characterized by the function of robustness (i.e., the degree of negative departure from the baseline of y) and rapidity (i.e., time to the return to baseline of y) in relation to the incursion of a stress event on an entity. To use this method, three things must be in place: (a) a baseline value (before the stress event) of a variable of interest 'y' needs to be known, (b) an incursion of a stress event needs to occur on an entity (e.g., individual, group), and (c) the variable of interest 'y' needs to be measured repeatedly after the incursion of a stress event. Thus, ARSE is the function of how much the variable 'y' negatively diverges from baseline levels after a stress event (i.e., robustness) and the time it takes 'y' to return to baseline levels (i.e., rapidity). The combination of robustness and rapidity form a series of points that can be connected into an irregular polygon from which an area can be derived. It is this area, ARSE, that is indicative of how much resilience is demonstrated to a stress event where smaller values of ARSE indicate better resilience and larger values indicate poor resilience. It should be noted that we refer to decreases as a default way of discussing departures from baseline levels, however, for variables in which higher numbers are characterized as less desirable (e.g., blood pressure), negative departures from the baseline would be increases from the baseline. The ARSE functions discussed below have an option 'yinvert' that accommodate cases in which higher values are not desirable. For the purposes of this walkthrough, we assume that higher values are more desirable and that decreases from the baseline level are not. The following presents a step-by-step guide to analyzing ARSE using a fictitious data set. ## Installation of arse R Package To install arse, use `install.packages("arse")` in R or RStudio. Alternatively, the development version of the arse package can be downloaded from github using `devtools::install_github("nr3xe/arse")`. ## Load arse Package, Dependent Packages (dplyr, pracma), and the 'stress_appraisal' Data Set ```{r setup} # Required R packages that need to be loaded library(arse) library(dplyr) library(pracma) ``` ## Description of stress_appraisal Data Set A Fictitious data set was used to demonstrate the calculation of ARSE In this data set, there are 50 fictitious "subjects" split into two groups with 25 members each (i.e., 'group' variable). The *Control* condition represents subjects in which training was not given before a stress event. In the *Appraisal_Training* condition, subjects were given a training to help cognitively reappraise a stressful situation and think of strategies to adapt to a stressor. Before random assignment to group condition, a baseline **'tby'** is measured on the subject's ability to place 100 colored-pegs in a specified patterned grid in one minute. Following baseline measurement, a stress event occurs for all subjects where they are asked to dip their hand in a bath of ice cold water for one minute (or as long as they can stand). Following the stress event, the subjects are asked to perform the peg task four more times with different patterns to match. subjects perform the peg task at three minute intervals. The fourth time the subject performs the task **'t4y'** represents the subject's end state at the end of the fictitious experiment. In the data set, **'t#x'** values represent time on the x-axis using x-coordinates. ```{r} # Dataframe of stress_appraisal data set head(stress_appraisal, 10) # shows the first ten rows of the 'stress_appraisal' ficticious data set found in the arse package ``` ### stress_appraisal Layout Viewed above, the stress_appraisal data set has 12 columns and 50 rows that represent individual subjects. Each of the columns represent the following - subj = subject number - group = experimental condition * Control = Control condition receiving no training * Appraisal_Training condition = Experimental condition receiving training - tbx = x-coordinate of baseline measure of peg performance - t1x--t4x = x-coordinates of additional measured peg performance measure (t4x = end state x-coordinate) - tby = baseline measure of peg performance (0--100 scale) - t1y--t4y = y-coordinates of additional measured peg performance measure (t4y = end state y-coordinate) ### Data Organization To organize the data set, the baseline x-coordinate should be the first column of x-coordinates. Accordingly, the baseline y-coordinate value should be the first column of the y-coordinates. The functions within the `arse` package will default to the first column of y-coordinates as the baseline value. ## ARSE Plot of Subject #1 To plot an example case of ARSE, the `plot_arse` function provides a rough picture of the pattern of resilience. To plot a single case of arse, the `plot_arse` function requires a vector of x-coordinates and a vector of y-coordinates. The baseline value defaults to the first column of the y-coordinates but can be specified with the `ybase = ` argument. Below, we indicate where in our dataframe the x- and y-coordinates are located and enter them as vectors using the `as.integer()` prefix. The lower and upper limits of the displayed scale are specified using the `ll =` and `ul =` respectively (a best practice is to indicate the full range of possible values for the scale of 'y' or reflect the full range of observed values). ```{r} # Plot of ARSE for single subject plot_arse(xcoord = as.integer(stress_appraisal[1,3:7]), ycoord = as.integer(stress_appraisal[1, 8:12]), ll=0, ul=100, xlab = "Trial Number", ylab = "Number of Pegs") ``` ### Description of Subj #1 Plot From the plot above, you can see that the baseline is 64 and that, in this case, resilience was not achieved since the end state is below the baseline at a value of 47. ## Calculating ARSE for Subject #1 To calculate ARSE from our example case, the `arse` function is used. The `arse` function requires three arguments: data, xcoord, and ycoord. For data, indicate the dataframe that is being used, in our example this would be `stress_appraisal`. For `xcoord`, a dataframe of x-coordinates is required with the first column having the x-coordinate of the baseline value of 'y'. For `ycoord`, a dataframe of y-coordinates is required with the first column having the baseline value of 'y'. The baseline value defaults to the first column of the y-coordinates but can be specified with the `ybase =` argument (we strongly suggest that users rely on the default using the first column of x- and y-coordinates). The `arse` function only calculates the area below the baseline; any points above the baseline (i.e., growth) are set to the baseline level to only calculate the area beneath the baseline. The `arse` function, as well as the related ARSE functions, will provide interpolation points for x-coordinates where the line between two points crosses the baseline at a point not measured in the data (using a function analogous to the `getintersectx` function in the `arse` package (see help for more details). In the example below, the first row of the dataframe is selected with the corresponding columns for the x- and y-coordinates. To calculate ARSE, an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons is used with the (`polyarea()`) function from the `pracma` package. The `arse` function also has two additional arguments that can be specified: `yinvert` and `saveout`. The `yinvert` argument can be used to calculate ARSE depending on how the range of values of 'y' are to be interpreted. By default, `yinvert = FALSE` and assumes that higher values of 'y' are more desirable or positive. However, if higher values of 'y' are not desireable and lower values are, then `yinvert = TRUE` will calculate ARSE assuming that values above the baseline represent resilience and values below the baseline represent growth. Lastly, the `saveout` argument is set to FALSE by default and will just return a vector of values for the ARSE calculation. When set to TRUE, `saveout` will return the original dataframe and add a column of the calculated ARSE values. ```{r} # Returns area of resilience to stress event (ARSE) for single subject arse(data = stress_appraisal, xcoord = stress_appraisal[1, 3:7], ycoord = stress_appraisal[1, 8:12]) ``` ### The result of ARSE The function returns an ARSE value of 87.5. This area was calculated by using the x- and y-coordinates that form an irregular polygon. Since resilience was not achieved in this example (i.e., the end state value did not return or exceed the baseline), an additional point is interpolated at the same x-coordinate as the end state value with a y-coordinate value at the baseline (i.e., x = 4, y = 64). Doing so completes the appropriate shape to calculate ARSE. ## Calculating AoG for Subject #4 In some cases, users may want to know how much growth a subject might have experienced (see plot below). ```{r} # Plot of area of growth (AoG) for single subject plot_arse(xcoord = as.integer(stress_appraisal[4,3:7]), ycoord = as.integer(stress_appraisal[4, 8:12]), ll=0, ul=100, xlab = "Trial Number", ylab = "Number of Pegs") ``` The plot shows that Subject #4 experienced growth (i.e., 'y' values above the baseline) after the incursion of a stress event. To calculate areas of growth, the `aog` function is used. This function is exactly the same as the `arse` function above except that instead of setting values above the baseline to the baseline, `aog` sets values below the baseline to the baseline to only look at the area above the baseline. ```{r} # Returns area of growth (AoG) value for single subject aog(data = stress_appraisal, xcoord = stress_appraisal[4, 3:7], ycoord = stress_appraisal[4, 8:12]) # Returns area of resilience to stress event (ARSE) value for single subject arse(data = stress_appraisal, xcoord = stress_appraisal[4, 3:7], ycoord = stress_appraisal[4, 8:12]) ``` ### The Result of AoG and ARSE The result of `aog` returns a value of 25.58 indicating the area of growth for Subject #4. However, since the subject had an end state value below the baseline (t4y = 61), `arse` can also be calculated and return a value of 0.08. In this case, more growth was achieved for the subject with a small area of resilience, indicating a good response to the stress event. ## Calculating ARSE~T~ for Subject #4 In some cases, users may want to take into account both resilience and growth. There is also a function, `arse_t`, that calculates the area of resilience (`arse`) and area of growth (`aog`) and takes their difference (i.e., $ARSE_T = ARSE - AoG$) to get a total area value for resilience. In these cases, ARSE can be positive and negative depending on whether the area of resilience or area of growth is larger. ```{r} # Returns area of resilience to stress event total (ARSE_T) value for single subject arse_t(data = stress_appraisal, xcoord = stress_appraisal[4, 3:7], ycoord = stress_appraisal[4, 8:12]) ``` ### The result of ARSE~T~ The result of `arse_t` returns a value of -25.5 which reflects the subtraction of ARSE (0.08) from AoG (25.58). A negative returned value indicates that the area of growth was larger than the area of resilience. ## Calculating ARSE~S~ for Subject #1 In some cases, users may want to account for the end state being above the baseline (growth) or below the the baseline (non-resilience). The `arse_s` function provides a scaling factor that accounts for the end state where $ARSE_S = ARSE * (Baseline/End State)$. When the end state is below the baseline, the scaling factor will make ARSE larger and when the end state is above the baseline, the scaling factor will make ARSE smaller. ```{r} # Returns area of resilience to stress event scaled (ARSE_S) value for single subject arse_s(data = stress_appraisal, xcoord = stress_appraisal[1, 3:7], ycoord = stress_appraisal[1, 8:12]) ``` ### The Result of ARSE~S~ The result of `arse_s` returns a value of 119.15. Recall that the `arse` value for this subject was 87.5 with a baseline value of 64 and an end state value of 47. Thus, $ARSE_S = 87.5 * (64/47)$ or $ARSE_S = 87.5 * 1.36$ which returns a larger area (vs. the un-scaled ARSE) of 119.15. ## Calculating ARSE~TS~ for Subject #4 In some cases, users may want to account for both growth and the end state value; the `arse_ts` function combines aspects of both `arse_t` and `arse_s`. Specifically, `arse_ts` is calculated as follows: for `arse_t` values that are >= 0, $ARSE_T._S = ARSE_T * (Baseline/End State)$ while for `arse_t` values that are < 0, $ARSE_T._S = ARSE_T * (End State/Baseline)$. The two different calculations are needed to account for scaling positive and negative values of `arse_t`. For instance, if `arse_t` is negative and the the end state is above the baseline, then the end state value needs to be in the numerator so that the scaling factor can make a negative value larger (versus smaller when `arse_t` is zero or positive). ```{r} # Returns area of resilience to stress event total scaled (ARSE_TS) for single subject arse_ts(data = stress_appraisal, xcoord = stress_appraisal[4, 3:7], ycoord = stress_appraisal[4, 8:12]) ``` ### The Result of ARSE~TS~ The result of `arse_ts` returns a value of -25.09. Recall that `arse_t` for this subject was -25.5 with a baseline of 62 and an end state of 61. Thus, $ARSE_T._S = -25.5 * (61/62)$ or $ARSE_TS = -25.5 * (0.98)$ which returns a smaller negative value (vs. un-scaled ARSE~T~) of -25.09. ## Calculating ARSE for Entire Sample Calculation of `arse` and the ARSE family of functions for the entire sample is the same as for individual cases. ```{r} # Returns area of resilience to stress event (ARSE) for entire sample with modified data set including calculated ARSE values print(arse(data = stress_appraisal, xcoord = stress_appraisal[3:7], ycoord = stress_appraisal[8:12], saveout = TRUE), digits = 2) ``` ## Calculating ARSE~T~ for Entire Sample ```{r} # Returns area of resilience to stress event total (ARSE_T) for entire sample with modified data set including calculated ARSE_T values arse_t(data = stress_appraisal, xcoord = stress_appraisal[3:7], ycoord = stress_appraisal[8:12], saveout = TRUE) ``` ## Calculating ARSE~S~ for Entire Sample ```{r} # Returns area of resilience to stress event scaled (ARSE_S) for entire sample with modified data set including calculated ARSE_S values print(arse_s(data = stress_appraisal, xcoord = stress_appraisal[3:7], ycoord = stress_appraisal[8:12], saveout = TRUE), digits = 2) ``` ## Calculating ARSE~TS~ for Entire Sample ```{r} # Returns area of resilience to stress event total scaled (ARSE_TS) for entire sample with modified data set including calculated ARSE_TS values print(arse_ts(data = stress_appraisal, xcoord = stress_appraisal[3:7], ycoord = stress_appraisal[8:12], saveout = TRUE), digits = 3) ``` ## Calculating ARSE~TS~ for Entire Sample and Comparing Groups with a *t*-test In this example, we first calculate values of `arse_ts` for the entire sample and create a new column 'arse_ts' by saving the new dataframe as a new object 'data1'. Second, we perform a *t*-test by comparing the control and appraisal_training groups under the 'group' factor. ```{r} # Returns area of resilience to stress event total scaled (ARSE_TS) for entire sample with modified data set including calculated ARSE_TS values data1 <- arse_ts(data = stress_appraisal, xcoord = stress_appraisal[3:7], ycoord = stress_appraisal[8:12], saveout = TRUE) t.test(data1$arse_ts ~ data1$group) ``` ```{r} # Boxplot of two group conditions boxplot(data1$arse_ts~data1$group, data = data1, xlab="Trials", ylab="Number of Pegs") ``` ### The Result of *t*-test comparing the Control Group to Appraisal Training Group The result of the *t*-test reveals a significant difference between the two groups at an alpha level of 0.05. Specifically, subjects in the appraisal training condition had smaller ARSE~TS~ values (*M* = 21.27) compared to the control condition (*M* = 109.92). ### Plotting ARSE of Control Group Using Mean Values of Y-Coordinates ```{r} # Plots the mean values of 'y' across x-coordinates for the control group stress_appraisal_group <- subset(stress_appraisal, group == "Control", select = c("subj", "group", "tbx", "t1x", "t2x", "t3x", "t4x", "tby", "t1y", "t2y", "t3y", "t4y")) plot_arse(xcoord = as.integer(stress_appraisal_group[1,3:7]), ycoord = c(mean(stress_appraisal_group[,8]),mean(stress_appraisal_group[,9]),mean(stress_appraisal_group[,10]), mean(stress_appraisal_group[,11]), mean(stress_appraisal_group[,12])), ll=0, ul=100, xlab = "Trial Number", ylab = "Number of Pegs") ``` The plot above reflects the mean values of the 'y' variable at each time interval to show the average shape of the ARSE for subjects in the control condition. ### Plotting ARSE of Appraisal Training Group Using Mean Values of Y-Coordinates ```{r} # Plots the mean values of 'y' across the x-coordinates for the appraisal training group stress_appraisal_group <- subset(stress_appraisal, group == "Appraisal_Training", select = c("subj", "group", "tbx", "t1x", "t2x", "t3x", "t4x", "tby", "t1y", "t2y", "t3y", "t4y")) plot_arse(xcoord = as.integer(stress_appraisal_group[1,3:7]), ycoord = c(mean(stress_appraisal_group[,8]),mean(stress_appraisal_group[,9]),mean(stress_appraisal_group[,10]), mean(stress_appraisal_group[,11]), mean(stress_appraisal_group[,12])), ll=0, ul=100, xlab = "Trial Number", ylab = "Number of Pegs") ``` The plot above reflects the mean values of the 'y' variable at each time interval to show the average shape of the ARSE for subjects in the appraisal training condition. ## References Ratcliff, N. J., Nair, D. T., & Goldstein, J. R. (*under review*). The Area of Resilience to Stress Event (ARSE): A New Conceptual Clarification and Method for Quantifying the Process of Resilience.