# The visual workflow: SurveyBuilder, SurveyStudio, and the dashboard

`surveyframe` has three graphical entry points, kept separate on purpose, each mapping onto a part of the research-design workflow.

- `launch_builder()` opens SurveyBuilder, a standalone questionnaire builder. It runs in the browser, saves `.sframe` files, and authors the analysis plan and the model. It does not compute statistics.
- `launch_studio()` opens SurveyStudio, the workflow hub. With R behind it, it opens a designed instrument, previews it exactly as deployed, uploads responses, runs quality and reliability checks, runs the analysis plan, and exports the report, the deployable survey, and the Sheets collector. Survey design itself stays in the SurveyBuilder.
- `launch_dashboard()` opens a read-only response explorer for an instrument and response data that already exist.

## 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`, are not part of 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, adds structural paths, and writes lavaan or seminr syntax along with the model JSON into the `.sframe` file. 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 rather than replacing its history. 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.

## Demo launchers

This vignette leaves the demo launchers unevaluated, because CRAN examples and vignettes should not open browsers.

    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 Upload Responses screen, and `screen = "analysis"` opens the Analysis Plan screen.

## 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.