Question structure as YAML

[StefanMunnes]

Description

I already had the idea before, but it has now become more concrete thanks to the work on the label output. I would find it helpful if there could be a questions.json output that actually contains the same values as the sd_question() function:

questions.json

{
  "id": "fruit",
  "type": "mc_buttons",
  "label": "Which fruit do you prefer most from this list?",
  "option": {
    "Apple": "apple",
    "Banana": "banana",
    "Pear": "pear",
    "Strawberry": "strawberry",
    "Grape": "grape",
    "Mango": "mango",
    "Watermelon": "watermelon"
  }
}

This would be useful if you want to use the option labels to create factor variables in the data wrangling, or using the question labels in a report. If you implement the pull request, all the information are already extracted from the HTML and available and just need to be exported.

One could also think about using this JSON file as an input for the survey.qmd file. This could be helpful if you have a much larger set of standardized questions and just want to choose which ones you want to ask in the new survey. Or often copy the same survey. You just need to specify the question ID in the survey.qmd file with sq_question("fruit"), and it will take all the information from a questions.json file in the directory. Or, if you need to, you can define the path to an external questions.json file in the sd_server() function.

Just my thoughts. If you also find this useful, I can try to do a pull request on this.

[jhelvy]

This is actually closer to the original idea I had a while back (which I wrote a blog post about). The idea was to define all of the questions in a single static file (the original idea was yaml, but json works just the same).

I still like this idea, and it could definitely be helpful for large surveys and / or working with large corpuses of standard questions.

I guess there are two ways to use it though:

1. Pre-defining questions that we just drop in with sd_question("id").
2. Exporting all questions in a survey.qmd file to json (e.g. for use in another survey).

I would want to support both if possible. In terms of implementing it though, we should first agree upon the way we want the user to interface with each approach.

For part 1, assuming a user has something like a questions.json file storing the question data, I think it should be specified inside the sd_server() function, like sd_server(json = "questions.json"). This can then be leveraged inside the run_config() function to define the questions. This will not be trivial to implement though. The current logic flow inside run_config() is to render the survey.qmd file first, then parse it to obtain the rendered html content (which ultimately gets displayed later in the sd_server() function). To implement the json, we would need to somehow replace the placeholder sd_question(id) values inside the survey.qmd file with the questions from the json file. One idea to implement this is to introduce an additional qmd file, maybe called questions.qmd. The user would not need to create this file - it could be generated automatically if a value was provided to the json argument in sd_server(). This file would only contain one big code chunk (no page breaks) that reads the questions.json file and loops across each question creating calls to sd_question() populated with the data in the json file. This file could then rendered into a questions.html file that could then be parsed to grab the rendered html for each question. Then when parsing the rendered survey.html (rendered from the survey.qmd file), all we would need to do is for each question_id check if there was an equivalent question_id in the parsed questions.html file; if so, replace the html with that from the questions.html file. Does this make sense? We would also need to update the sd_question() function such that users could only provide an id argument and it won't error. Alternatively, we could create a different function, e.g. sd_question_json() or something that only takes an id argument and will just drop in a placeholder that will be swapped out with the question html from the json data.

For part 2, I assume this might just be a separate function to run in the console, something like sd_export_questions(path). It would run the same run_config() function to get back the list of pages and then extract only the question data, convert it to json, and write it to path, with maybe a default value of path = "questions.json".

[StefanMunnes]

Okay, that sounds great. I'm sorry I didn't find the blog post before.

I also think it would make sense to have both options. I've used the time again to think about how it would make sense conceptually in general. I think that we should separate the output of the questions and the possible input into two files. While the output only ever contains the questions that are actually being used, an external import file would have the advantage of also containing additional questions and versioning, a kind of simple question database. In other words, a clear separation between used and generally available questions.

As the output of questions to an external file is certainly easier to implement, I would focus on this first. For me, this would also be more useful, especially for further data labeling.

1. my suggestion would be to have an output_question = TRUE option in sd_server(), like it used to be with use_html = TRUE. I'm not a fan of additional functions, but it would also be logical to implement a function in the global settings section, where the database is also defined: sd_external_question(output = 'path'). However, I would not necessarily specify a path and it should be enough if the question file is in the same survey folder. Or this is the default and if one want, a path can also be specifiet.
   This would actually be relatively easy to implement, as all the relevant information about the questions can be extracted from the rendered html. Just like I did in the pull request. It would then only have to be written from the output list into the file.

2. regarding the import of external questions, I am currently at the end of my knowledge. You are the expert and your suggestion sounds more complicated than I had hoped, but will certainly not be easier to implement. I'll think about it again.

PS: I hadn't even thought about it, but I also think YAML is better than JSON.

[jhelvy]

I was also thinking that the questions.json file could have any number of questions in it, so long as each has a unique id. You wouldn't have to use them all - the survey would only use the ones that are included in the survey.qmd file. So you could have tons of questions in the json file, but only use a handful.

As for the export option, I wouldn't want this to be part of the sd_server() arguments. Those arguments should only be things that change the behavior of how the survey app runs (e.g. setting some questions as required). Exporting questions to a json file is a separate task that only a survey designer would want to do, and I believe it should be a separate function to be used in the R console and not within the survey.qmd or app.R files. So I still think this should be something like sd_export_questions(name, path), where the default values would be name = "questions.json" and path = NULL, in which case it would save the json file as "questions.json" in the root project folder. I would want these optional arguments because a user may want to save them somewhere else. This is more like write_csv() - a function for storing data somewhere (in this case, we're storing question metadata).

As for the data structure, I do think json is actually the better approach as it is sort of the default data structure for web applications. It's easy to convert back and forth to lists or data frames in R using the jsonlite package.

For importing questions, I would introduce a new argument to sd_server(), something like question_json = "questions.json", with a default value of NULL. If NULL, then it ignores the json. If it's a path to a valid json file, then the question data in the json file will be used for any question in the survey.qmd file that has an equivalent id with a question in the questions.json file.

[StefanMunnes]

I would like to discuss the two points again.

1. from what I have read so far, YAML has a few advantages over JSON:

• it is easier to write and read (no curly braces, fewer quotes)
• offers a wider support of different values - the git diff control is clearer
• comments can be inserted

In addition, YAML can be created and loaded via the library(yaml) just as easily as JSON with library(jsonlite).

2. I still think it makes sense to have two separate files, one for the input of the questions, one for the output. In the simplest case, the questions are created via the survey.qmd file anyway. This output file would then, if desired, only be there to use the questions actually contained and their labels for further data processing or the creation of a codebook.
   Importing questions from an external file, on the other hand, is a different process and in some cases only some of the questions are imported, and I don't want all the additional questions I may have asked to be saved in this file. For example, I have a file with questions about attitudes to electric cars, but I don't want to overwrite it with additional questions about bicycles from this one survey. I think this logical separation should also be reflected in the import and export.
   In addition, it would of course also be a major intervention, also coding wise, if the import file had to be overwritten again for the output.

[jhelvy]

I don't have a strong preference either way (json or yaml). They're functionally equivalent, so if yaml is easier to read / edit, then we could use that. To prove the point, here's an example of each:

id: "artist"
type: "mc"
label: "Which artist do you prefer most from this list?"
option:
  Michael Jackson: "michael_jackson"
  Taylor Swift: "taylor_swift"

{
  "id": "artist",
  "type": "mc",
  "label": "Which artist do you prefer most from this list?",
  "option": {
    "Michael Jackson": "michael_jackson",
    "Taylor Swift": "taylor_swift"
  }
}

Save those as questions.yml and questions.json. Then the following code will generate the exact same named list:

q_yaml <- yaml::read_yaml('questions.yml')
q_json <- jsonlite::read_json('questions.json')
identical(q_yaml, q_json)

[jhelvy]

About how we actually implement this, one thought I had was to create a questions folder in the project root directory. Inside that folder you could have multiple different yaml files that store a bunch of different questions. This could be helpful for keeping your questions organized by theme, e.g. demographics.yml, electric_cars.yml, etc. surveydown could simply be set up such that any question id it finds in any of these files will be used in the survey where ever a matching sd_question(id) is found. That's not too hard to set up and could just be automatically implemented - no need to use any arguments in sd_server(), etc.

As for exporting questions, this could also be automatically done. Whenever you run the app, it will export the survey questions to a yml file after running run_config(). This file could be just a special name inside the questions folder, maybe _exported_questions.yml. That will make it more distinct inside the folder, and it will be a special name that is excluded from the read process, preventing questions inside this file from being used inside the survey. This will keep the different yaml files from becoming overwritten / corrupted.

For each of these steps, we can set it up such that the function is "smart", meaning it will check the files for updated time stamps. If it finds that a file has been changed, it will re-import / re-export accordingly, otherwise it won't. That will prevent this from happening on every single instance of the survey app when it's deployed (you don't want it trying to read/write on shinyapps.io - that will cause an error).

I don't have time immediately to work on this, but I want to get the concepts laid out and agreed upon so that when there is time we have a clear plan.

[StefanMunnes]

Interesting idea. However, I'm not quite sure if this would really often happen, that there would be multiple files with questions to import and if it wouldn't make it unnecessarily complicated.

The automatic import/export sounds like a great idea to me, though. Less effort for the user.

Do you think a "smart" function is important? So is the extra code complexity and testing time worth reading in the files? The same applies to writing the output. How much do we gain by making the function "smart"? Perhaps the import/export can be linked to the automatic rendering of the HTML, so that the files are only loaded or saved if the HTML is also re-rendered because there have been changes in the survey.qmd file?

I'm not sure how the import can be organized, but would like to suggest a PR for the output? I think this is more important at the moment and should be relatively easy to implement. Just let me know what you think and how you image to solve this when you have time.

[jhelvy]

By "smart" I just mean that any import / export operations would only happen if a change is detected in a relevant file. This would all happen internally, the user wouldn't need to do anything differently. I just mean that we don't want the app to be trying to read / write yaml files when the app is hosted somewhere like shinyapps.io.

Two possible designs:

1. Create a questions folder to store all the questions. It gives you the flexibility to call the yml file(s) whatever you want - so long as they're in a folder called questions then they can be accessible to the survey. If we go with that design, then I would also put the exported questions in that folder, maybe in a file called _exported.yml or exported.yml.
2. Import all questions from a single yml file, maybe just called questions.yml. That could be a fixed name that the program searches for in the project root directory. For exporting questions, I would write them to a file called questions_exported.yml to make it distinct from the ones being used in the survey.

With either design, you should be able to send a PR with the exported questions relatively easily. It's just an operation that occurs after run_config() since you'll have all the question data. You can set it up with some logic so it only writes when needed. If no exported file is found, write it. If it is found, check the times of when it was updated, compare that against the survey.html file. If the survey.html is newer, export the questions again.

[jhelvy]

Questions are now exported into a _survey/questions.yml file when rendering, and otherwise loaded when the app launches unless changes are detected in the survey.qmd and app.R files.

I'll leave this discussion open though because there is still the possibility of loading questions via a yml file.