Package 'arse'

Calculates the area of growth above a baseline.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For a given set of x-coordinates over time and repeated measures of a 'y' variable, this function calculates the area of growth (aog) that is formed above the specified baseline value of 'y' using an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons. Larger aog values are indicative of more growth on the measured variable.

Usage

aog(data, xcoord, ycoord, ybase = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated aog values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated aog values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated aog values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated aog values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,95,80,75,75,75))
dataset1 <- data.frame(xc, yc)
aog(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20], saveout = TRUE)

---

Calculates the area of resilience to stress event below a baseline.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For a given set of x-coordinates over time and repeated measures of a 'y' variable, this function calculates the area of resilience to a stress event (arse) that is formed below the specified baseline value of 'y' using an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons. Any area above the baseline (i.e., growth) is ignored. Smaller arse values are indicative of better resilience on the measured variable.

Usage

arse(data, xcoord, ycoord, ybase = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated arse values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated arse values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,35,50,75,75,75))
dataset1 <- data.frame(xc, yc)
arse(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20], saveout = TRUE)

---

Calculates the area of resilience to stress event below a baseline with scaling for end state growth or non-resilience.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For a given set of x-coordinates over time and repeated measures of a 'y' variable, this function calculates the area of resilience to a stress event (arse) that is formed below the specified baseline value of 'y' using an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons. With arse calculated, the arse is scaled in reference to the end state value by multiplying the arse value by the division of baseline value over the end state value (i.e., last measured value of 'y') or $arse value * (baseline value/end state value)$. Smaller arse_s values are indicative of better resilience on the measured variable.

Usage

arse_s(data, xcoord, ycoord, ybase = NA, yend = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yend	A specified selection of the end state of the 'y' measured variable. Users are advised to place end state as the last instance of the y-coordinate values. Function defaults to use the last y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated arse_s values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_s values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated arse_s values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_s values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,35,46,49,49,51))
dataset1 <- data.frame(xc, yc)
arse_s(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20], saveout = TRUE)

---

Calculates the area of resilience to stress event below a baseline with subtraction of area of growth.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For a given set of x-coordinates over time and repeated measures of a 'y' variable, this function calculates the area of resilience to a stress event (arse) that is formed below the specified baseline value of 'y' using an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons. Area of growth (aog) is calculated in the same manner by calculating the area formed by points above the baseline. With both areas calculated, the arse is subtracted from aog creating a new variable, arse_t. Smaller arse_t values are indicative of better resilience on the measured variable.

Usage

arse_t(data, xcoord, ycoord, ybase = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated arse_t values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_t values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated arse_t values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_t values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,95,80,75,75,75))
dataset1 <- data.frame(xc, yc)
arse_t(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20], saveout = TRUE)

---

Calculates the area of resilience to stress event below a baseline with subtraction of area of growth and scaling for end state growth or non-resilience.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For a given set of x-coordinates over time and repeated measures of a 'y' variable, this function calculates the area of resilience to a stress event (arse) that is formed below the specified baseline value of 'y' using an implementation of the shoelace formula (Gauss's area formula) for the area of irregular polygons. The function also calculates the area of growth (aog) that is formed above the specified baseline in the same manner as arse. The function then subtracts the arse from aog to get a new variable, arse_t. With arse_t calculated, it is scaled in reference to the end state value by (a) if arse_t is greater than or equal to zero, multiplying the arse_t value by the division of baseline value over the end state value (i.e., last measured value of 'y') or $arse value * (baseline value/end state value)$ or (b) if arse_t is less than zero, multiplying the arse_t value by the division of end state value over the baseline value (i.e., last measured value of 'y') or $arse value * (end state value/baseline value)$. Smaller arse_s values are indicative of better resilience on the measured variable.

Usage

arse_ts(data, xcoord, ycoord, ybase = NA, yend = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yend	A specified selection of the end state of the 'y' measured variable. Users are advised to place end state as the last instance of the y-coordinate values. Function defaults to use the last y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated arse_ts values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_ts values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated arse_ts values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated arse_ts values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,75,77,79,80,81,77,76,77,77))
dataset1 <- data.frame(xc, yc)
arse_ts(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20], saveout = TRUE)

---

arsefigures

Description

Dataset used to demonstrate different manifestations of arse. Cases correspond to different figures from a forthcoming arse method paper. Figure number and panel are noted #' in the last column. Additional data is also added to test other situations that might occur with data sources (e.g., different baselines, interpolation of points).

Usage

bar

Format

A dataframe with 11 rows and 22 columns. There are 10 total examples.

---

Calculates a count of the time beneath the baseline.

Description

This function takes a series of y-coordinates and returns a count of y-coordinates that fall beneath the specified baseline after the intrusion of a stress event (i.e., rapidity).

Usage

count_rapidity(data, ycoord, ybase = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated count_rapidity values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated count_rapidity values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated count_rapidity values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated count_rapidity values.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,35,50,75,75,75))
dataset1 <- data.frame(xc, yc)
count_rapidity(data = dataset1, ycoord = dataset1[,11:20], saveout = TRUE)

---

Calculates x-coordinate interpolation points across a baseline.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value. For any two sequential x-coordinate points, where the 'y' baseline value is crossed in between them, the function calculates the predicted x-coordinate value and interpolates that point with the matching 'y' baseline value. The new points are then added to the original set of 'x,y' coordinates. Note that all the prefixed arse functions automatically perform this operation within their respective functions.

Usage

getintersectx(data, xcoord, ycoord, ybase = NA)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
xcoord	A specified selection of the x-coordinate values within the dataframe.
ycoord	A specified selection of the y-coordinate values within the dataframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.

Value

A dataframe of old and newly-interpolated x-coordinate values at the specified baseline.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,95,35,50,75,75,75))
dataset1 <- data.frame(xc, yc)
getintersectx(data = dataset1, xcoord = dataset1[,1:10], ycoord = dataset1[,11:20])

---

Calculates the mean robustness after a stress event.

Description

This function takes a series of y-coordinates and returns the average deviation from the specified baseline after the intrusion of a stress event (i.e., robustness). Magnitude is indicated by how large the mean_robust value becomes. Direction of the robustness is indicated by a positive or negative value; negative numbers indicate a departure below the baseline while positive numbers indicate a departure above the baseline.

Usage

mean_robust(data, ycoord, ybase = NA, yinvert = FALSE,
  saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
ycoord	A specified selection of the y-coordinate values within the dataframe. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated mean_robust values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated mean_robust values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated mean_robust values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated mean_robust values.

Examples

yc <- t(c(75,53,37,25,27,35,50,75,75,75))
dataset1 <- data.frame(yc)
mean_robust(data = dataset1, ycoord = yc, saveout = TRUE)

---

Plots the area of resilience to stress event.

Description

This function takes a series of 'x,y' coordinates and a specified 'y' baseline value and plots them on an x- and y-axis.

Usage

plot_arse(xcoord, ycoord, ybase = NA, ll, ul, xlab = NA, ylab = NA)

Arguments

xcoord	A specified selection of the x-coordinate values within a vector. The first x-coordinate value should correspond to the baseline input of 'y'.
ycoord	A specified selection of the y-coordinate values within a vector. The first y-coordinate value should correspond to the baseline value of 'y'. The second y-coordinate value should be the first measure of 'y' after the intrusion of a stress event. The last value of 'y' should correspond to the last measurement of 'y' over the measured timeframe.
ybase	A specified selection of the baseline of the 'y' measured variable. Users are advised to place baseline as the first instance of the y-coordinate values. Function defaults to use the first y-coordinate value in the series.
ll	Sets the lower limit of the y-axis scale. Recommended to be the lowest possible value of your 'y' measure.
ul	Sets the upper limit of the y-axis scale. Recommended to be the highest possible value of your 'y' measure.
xlab	Labels the x-axis. Defaults to "Time (X)".
ylab	Labels the y-axis. Defaults to "Outcome (Y)".

Value

Returns a graph with 'x,y' coordinates and baseline.

Examples

xc <- t(c(1,2,3,4,5,6,7,8,9,10))
yc <- t(c(75,53,37,25,27,35,50,75,75,75))
dataset1 <- data.frame(xc, yc)
plot_arse(xcoord = as.numeric(dataset1[,1:10]),
ycoord = as.numeric(dataset1[,11:20]), ll = 0, ul = 100)

---

stress_appraisal

Description

Fictitious dataset used to demonstrate the calculation of arse. In this dataset, there are 50 fictitious cases split into two groups with 25 members each (i.e., 'group' variable). The control condition represents cases in which training was not given before a stress event. In the 'Appraisal_Training' condition, cases 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 (i.e., 'tby') is measured on the case's ability to place 100 colored-pegs in a specified patterned grid in one minute. Following baseline measurement, a stress event occurs for all cases 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 cases are asked to perform the peg task four more times with different patterns to match. Cases perform the peg task at three minute intervals. The fourth time the case performs the task (i.e., t4y) represents the case's endstate at the end of the fictitious experiment. In the dataset, t#x values represent time on the x-axis.

Usage

bar

Format

A dataframe with 51 rows and 12 columns. There are 50 total cases.

Source

Fictitious dataset. All values generated.

---

Calculates the nadir point of measured 'y' values.

Description

This function takes a series of y-coordinates and returns the lowest value.

Usage

ynadir(data, ycoord, yinvert = FALSE, saveout = FALSE)

Arguments

data	A dataframe with x- and y-coordinates in wide format.
ycoord	A specified selection of the y-coordinate values within the dataframe.
yinvert	Specifies whether resilience occurs above or below the baseline depending on the meaning of high and low 'y' values. When parameter 'yinvert' is set to 'FALSE' (the default), it is assumed that higher numbers are indicative of positive (i.e., desired) 'y' values (e.g., exam grade). When 'yinvert' is set to 'TRUE', it is assumed that lower numbers are indicative of positive (i.e., desired) 'y' values (e.g., blood pressure).
saveout	When the parameter 'saveout' is set to 'FALSE' (the default), a vector of calculated ynadir values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated ynadir values.

Value

When the parameter 'saveout' is set to 'FALSE', a vector of calculated ynadir values are given for each case. When 'saveout' is set to 'TRUE', a dataframe of the original inputted dataset is returned with a new column of calculated ynadir values.

Examples

yc <- t(c(75,53,37,25,27,35,50,75,75,75))
dataset1 <- data.frame(yc)
ynadir(data = dataset1, ycoord = yc, saveout = TRUE)

---