The visual workflow: SurveyBuilder, SurveyStudio, and the dashboard

Input-types demo

The input-types demo covers the main controls available in SurveyBuilder and SurveyStudio. The two decision item types, pairwise_comparison and criteria_weight, sit outside this demo. They get their own worked example in the MCDM vignette, because they only make sense alongside a declared decision method and a set of alternatives.

demo      <- sframe_input_types_demo_data()
instr     <- demo$instrument
responses <- demo$responses

table(vapply(instr$items, function(x) x$type, character(1)))
#> 
#>            date          likert          matrix multiple_choice         numeric 
#>               1               5               1               1               1 
#>         ranking          rating   section_break   single_choice          slider 
#>               1               1               3               4               1 
#>            text      text_block        textarea 
#>               2               1               1
dim(responses)
#> [1] 120  22

SurveyBuilder: the Analyse mode

SurveyBuilder runs entirely in the browser, so it is an authoring tool. Its Analyse mode has three tabs, Plan, Run, and Report, with a three-panel layout underneath: a list of variables and constructs on the left, the analysis plans in the middle, and an output preview with the model builder on the right.

The Plan tab is where the research design is written. The “+ Add plan” button opens a form that records the research question, the family and method, the significance level, the variables that fill each role, and the decision rule. The form offers only the role set a method needs and reads the measurement level of each variable, so a saved plan is coherent.

The Run and Report tabs relabel the same plan list as a “run queue” and a “report outline”. They do not compute anything. SurveyBuilder stores each plan with an empty result, because the browser cannot run R. The statistics are produced later, either in an R session with run_analysis_plan() or in SurveyStudio. The output preview on the right shows counts, such as the number of plans, the number of data-dependent run items, and the number of saved models.

The model builder, also on the right, creates constructs from the scales and adds structural paths. The .sframe stores that model specification, and surveyframe can generate lavaan or seminr syntax from it. The Google Sheet panel does not collect data on its own. It explains that, after saving the .sframe file, you run export_google_sheet(instr, sheet_url = "...") in R to generate the Apps Script collector.

SurveyStudio: the screens

SurveyStudio is a Shiny application, so it can run R. Its left navigation lists nine screens in this order: Open Instrument, Amendments, Preview Survey, Upload Responses, Quality Dashboard, Reliability, Analysis Plan, Dashboard, and Export. Survey design is done in the SurveyBuilder, and the studio opens the resulting .sframe.

The Amendments screen discloses a change to the open instrument: upload a revised .sframe, give a reason and an explanation, and amend_sframe() appends the change to the instrument’s amendment log, where every earlier entry stays as it was written. Exporting the amended instrument keeps that log inside the .sframe file, readable later with amendment_log().

The Preview Survey screen renders the exact deployable survey, identical to the exported HTML.

The Analysis Plan screen does two jobs. It edits the plan, with the same research question, method, significance level, and role fields as the builder. It also runs the plan. When response data have been uploaded, the screen calls run_analysis_plan() and shows a “Run results” table with the plan ID, the method, and the APA result for each research question. Without responses, it asks you to upload data before running.

The Export screen produces the written report through render_report(). Its options include the codebook, quality, missing data, descriptives, reliability, the saved analysis-plan results, and the model appendices. The per-question report produced by render_results() in an R session is a separate route to a written report and is covered in the main vignette. The same screen’s “Analysis notebook” card writes a Quarto notebook alongside the instrument and its responses, via sframe_analysis_qmd(), so the same analysis can be run and edited outside SurveyStudio.

Recommended workflow

1. Use launch_builder() to create or revise the questionnaire, the plan, and the model.
2. Save the instrument as a .sframe file.
3. Use read_sframe() to load the saved instrument in R.
4. Use read_responses() to import collected data.
5. Use launch_studio() to inspect the instrument and responses together, to run the plan on the Analysis Plan screen, and to export the report.
6. Use launch_dashboard() for read-only response exploration.

RStudio Addins

In RStudio, the same tools open from the Addins menu in the toolbar. The 4 commands are listed under surveyframe: and are searchable by that prefix in the command palette. Each one needs the rstudioapi package.

The commands follow the workflow above:

Design an instrument -> save .sframe -> Analyse an existing instrument ->
upload responses -> run the plan -> export the report

The starter instrument holds a 5-point choice set, 3 items, one scale, and a reliability plan, and it validates as inserted. It ends with a commented write_sframe() line for saving it. When a command has to stop, because RStudio is closed, the console has focus, or a file fails to load, it prints one message saying why and what to do next.

Demo launchers

This vignette leaves the demo launchers unevaluated, because CRAN examples and vignettes leave browsers closed.

launch_builder_demo()
launch_studio_demo()
launch_dashboard_demo()

launch_builder_demo() injects the demo state into a temporary copy of survey_builder.html and opens it, so the demo questions, scales, and analysis plan are visible at once. launch_studio_demo() opens the studio with an instrument and response data already loaded. launch_dashboard_demo() opens the dashboard with the same demo data.

Standalone builder

builder_file <- launch_builder(open = FALSE)
builder_file

Use SurveyBuilder for questionnaire, plan, and model authoring. Response exploration and plan execution belong in SurveyStudio or the dashboard.

Studio workflow hub

launch_studio(
  instrument     = instr,
  responses      = responses,
  screen         = "analysis",
  launch.browser = FALSE
)

SurveyStudio reads the objects passed by launch_studio(). With response data present, screen = "auto" opens the Dashboard. With an instrument alone it opens Preview Survey, and with neither it opens Open Instrument. screen = "analysis" opens the Analysis Plan screen explicitly.

Dashboard

launch_dashboard(
  instrument     = instr,
  responses      = responses,
  launch.browser = FALSE
)

Use the dashboard after data collection for read-only exploration.

Known limitations

SurveyBuilder stores short autosave recovery data in browser localStorage. Browsers can clear that storage when site data are cleared, when private browsing is used, or when a storage quota is reached. Save a .sframe file before closing the browser when the work matters.

SurveyBuilder first tries the browser crypto.subtle API for SHA-256 hashing and then uses the bundled JavaScript fallback. This supports browsers that restrict crypto.subtle on local file:// pages.

Moving files between tools

The .sframe file is the shared object between the visual tools and the R workflow. It carries the questions, the analysis plan, and the model in one file.

1. Build or edit the questionnaire, plan, and model in SurveyBuilder.
2. Save the .sframe file.
3. Load it in R with read_sframe().
4. Import responses with read_responses().
5. Use SurveyStudio or the dashboard for response checking and reporting.