surveyPrep: Check Questions before Running a Survey in a Shiny App

In abbey-thomas/speechcollectr: R Tools for Collecting Speech Production & Perception Data

Check Questions before Running a Survey in a Shiny App

Description

Check Questions before Running a Survey in a Shiny App

Usage

surveyPrep(questionFile = NULL, notListedLab = NULL)

Arguments

questionFile	character. The name of the CSV file containing the id, label, type, priority, and options for each question. See Details below for more information.
notListedLab	character. For non-textInput questions, the name of the choice that will allow your participants to enter their own value for all questions that include this string in the 'options' column.

Details

The input for this function must be a CSV file containing all and only the columns described below. Each row in the CSV file corresponds to a survey question that will be displayed to participants with the ⁠speechcollectr::survey*()⁠ functions. If any of the columns described below are missing, or if your initial question file contains extra columns, this function will return ONLY an error message in the console. If this occurs, please go back, correct column names (they are case sensitive), save your question file, and then rerun surveyPrep(). If this function does not return a data frame in which all cells contain 'No errors', the ⁠speechcollectr::survey*()⁠ functions will not produce a Shiny survey form as expected.

• "id:"Gives a unique input ID for each question. Values MUST be unique for each row and follow the same rules as other Shiny input IDs (no spaces).

• "label:"Contains the labels (i.e., the questions) that will be displayed to participants, as labels in the Shiny ⁠*input()⁠ functions.

• "priority:"Specifies whether an item is required or not. There are two accepted options (required and optional), denoted by the following values (values separated by pipe (|) are treated as equivalent): 'required'|'req'|'r' and 'optional'|'opt'|'o'.

• "type:" Tells Shiny which ⁠*Input()⁠ function to use for each question. Acceptable types are any of the following (equivalent options separated by '|'): 'textInput'|'text'|'t', 'selectInput'|'select'|'s', 'numericInput'|'numeric'|'n', 'checkboxGroupInput'|'checkbox'|'c', and 'radioButtons'|'radio'|'r'.

• "options:" Contains the list of options for all non-textInput questions. All options in the list should be separated by commas, and no enclosing parantheses are needed. If you wish to include an option for participants to enter a value not listed among these options, place the value for the notListedLab as the last option in the row. This will tell R to insert a textInput UI when the participant selects the not listed option. The value they enter will be accessible using the input ID associated with this row in the input CSV file. If you do not wish users to be able to specify a value when the select not listed, simply leave the notListedLab argument as NULL. If a question is of type numericInput, this column must contain two values, the minimum and the maximum numeric options, separated by a comma. If a question is of type textInput, the value in this column should be ” (an empty vector) or NA. If all questions are of type textInput, this column may be omitted.

• "trigger_id:" Optional. For questions that appear conditionally based on an answer to a previous question. Should contain the id (from the id column) of the question used to trigger the appearance of the question in this row. If the question's appearance is not conditional on any other answers, this column's value should be set to NA.

• "trigger_value:" Optional. For questions that appear conditionally based on an answer to a previous question. Should contain the ANSWER to the question identified in trigger_id that will trigger the appearance of the question in this row. If the question's appearance is not conditional on any answers, this column's value should be set to NA. This cannot be NA if trigger_id has a value other than NA for this row.

Value

A data frame that includes the same columns and rows as the questionFile, and gives feedback on each cell of the original data frame in the corresponding cells of the output. Optionally, if running in an interactive session, this function will also return a demo Shiny App, if the user replies 'y' (yes) when asked if they would like to preview the questions.

Note

The data frame produced by this function is only for informational purposes. Do NOT use this function in a shiny app to present to participants. To present a survey to participants use surveyUI() and surveyServer(). If any errors are found in your input question file, please return open the input question file in a text editor, correct any mistakes, and rerun this function until all cells in the output say 'No errors'.

Examples

data("demographics")
write.csv(demographics, "demographics.csv", row.names = FALSE)
feedback <- surveyPrep(questionFile = "demographics.csv",
                       notListedLab = "Not listed:")

abbey-thomas/speechcollectr documentation built on Nov. 19, 2024, 7:09 p.m.