#' computeTimeBetween
#
#' @description computeTimeBetween computes the duration between when an ESM questionnaire was started and when the subsequent one was finished, across all ESM questionnaires per person.
#
#' @param esDf a data.frame. A single ESM dataset. It must contain the 2 columns that hold the date-time object for when an ESM questionnaire was started and finished, respectively.
#
#' @param refDf a data.frame. The reference dataset.
#
#' @param RELEVANTVN_ES a list. This list is generated by function \code{\link{setES}} and it is extended once either by function \code{\link{genDateTime}} or by function \code{\link{splitDateTime}}.
#
#' @param RELEVANTVN_REF a list. This list is generated by function \code{\link{setREF}} and it is extended once either by function \code{\link{genDateTime}} or by function \code{\link{splitDateTime}}.
#
#' @return \code{esDf} with the additional column TBESQ, i.e. the T_ime B_etween E_xperience S_ampling Q_uestionnaires.
#
#' @importFrom lubridate as.interval ymd_hms as.period parse_date_time
#
#' @examples
#' # o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o
#' # Prerequisites in order to execute computeTimeBetween. Start -------
#' # Use example list delivered with the package
#' RELEVANTVN_ES <- RELEVANTVN_ESext
#' # Use example list delivered with the package
#' RELEVANTVN_REF <- RELEVANTVN_REFext
#' intoleranceDf <- data.frame(prompt = c(2, 3, 4, 1, 1),
#' expect = c(1, 1, 1, 2, 3))
#' # expectedDf is a raw ESM dataset, delivered with the package.
#' intolLs <- intolerable(expectedDf, intoleranceDf, RELEVANTINFO_ES)
#' randSelLs <- randomMultSelection(intolLs[["cleanedDf"]])
#' # Prerequisites in order to execute computeTimeBetween. End ---------
#' # -------------------------------------------------------
#' # Run function 28 of 29; see esmprep functions' hierarchy.
#' # -------------------------------------------------------
#' # randSelLs[["esRandSelIn"]] is the result of function 'randomMultSelection'.
#' tbsqDf <- computeTimeBetween(randSelLs[["esRandSelIn"]], referenceDfNew, RELEVANTVN_ES,
#' RELEVANTVN_REF)
#' # o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o=o
#
#' @seealso Exemplary code (fully executable) in the documentation of \code{\link{esmprep}} (function 28 of 29).
#
#' @export
#
computeTimeBetween <- function(esDf, refDf, RELEVANTVN_ES=NULL, RELEVANTVN_REF=NULL) {
# Possible errors when passing arguments to the function -----------------------------
if(!is.data.frame(esDf)) {
stop("Argument 'esDf' must be of type data.frame.")
}
# Error handling function for all set-up lists generated by setES and setREF.
# Both lists RELEVANTVN_ES and RELEVANTVN_REF get extended either by function
# genDateTime or by function splitDateTime!
SETUPLISTCheck(RELEVANTINFO_ES=NULL,
RELEVANTVN_ES=RELEVANTVN_ES,
RELEVANTVN_REF=RELEVANTVN_REF)
if(any(is.na(match(c("ID",
RELEVANTVN_ES[["ES_START_DATETIME"]],
RELEVANTVN_ES[["ES_END_DATETIME"]]),
names(esDf))))) {
stop(paste0("In order to compute the time lag the variables ",
"ID, ",
RELEVANTVN_ES[["ES_START_DATETIME"]]," and ",
RELEVANTVN_ES[["ES_END_DATETIME"]],
" must be part of the data.frame that is passed to this function."))
}
timeBetween <- c()
for(i in 1:nrow(refDf)) {
idx_i <- which(esDf[,"ID"] == refDf[i,RELEVANTVN_REF[["REF_ID"]]])
if(length(idx_i)==0) {
warning(paste0(as.character(refDf[i,RELEVANTVN_REF[["REF_ID"]]]), " isn't contained in current ESM dataset. Check warning message(s) of function 'esAssign'. It must say which IDs couldn't be assigned."))
} else if(length(idx_i) == 1) {
dateTime_i1 <- "1970-01-01 00:00:01"
timeBetween_i <- lubridate::as.period(lubridate::as.interval(lubridate::ymd_hms(dateTime_i1),
lubridate::ymd_hms(dateTime_i1)))
timeBetweenParse <-
suppressWarnings(lubridate::parse_date_time(paste0(timeBetween_i@hour, ":",
timeBetween_i@minute, ":",
timeBetween_i@.Data), "%H%M%S"))
timeBetween <- c(timeBetween, format(timeBetweenParse, "%H:%M:%S"))
} else {
timeBetweenDf_temp <- data.frame(timeEnd_temp=
# 1st column consists of date-time the prior questionnaire has been ended
c(as.character(esDf[idx_i[1],RELEVANTVN_ES[["ES_START_DATETIME"]]]),
as.character(esDf[idx_i[-length(idx_i)], RELEVANTVN_ES[["ES_END_DATETIME"]]])),
# 2nd column consists of date-time the subsequent questionnaire has been started
timeStart_temp=as.character(esDf[idx_i,RELEVANTVN_ES[["ES_START_DATETIME"]]]))
timeBetween_i <- lubridate::as.period(lubridate::as.interval(lubridate::ymd_hms(timeBetweenDf_temp[,1]),
lubridate::ymd_hms(timeBetweenDf_temp[,2])))
timeBetweenParse <-
suppressWarnings(lubridate::parse_date_time(paste0(timeBetween_i@hour, ":",
timeBetween_i@minute, ":",
timeBetween_i@.Data), "%H%M%S"))
timeBetween <- c(timeBetween, format(timeBetweenParse, "%H:%M:%S"))
}
}
# T_ime that has passed b_etween s_ubsequent q_uestionnaires = tbsq
esDf[,"TBSQ"] <- timeBetween
return(esDf)
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.