esmprep (version 0.2.0)

suggestShift: suggestShift

Description

suggestShift registers all ESM prompts that are eligible to be modified.

Usage

suggestShift(esDf, timeLagMinutes = NULL, RELEVANTINFO_ES = NULL,
  RELEVANTVN_ES = NULL)

Arguments

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.

timeLagMinutes

a numeric value. Specify the time difference in minutes for questionnaires that might be shifted to a neighboring prompt. See Details for more information.

RELEVANTINFO_ES

a list. This list is generated by function setES.

RELEVANTVN_ES

a list. This list is generated by function setES and it is extended once either by function genDateTime or by function splitDateTime.

Value

a list. If at least one prompt is suggested for shifting, a list containing the following 3 data.frames is returned:

1. the first data.frame (called 'esDf') is the raw ESM dataset in its current state (with new colums SHIFT, SHIFTKEY, and LAG_MINUTES),

2. the second data.frame (called 'suggestShiftDf') includes all relevant information to act according to the decision as to which questionnaires shall be shifted. See Examples in function makeShift to get a clear idea of how to use 'suggestShiftDf',

3. the third data.frame (called 'printShiftDf') contains the relevant information to print all questionnaires registered by suggestShift to the console, before as well as after having made the shifting. This printing to the console is done by applying the function printSuggestedShift.

If no prompt is suggested for shifting, the list elements 'suggestShiftDf' and 'printShiftDf' both are character strings which confirm that no shift is suggested.

Details

If at least one questionnaire is registered as having been filled out repeatedly at a specific prompt it might be 'reasonable' to shift such questionnaires to a neighboring prompt index. The word 'reasonable' refers to the rule of how questionnaires get assigned to a specific prompt: For each participant the minimum time difference between the actual start time of a questionnaire and all of the participant's scheduled times (prompts) determines which prompt gets assigned to the actual start time. Say between 2 neighboring prompts 4 hours pass, then a questionnaire that was started 3 minutes after the prompt gets assigned to the same prompt as a questionnaire that was started 1 hour and 59 minutes after the prompt. Had it been started say exactly 2 hours after the prompt it would have been assigned to the subsequent prompt. It might be reasonable to assign such a questionnaire to this subsequent (neighboring) prompt.

See Also

Exemplary code (fully executable) in the documentation of esmprep (function 20 of 29).

Examples

# NOT RUN {
# 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 suggestShift. Start -------------
# Use example list delivered with the package
RELEVANTINFO_ES <- RELEVANTINFO_ES
# Use example list delivered with the package
RELEVANTVN_ES <- RELEVANTVN_ESext
# esAssigned is a list of datasets, delivered with the package. It is
# the result of the assignment of the ESM questionnaires to ALL 8
# participants in the reference dataset.
noEndDf <- missingEndDateTime(esAssigned[["ES"]], RELEVANTVN_ES)
identDf <- esIdentical(noEndDf, RELEVANTVN_ES)
# Prerequisites in order to execute suggestShift. End ---------------
# -------------------------------------------------------
# Run function 20 of 29; see esmprep functions' hierarchy.
# -------------------------------------------------------
# identDf is the result of function 'esIdentical'.
# 100 represents the number of minutes that at least must have passed
# between the scheduled start of an ESM questionnaire at its actual start
# in order for the questionnaire to be eligible for shifting (see function
# makeShift).
sugShift <- suggestShift(identDf, 100, RELEVANTINFO_ES, RELEVANTVN_ES)
# Display output element 'suggestShiftDf':
sugShift$suggestShiftDf
# Display output element 'printShiftDf':
sugShift$printShiftDf
# 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
# }