Package {surveyframe}

Title:	Survey Instrument Workflows
Version:	0.3.0
Description:	Supports survey research workflows built around a typed instrument object (the sframe). Features include visual instrument design via a browser-based builder or 'Shiny' studio, export to a self-contained static HTML survey, an embeddable 'Shiny' module, SHA-256 integrity-checked serialisation to the '.sframe' format, multi-page survey rendering, branching logic, response quality checking, scale scoring, psychometric diagnostics, analysis-plan execution, model syntax planning, an interactive response dashboard, codebook generation, and reproducible HTML reporting.
License:	MIT + file LICENSE
URL:	https://github.com/MohammedAliSharafuddin/surveyframe
BugReports:	https://github.com/MohammedAliSharafuddin/surveyframe/issues
Encoding:	UTF-8
Language:	en-GB
Depends:	R (≥ 4.1.0)
Imports:	jsonlite (≥ 1.8.0), rlang (≥ 1.1.0), openssl (≥ 2.1.0)
Suggests:	googlesheets4 (≥ 1.1.0), shiny (≥ 1.7.0), psych (≥ 2.3.0), MASS, nnet, digest (≥ 0.6.0), testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
RoxygenNote:	8.0.0
NeedsCompilation:	no
Packaged:	2026-05-20 18:17:37 UTC; maxx
Author:	Mohammed Ali Sharafuddin [aut, cre]
Maintainer:	Mohammed Ali Sharafuddin <mohammedali.page@gmail.com>
Repository:	CRAN
Date/Publication:	2026-05-27 20:10:09 UTC

surveyframe: Survey Instrument Workflows for R

Description

surveyframe defines a survey instrument as a first-class R object and supports a workflow from instrument design through data collection, quality checking, scoring, psychometric diagnostics, and reproducible reporting. Version 0.3 adds static HTML survey export, an embeddable Shiny survey module, an interactive response dashboard, a role-based analysis planner, common survey statistics, and model syntax planning for EFA, CFA, CB-SEM, and PLS-SEM.

Core workflow

1. Design an instrument with launch_builder() or sf_instrument() and its component constructors: sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check().

2. Validate and save with validate_sframe() and write_sframe().

3. Deploy a Shiny survey with render_survey().

4. Load responses with read_responses() or read_sheet_responses().

5. Check quality with quality_report().

6. Score and analyse with score_scales(), descriptives_report(), missing_data_report(), reliability_report(), item_report(), efa_report(), cfa_syntax(), and run_analysis_plan().

7. Report with codebook_report(), render_report(), and render_results().

The instrument object

Every function in the package operates on an sframe object. The object is the single source of truth for item definitions, scale structure, reverse-coding keys, branching rules, check specifications, analysis plans, and optional model specifications.

File format

Instruments are stored as UTF-8 JSON files with the .sframe extension. Each file includes a SHA-256 integrity hash for reproducibility auditing.

Author(s)

Maintainer: Mohammed Ali Sharafuddin mohammedali.page@gmail.com (ORCID)

Authors:

• Mohammed Ali Sharafuddin mohammedali.page@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/MohammedAliSharafuddin/surveyframe

• Report bugs at https://github.com/MohammedAliSharafuddin/surveyframe/issues

Add a model specification to an instrument

Description

Add a model specification to an instrument

Usage

add_model(instrument, model, validate = TRUE, replace = TRUE)

Arguments

Value

The updated sframe object.

Assumption-check report

Description

Performs common assumption checks for survey analyses using base R where possible: Shapiro-Wilk tests, skewness/kurtosis screening, Levene and Brown-Forsythe tests, regression residual checks, VIF, Cook's distance, expected-count checks, and sparse-cell warnings.

Usage

assumption_report(
  data,
  variables = NULL,
  group = NULL,
  outcome = NULL,
  predictors = NULL,
  table_vars = NULL
)

Arguments

Value

An object of class sframe_assumption_report.

Generate lavaan CFA syntax

Description

Generate lavaan CFA syntax

Usage

cfa_lavaan_syntax(
  instrument = NULL,
  model = NULL,
  scales = NULL,
  ordered = FALSE,
  std_lv = TRUE,
  residual_covariances = NULL,
  latent_covariances = TRUE
)

Arguments

Value

A lavaan syntax string.

Generate lavaan CFA syntax from an instrument object

Description

Produces a character string of lavaan model syntax derived from the scale structure in the instrument. The syntax can be passed directly to lavaan::cfa(). Reverse-coded items are noted in a comment but are not transformed in the syntax; recoding should be applied to the data before fitting the model.

Usage

cfa_syntax(instrument, scales = NULL, std_lv = TRUE)

Arguments

Value

A character string of lavaan CFA model syntax.

See Also

efa_report(), reliability_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i3    <- sf_item("sat_3", "Item 3 (reverse)", type = "likert",
                 choice_set = "ag5", scale_id = "sat", reverse = TRUE)
scale <- sf_scale("sat", "Satisfaction",
                  items = c("sat_1", "sat_2", "sat_3"))
instr <- sf_instrument("Demo Survey", components = list(cs, i1, i2, i3, scale))

syntax <- cfa_syntax(instr)
cat(syntax)

## Not run: 
# lavaan is not installed by default; install it before fitting.
demo   <- sframe_demo_data()
scored <- score_scales(demo$responses, demo$instrument)
fit    <- lavaan::cfa(syntax, data = scored, std.lv = TRUE)
summary(fit, fit.measures = TRUE)

## End(Not run)

Generate a survey codebook from an instrument object

Description

Produces a structured codebook listing all items, their types, choice sets, scale membership, and reverse-coding status. The codebook can be rendered as HTML or Markdown.

Usage

codebook_report(instrument, format = c("html", "md"))

Arguments

Value

An object of class sframe_codebook, a list with elements instrument_meta, items_table, choices_table, and scales_table. Call print() to display a compact summary or use render_report() to include the codebook in a full report.

See Also

render_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
scale <- sf_scale("sat", "Satisfaction", items = c("sat_1", "sat_2"))
instr <- sf_instrument("Demo Survey", components = list(cs, i1, i2, scale))

cb <- codebook_report(instr)
print(cb)
nrow(cb$items_table)
nrow(cb$scales_table)

Descriptive statistics report

Description

Computes survey descriptives for numeric, Likert, and scale-score columns, including missingness, mean, standard deviation, median, IQR, range, skewness, kurtosis, standard error, and confidence intervals.

Usage

descriptives_report(
  data,
  variables = NULL,
  split_by = NULL,
  conf_level = 0.95,
  weights = NULL
)

Arguments

Value

An object of class sframe_descriptives_report.

Prepare a survey instrument for exploratory factor analysis

Description

Reports KMO sampling adequacy, Bartlett's test of sphericity, and a parallel analysis scree plot to inform factor number selection. The report prepares the researcher to estimate an EFA solution with a separate package such as psych or lavaan.

Usage

efa_report(
  data,
  instrument,
  scales = NULL,
  nfactors = NULL,
  rotation = "oblimin"
)

Arguments

Value

An object of class sframe_efa_report with elements kmo, bartlett, parallel, and suggested_nfactors.

See Also

reliability_report(), cfa_syntax()

Examples

if (requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  er <- efa_report(demo$responses, demo$instrument)
  print(er)
}

Estimate an exploratory factor solution

Description

Runs psych::fa() on selected item columns and returns loadings, communalities, uniqueness, variance summaries, and simple item retention flags. The psych package is optional and is only required when this function is called.

Usage

efa_solution(
  data,
  instrument,
  items = NULL,
  scales = NULL,
  nfactors = 1L,
  extraction = c("minres", "pa", "ml"),
  rotation = c("oblimin", "promax", "varimax"),
  min_loading = 0.3,
  cross_loading = 0.3
)

Arguments

Value

An object of class sframe_efa_solution.

Generate EFA planning syntax

Description

Generate EFA planning syntax

Usage

efa_syntax(
  items,
  nfactors = 1L,
  extraction = c("minres", "pa", "ml"),
  rotation = c("oblimin", "promax", "varimax"),
  data_name = "data"
)

Arguments

Value

A character string with R syntax.

Export a survey instrument to Google Sheets collection format

Description

Generates a Google Apps Script file that, when run in a Google Sheet, creates a response collection endpoint for a survey instrument. The builder can store the deployed Apps Script URL in survey metadata, and the same sheet can be read back with read_sheet_responses().

Usage

export_google_sheet(instrument, sheet_url, output_dir = ".")

Arguments

Value

The path to the generated .gs Apps Script file, invisibly.

See Also

read_sheet_responses(), read_responses(), write_sframe()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
script <- export_google_sheet(
  instr,
  sheet_url = "https://docs.google.com/spreadsheets/d/demo",
  output_dir = tempdir()
)
file.exists(script)

Export a self-contained static HTML survey

Description

Generates a single HTML file that presents the survey instrument in a browser without requiring a Shiny server or any internet connection. All thirteen item types, branching logic, required-field validation, and multi-page navigation are handled entirely in client-side JavaScript.

Usage

export_static_survey(
  instrument,
  output_path = NULL,
  open = interactive(),
  endpoint_url = NULL,
  overwrite = FALSE
)

Arguments

Details

When output_path is NULL, the file is written to tempdir(). Supply an explicit output_path for any production export that should be kept.

When a respondent clicks the submit button, the browser downloads a one-row CSV file named ⁠<survey_title>_response_<id>.csv⁠. If endpoint_url is supplied, the same payload is also sent as a JSON POST request to that URL (for example a Google Apps Script web app or a serverless function). The two mechanisms are independent: the download happens regardless, so responses are never lost if the POST fails.

The exported file works offline. It can be hosted on GitHub Pages, Netlify, any static file server, or e-mailed as an attachment for opening directly from disk.

Value

The output path, invisibly.

See Also

launch_studio(), launch_builder(), render_survey()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Overall I am satisfied with the service.",
                 type = "likert", choice_set = "ag5", required = TRUE)
i2    <- sf_item("comments", "Any additional comments?", type = "textarea")
instr <- sf_instrument("Customer Satisfaction Survey",
                       components = list(cs, i1, i2))

# Write to a temp file without opening the browser
out <- export_static_survey(instr,
                             output_path = file.path(tempdir(), "sat.html"),
                             open = FALSE)
file.exists(out)


# Write to a temp file and open in the default browser
export_static_survey(instr,
                     output_path = file.path(tempdir(), "sat_browser.html"),
                     overwrite = TRUE)

# Write with a Google Apps Script endpoint for server-side collection
export_static_survey(
  instr,
  output_path  = file.path(tempdir(), "sat_endpoint.html"),
  endpoint_url = "https://script.google.com/macros/s/XXXXX/exec",
  open         = FALSE,
  overwrite    = TRUE
)

Format an sframe instrument object as a string

Description

Format an sframe instrument object as a string

Usage

## S3 method for class 'sframe'
format(x, ...)

Arguments

Value

A single character string.

Generate item-level diagnostics

Description

Produces item-total correlations, floor and ceiling effect proportions, and item means and standard deviations for each item within each scale.

Usage

item_report(data, instrument, scales = NULL)

Arguments

Value

An object of class sframe_item_report, a list with one data.frame per scale.

See Also

reliability_report(), sf_scale()

Examples

demo <- sframe_demo_data()
ir <- item_report(demo$responses, demo$instrument)
print(ir)

Launch the surveyframe visual survey builder

Description

Opens the SurveyBuilder, a self-contained HTML application for visual survey design. The builder runs client-side without an R session or Shiny server. Save instruments as .sframe files from the browser and load them into R with read_sframe().

Usage

launch_builder(open = TRUE)

Arguments

Details

The builder includes a three-mode interface.

Build

An item editor with a persistent inspector panel, drag-to-reorder, undo/redo, and autosave to browser localStorage.

Preview

A full live render of the survey showing welcome, body, and thank-you pages.

Analyse

A role-based analysis planner with method-specific options, planned outputs, reporting references, and decision rules.

The builder includes a pure-JavaScript SHA-256 fallback for browsers or security policies where crypto.subtle is unavailable on ⁠file://⁠ origins. Saved .sframe files can be loaded and validated with read_sframe().

Value

The path to the bundled builder HTML file, invisibly.

See Also

launch_studio(), read_sframe(), run_analysis_plan()

Examples

# Retrieve the builder path for inspection without opening the browser
path <- launch_builder(open = FALSE)
file.exists(path)

Launch SurveyBuilder with the bundled input-types demo preloaded

Description

Opens a temporary copy of the SurveyBuilder with the bundled input-types instrument already injected into the JavaScript state. The demo questions, scales, and analysis plan are visible immediately — no manual file-load step is required.

Usage

launch_builder_demo(open = TRUE)

Arguments

Value

Invisibly returns a list with builder_path, demo_file, and responses_path.

Launch the interactive response dashboard

Description

Opens a Shiny dashboard to explore collected response data alongside the instrument definition. Use this interface after response collection for analysis and quality control. Use launch_builder() to design new questionnaires. The dashboard includes five panels:

Usage

launch_dashboard(
  instrument = NULL,
  responses = NULL,
  port = NULL,
  host = "127.0.0.1",
  launch.browser = interactive()
)

Arguments

Details

Overview

Response count, date range, and instrument metadata.

Items

Per-item frequency bar charts, histograms, and tabulated frequency counts for choice-type questions.

Scales

Scale score distributions with mean overlay, and a summary table of scale definitions.

Quality

Attention check pass rates for each check defined in the instrument.

Raw data

Scrollable response table with a CSV download button.

The dashboard is read-only. Use it for descriptive exploration after collecting responses and before running formal analysis with run_analysis_plan().

Value

Called for its side effect. Returns nothing.

See Also

run_analysis_plan(), quality_report(), score_scales()

Examples

# Open the bundled tourism-services response dashboard.
# To build a questionnaire instead, use launch_builder().
launch_dashboard()

# Open the dashboard with your own instrument and responses
instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
launch_dashboard(instr, responses)

Launch the response dashboard with the bundled input-types demo

Description

Opens the dashboard with the bundled input-types questionnaire and 120 simulated responses already loaded. The browser is opened automatically by default.

Usage

launch_dashboard_demo(port = NULL, host = "127.0.0.1", launch.browser = TRUE)

Arguments

Value

Called for its side effect.

Launch the SurveyStudio interface

Description

Opens the SurveyStudio Shiny application, a visual interface for the complete surveyframe workflow. The studio includes screens to build a survey draft, open an existing instrument, preview the survey, upload responses, review data quality, inspect reliability, plan analyses, and export outputs.

Usage

launch_studio(
  instrument = NULL,
  responses = NULL,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE,
  screen = c("auto", "build", "preview", "data", "quality", "analysis", "dashboard"),
  port = NULL,
  host = "127.0.0.1",
  launch.browser = interactive()
)

Arguments

Value

Called for its side effect.

See Also

launch_builder(), launch_dashboard(), read_sframe(), read_responses()

Examples

launch_studio()

demo <- sframe_demo_data()
launch_studio(instrument = demo$instrument, launch.browser = FALSE)

launch_studio(
  instrument    = demo$instrument,
  responses     = demo$responses,
  respondent_id = "respondent_id",
  submitted_at  = "submitted_at"
)

Launch SurveyStudio with the bundled input-types demo

Description

Opens SurveyStudio with the bundled input-types questionnaire and simulated response data already loaded. The browser is opened automatically by default.

Usage

launch_studio_demo(
  screen = "preview",
  port = NULL,
  host = "127.0.0.1",
  launch.browser = TRUE
)

Arguments

Value

Called for its side effect.

Missing-data report

Description

Reports item-wise missingness, respondent-wise missingness, missing-data patterns, listwise and pairwise deletion counts, and scale scoring missing rules. No imputation is performed.

Usage

missing_data_report(data, instrument = NULL, variables = NULL)

Arguments

Value

An object of class sframe_missing_data_report.

Serialise a model specification to JSON

Description

Serialise a model specification to JSON

Usage

model_json(model, pretty = TRUE)

Arguments

Value

A JSON string.

Create a model reporting template

Description

Create a model reporting template

Usage

model_report_template(model, include_json = TRUE)

Arguments

Value

A character string.

Flag univariate and multivariate outliers

Description

Uses transparent screening rules for numeric survey response variables. The report supports data review before modelling, not automatic deletion.

Usage

outlier_report(
  data,
  variables = NULL,
  method = c("zscore", "iqr", "mahalanobis"),
  z_cut = 3,
  iqr_multiplier = 1.5,
  p_cut = 0.975
)

Arguments

Value

An object of class sframe_outlier_report with the method, screened variables, a result table, flagged row numbers, and a reporting prompt.

Examples

demo <- sframe_demo_data()
outliers <- outlier_report(
  demo$responses,
  variables = c("dm_1", "dm_2", "sat_1"),
  method = "zscore"
)
outliers$flagged_rows

Post-hoc and pairwise comparison report

Description

Post-hoc and pairwise comparison report

Usage

posthoc_report(
  data,
  method = c("anova", "kruskal_wallis", "chi_square", "cochran_q"),
  outcome = NULL,
  group = NULL,
  table_vars = NULL,
  measures = NULL,
  correction = c("holm", "bonferroni", "BH")
)

Arguments

Value

An object of class sframe_posthoc_report.

Print an sframe instrument object

Description

Displays a compact summary of an sframe instrument object, showing the title, version, item count, scale count, and validation status.

Usage

## S3 method for class 'sframe'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

item <- sf_item("q1", "How satisfied are you?", type = "likert",
                choice_set = "agree5")
instr <- sf_instrument("My Survey", components = list(item))
print(instr)

Generate a data quality report for survey responses

Description

Evaluates collected response data against the instrument specification and produces a structured quality report. The report covers attention check performance, completion time, straight-lining within scale blocks, item-level missingness, respondent-level missingness, and duplicate respondent IDs where supplied.

Usage

quality_report(
  data,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  started_at = NULL,
  time_min = NULL,
  straightline_scales = TRUE,
  missing_threshold = 0.2
)

Arguments

Details

Timing analysis is available when the data contain a submission timestamp column and either an explicit started_at column or one of the recognised defaults: started_at, start_time, started, or .started_at.

Value

An object of class sframe_quality_report, a named list with elements: summary, attention, timing, straightline, missing, and duplicates. Use print() for a formatted summary.

See Also

sf_check(), read_responses(), score_scales()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
qr <- quality_report(
  responses,
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  started_at = "started_at",
  straightline_scales = FALSE
)
print(qr)

Read and validate survey responses

Description

Loads survey response data and checks that it conforms to the instrument specification. Column names in the response file must match item IDs defined in the instrument. Non-item columns are allowed only when declared through respondent_id, submitted_at, or meta_cols.

Usage

read_responses(
  x,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE
)

Arguments

Value

A data.frame with columns ordered as: metadata columns first, then item columns in instrument order. Unrecognised columns are dropped when strict = TRUE or appended with a warning when strict = FALSE.

See Also

quality_report(), score_scales()

Examples

responses <- read_responses(
  x = system.file("extdata", "tourism_services_responses.csv",
                  package = "surveyframe"),
  instrument = read_sframe(
    system.file("extdata", "tourism_services_demo.sframe",
                package = "surveyframe")
  ),
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
head(responses[, c("respondent_id", "visit_type", "dm_1")])

Read an instrument from a .sframe file

Description

Reads a .sframe JSON file and reconstructs an sframe instrument object. The SHA-256 integrity hash is verified on load unless validate = FALSE.

Usage

read_sframe(path, validate = TRUE)

Arguments

Value

An sframe object.

See Also

write_sframe(), validate_sframe()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
print(instr)

Read survey responses from a Google Sheet

Description

Reads response data collected by the surveyframe Google Apps Script endpoint and returns a validated data frame ready for the surveyframe analysis pipeline.

Usage

read_sheet_responses(
  sheet_id,
  instrument,
  sheet_name = "Responses",
  respondent_id = "respondent_id",
  submitted_at = "submitted_at"
)

Arguments

Value

A data.frame validated against the instrument, ready for quality_report(), score_scales(), and reliability_report().

See Also

export_google_sheet(), read_responses(), quality_report()

Examples

## Not run: 
responses <- read_sheet_responses(
  sheet_id   = "your-sheet-id",
  instrument = instr
)
qr <- quality_report(responses, instr, respondent_id = "respondent_id")

## End(Not run)

Compute reliability statistics for scored scales

Description

Produces Cronbach's alpha and McDonald's omega for each scale defined in the instrument, along with the number of items and sample size.

Usage

reliability_report(data, instrument, scales = NULL, alpha = TRUE, omega = TRUE)

Arguments

Value

An object of class sframe_reliability_report, a list with one element per scale. Each element is a list of statistics and a summary tibble.

See Also

sf_scale(), item_report()

Examples

if (requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  rr <- reliability_report(demo$responses, demo$instrument, omega = FALSE)
  print(rr)
}

Render a reproducible survey report

Description

Generates an HTML report that includes the instrument codebook, data quality summary, reliability diagnostics, and analysis-plan content. When Quarto and the bundled template are available, the report is rendered through Quarto. Otherwise, surveyframe writes an internal HTML fallback so the reporting workflow still runs on machines without Quarto.

Usage

render_report(
  instrument,
  data = NULL,
  output_file = NULL,
  output_path = NULL,
  format = c("html"),
  include_quality = TRUE,
  include_reliability = TRUE,
  include_codebook = TRUE,
  include_missing = TRUE,
  include_descriptives = TRUE,
  include_analysis = TRUE,
  include_models = TRUE
)

Arguments

Value

The output file path, invisibly.

See Also

codebook_report(), quality_report(), reliability_report()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
old <- options(surveyframe.use_quarto = FALSE)
out <- tryCatch(
  render_report(
    instr,
    data = responses,
    output_file = tempfile(fileext = ".html"),
    include_reliability = FALSE,
    include_analysis = FALSE
  ),
  finally = options(old)
)
file.exists(out)

Render analysis results to a formatted HTML report

Description

Generates a self-contained HTML report from the output of run_analysis_plan(). Each section corresponds to one research question and includes the APA-formatted statistical result, an interpretation space, and a reference list.

Usage

render_results(
  results = NULL,
  instrument,
  output_file = NULL,
  output_path = NULL,
  citation_format = c("apa", "ama", "vancouver"),
  title = NULL
)

Arguments

Value

The output file path, invisibly.

See Also

run_analysis_plan(), render_report()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
results <- run_analysis_plan(responses, instr)
out <- render_results(results, instr,
                      output_file = tempfile(fileext = ".html"))
file.exists(out)

Render a survey from an instrument object

Description

Launches a Shiny survey with a welcome page, configurable header, all item types, branching logic, required-field enforcement, progress tracking, standard and conversational (one-question-at-a-time) display modes, and a customisable thank-you page. Responses can be persisted to CSV or passed to a callback.

Usage

render_survey(
  instrument,
  mode = c("shiny"),
  title = NULL,
  theme = NULL,
  save_responses = c("none", "csv"),
  output_path = NULL,
  on_submit = NULL
)

Arguments

Value

A shiny.appobj.

See Also

launch_studio(), read_responses()

Examples

render_survey(instr)
render_survey(instr, save_responses = "csv", output_path = "responses.csv")

Run a pre-planned analysis from an instrument's analysis plan

Description

Executes every analysis block defined in the instrument's analysis_plan slot against the supplied response data. Each block corresponds to one research question defined during instrument design in the SurveyBuilder. Results include APA-formatted statistics, effect sizes, interpretation prompts, and reporting references.

Usage

run_analysis_plan(data, instrument, scored = TRUE)

Arguments

Value

An object of class sframe_analysis_results, a list with one element per analysis block. Each element contains the test result, APA string, interpretation prompt, and reporting-reference metadata. Pass to render_results() to generate a formatted report.

See Also

render_results(), read_sheet_responses()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
results <- run_analysis_plan(responses, instr)
print(results)

Sample-size and power planning helper

Description

Sample-size and power planning helper

Usage

sample_size_plan(
  type = c("proportion", "mean", "correlation", "t_test", "anova", "regression", "sem"),
  margin_error = NULL,
  sd = NULL,
  p = 0.5,
  r = NULL,
  alpha = 0.05,
  power = 0.8,
  groups = 2L,
  predictors = NULL
)

Arguments

Value

A list of planning estimates and warnings.

Score defined scales from survey responses

Description

Applies scale scoring rules from the instrument to response data. Handles reverse coding, optional weighted composite score computation, and minimum valid item thresholds. Returns a data frame with one scored column per scale.

Usage

score_scales(data, instrument, keep_items = TRUE, keep_meta = TRUE)

Arguments

Value

A data.frame with scored scale columns appended. Scale columns are named using the scale id.

See Also

sf_scale(), reliability_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i3    <- sf_item("sat_3", "Item 3 (reverse)", type = "likert",
                 choice_set = "ag5", scale_id = "sat", reverse = TRUE)
scale <- sf_scale("sat", "Satisfaction",
                  items = c("sat_1", "sat_2", "sat_3"), min_valid = 2L)
instr <- sf_instrument("Demo", components = list(cs, i1, i2, i3, scale))

responses <- data.frame(
  sat_1 = c(4, 5, 3),
  sat_2 = c(4, 4, 3),
  sat_3 = c(2, 1, 3),
  stringsAsFactors = FALSE
)

scored <- score_scales(responses, instr)
scored$sat

Generate lavaan CB-SEM syntax

Description

Generate lavaan CB-SEM syntax

Usage

sem_lavaan_syntax(model, instrument = NULL, standardised = TRUE)

Arguments

Value

A lavaan syntax string.

Generate seminr PLS-SEM syntax

Description

Generate seminr PLS-SEM syntax

Usage

seminr_syntax(model, data_name = "data", nboot = NULL, seed = 123)

Arguments

Value

An R syntax string for seminr.

Define a branching rule

Description

Creates a single-condition branching rule that shows or hides a survey item depending on the value of a preceding item. In v0.1, only single-condition rules are supported. Multi-condition AND/OR logic is planned for a later release.

Usage

sf_branch(
  item_id,
  depends_on,
  operator = c("==", "!=", "%in%", ">", ">=", "<", "<="),
  value,
  action = c("show", "hide")
)

Arguments

Value

An object of class sf_branch (a named list).

See Also

sf_instrument(), validate_sframe()

Examples

# Show an open-text follow-up only when the respondent selects "Other"
rule <- sf_branch(
  item_id    = "gender_other",
  depends_on = "gender",
  operator   = "==",
  value      = "other",
  action     = "show"
)

Define a design-time survey check

Description

Specifies an attention, instructional, or trap check item at instrument design time. The check is stored in the instrument object and evaluated against collected response data by quality_report(). This function only defines the check. Evaluation happens later in quality_report().

Usage

sf_check(
  id,
  item_id,
  type = c("attention", "instructional", "trap"),
  pass_values = NULL,
  fail_action = c("flag", "exclude"),
  label = NULL,
  notes = NULL
)

Arguments

Value

An object of class sf_check (a named list).

See Also

sf_item(), sf_instrument(), quality_report()

Examples

# An attention check: respondent must select 4
chk <- sf_check(
  id          = "attn_1",
  item_id     = "attention_check_q",
  type        = "attention",
  pass_values = 4,
  fail_action = "flag",
  label       = "Attention check 1"
)

Define a reusable choice set

Description

Creates a named set of response options that can be referenced by one or more items. Defining choices once and referencing them by id keeps the instrument consistent and reduces the risk of label mismatches across items that share the same response format.

Usage

sf_choices(id, values, labels, allow_other = FALSE, randomise = FALSE)

Arguments

Value

An object of class sf_choices (a named list).

See Also

sf_item(), sf_instrument()

Examples

# A five-point agreement scale
agree5 <- sf_choices(
  id     = "agree5",
  values = 1:5,
  labels = c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree")
)

# A yes/no set
yn <- sf_choices(
  id     = "yn",
  values = c("yes", "no"),
  labels = c("Yes", "No")
)

Define a latent or composite construct

Description

Define a latent or composite construct

Usage

sf_construct(
  id,
  label = NULL,
  items = character(0),
  mode = c("reflective", "composite", "formative", "single_item"),
  weights = NULL
)

Arguments

Value

An object of class sf_construct.

Define a covariance between constructs

Description

Define a covariance between constructs

Usage

sf_covariance(from, to, label = NULL)

Arguments

Value

An object of class sf_covariance.

Define an indirect effect path

Description

Define an indirect effect path

Usage

sf_indirect(from, through, to, label = NULL)

Arguments

Value

An object of class sf_indirect.

Create a survey instrument object

Description

Assembles a survey instrument from its component objects. This is the top-level constructor for the sframe class. All other constructors (sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check()) produce components that are passed into this function via components.

Usage

sf_instrument(
  title,
  version = "0.1.0",
  description = NULL,
  authors = NULL,
  languages = "en",
  components = list(),
  render = NULL,
  analysis_plan = list(),
  models = list()
)

Arguments

Value

An object of class sframe with slots meta, items, choices, scales, branching, checks, analysis_plan, models, and render.

See Also

sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check(), validate_sframe(), write_sframe()

Examples

choices <- sf_choices("agree5", 1:5,
  c("Strongly disagree", "Disagree", "Neutral", "Agree", "Strongly agree"))

item1 <- sf_item("sat_1", "The service met my expectations.",
                 type = "likert", choice_set = "agree5",
                 scale_id = "sat", required = TRUE)
item2 <- sf_item("sat_2", "I would recommend this service.",
                 type = "likert", choice_set = "agree5",
                 scale_id = "sat", required = TRUE)

scale <- sf_scale("sat", "Satisfaction", items = c("sat_1", "sat_2"))

instr <- sf_instrument(
  title      = "Service Quality Survey",
  version    = "1.0.0",
  components = list(choices, item1, item2, scale)
)
print(instr)

Define a survey item

Description

Creates a single survey item object for inclusion in an sframe instrument. Items are the atomic units of a survey instrument. Every item must have a unique id within the instrument it is added to.

Usage

sf_item(
  id,
  label,
  type = c("likert", "single_choice", "multiple_choice", "numeric", "text", "textarea",
    "date", "matrix", "slider", "ranking", "rating", "section_break", "text_block"),
  required = FALSE,
  choice_set = NULL,
  scale_id = NULL,
  reverse = FALSE,
  help = NULL,
  placeholder = NULL,
  matrix_items = NULL,
  slider_min = NULL,
  slider_max = NULL,
  slider_step = NULL,
  rating_max = NULL,
  rating_icon = NULL,
  section_intro = NULL,
  page = NULL
)

Arguments

Value

An object of class sf_item (a named list).

See Also

sf_instrument(), sf_choices(), sf_scale()

Examples

item <- sf_item(
  id = "sat_overall", label = "Overall, how satisfied are you?",
  type = "likert", required = TRUE, choice_set = "agree5",
  scale_id = "satisfaction"
)

sec <- sf_item("sec_1", "Demographic Information", type = "section_break",
               section_intro = "Please answer the following questions.")

Create a surveyframe model specification

Description

Create a surveyframe model specification

Usage

sf_model(
  id,
  label = NULL,
  type = c("efa", "cfa", "cb_sem", "pls_sem"),
  engine = NULL,
  constructs = list(),
  paths = list(),
  covariances = list(),
  indirect = list(),
  options = list()
)

Arguments

Value

An object of class sf_model.

Define a structural path between constructs

Description

Define a structural path between constructs

Usage

sf_path(from, to, label = NULL)

Arguments

Value

An object of class sf_path.

Define a scored scale

Description

Creates a scale definition that groups items and specifies how composite scores are computed. The scale carries scoring rules used by score_scales() and measurement structure used by reliability_report(), item_report(), and cfa_syntax().

Usage

sf_scale(
  id,
  label,
  items,
  method = c("mean", "sum"),
  min_valid = NULL,
  reverse_items = NULL,
  weights = NULL
)

Arguments

Value

An object of class sf_scale (a named list).

See Also

sf_item(), score_scales(), reliability_report()

Examples

sat_scale <- sf_scale(
  id            = "satisfaction",
  label         = "Customer Satisfaction",
  items         = c("sat_overall", "sat_speed", "sat_quality"),
  method        = "mean",
  min_valid     = 2,
  reverse_items = NULL
)

Abort with a branching error

Description

Abort with a branching error

Usage

sframe_abort_branching(message, item_id = NULL, ...)

Arguments

Abort with an import error

Description

Abort with an import error

Usage

sframe_abort_import(message, path = NULL, ...)

Arguments

Abort with a validation error

Description

Abort with a validation error

Usage

sframe_abort_validation(message, instrument_title = NULL, ...)

Arguments

Create an empty SurveyStudio builder state

Description

Create an empty SurveyStudio builder state

Usage

sframe_builder_empty_state()

Value

A list containing empty metadata, choice, item, scale, branching, and check collections suitable for SurveyStudio.

Convert an instrument into a SurveyStudio builder state

Description

Convert an instrument into a SurveyStudio builder state

Usage

sframe_builder_state_from_instrument(instrument = NULL)

Arguments

Value

A builder state list. Component classes are restored so the state can be edited or validated by SurveyStudio.

Validate a SurveyStudio draft state

Description

Validate a SurveyStudio draft state

Usage

sframe_builder_validate_draft(
  meta,
  choices = list(),
  items = list(),
  scales = list(),
  branching = list(),
  checks = list(),
  analysis_plan = list(),
  models = list()
)

Arguments

Value

A list with valid, problems, and instrument.

Load bundled surveyframe demo data

Description

Loads the bundled tourism-services .sframe instrument and simulated response dataset used in package examples and statistical workflow demos.

Usage

sframe_demo_data()

Value

A list with instrument, responses, instrument_path, and responses_path.

Load bundled input-types demo data

Description

Loads the bundled .sframe instrument and simulated response dataset that cover all main survey input types supported by surveyframe.

Usage

sframe_input_types_demo_data()

Value

A list with instrument, responses, instrument_path, and responses_path.

Warn about missing data

Description

Warn about missing data

Usage

sframe_warn_missing(message, item_id = NULL, rate = NULL, ...)

Arguments

Warn about a data quality issue

Description

Warn about a data quality issue

Usage

sframe_warn_quality(message, respondent_ids = NULL, ...)

Arguments

Warn about a scoring issue

Description

Warn about a scoring issue

Usage

sframe_warn_scoring(message, scale_id = NULL, ...)

Arguments

Summarise an sframe instrument object

Description

Prints a structured summary of an sframe object including metadata, item type counts, scale definitions, branching rules, and check specifications.

Usage

## S3 method for class 'sframe'
summary(object, ...)

Arguments

Value

object, invisibly.

Examples

item <- sf_item("q1", "How satisfied are you?", type = "likert",
                choice_set = "agree5")
instr <- sf_instrument("My Survey", components = list(item))
summary(instr)

Shiny module server for an embedded survey

Description

Renders the survey instrument and collects the respondent's answers. Returns a reactive that holds NULL until the form is submitted, then returns the response as a named list (one element per visible item).

Usage

survey_module_server(id, instrument, on_submit = NULL)

Arguments

Value

A reactive that returns NULL before submission and the response list after.

See Also

survey_module_ui()

Examples

# See survey_module_ui() for a complete example.

Shiny module UI for an embedded survey

Description

Places a survey rendered by surveyframe inside a larger Shiny application. Pair with survey_module_server() in the server function. The module renders the full instrument including welcome page, all item types, branching logic, required-field validation, and a thank-you screen.

Usage

survey_module_ui(id, width = "100%")

Arguments

Value

A shiny.tag object.

See Also

survey_module_server(), launch_studio(), export_static_survey()

Examples

# Minimal embedding example:
library(shiny)
library(surveyframe)

cs    <- sf_choices("ag5", 1:5, c("SD", "D", "N", "A", "SA"))
item  <- sf_item("q1", "Rate your experience.", type = "likert",
                 choice_set = "ag5", required = TRUE)
instr <- sf_instrument("Quick Survey", components = list(cs, item))

ui <- fluidPage(
  survey_module_ui("demo"),
  verbatimTextOutput("result")
)

server <- function(input, output, session) {
  resp <- survey_module_server("demo", instrument = instr)
  output$result <- renderPrint({
    req(resp())
    resp()
  })
}

shinyApp(ui, server)

Validate a surveyframe model specification

Description

Checks model IDs, construct IDs, indicators, structural path endpoints, duplicate paths, indirect paths, and engine/type compatibility.

Usage

validate_model(model, instrument = NULL, strict = TRUE)

Arguments

Value

The model invisibly when valid and strict = TRUE, otherwise a validation result list.

Validate an instrument object

Description

Checks the internal consistency of an sframe instrument object and reports all detected problems. Validation is performed automatically by write_sframe() and optionally by read_sframe(). It can also be run independently at any point during instrument construction.

Usage

validate_sframe(instrument, strict = TRUE)

Arguments

Details

The following checks are performed:

• Duplicate item IDs

• Invalid item IDs

• Duplicate choice-set IDs

• Duplicate scale IDs

• Items with missing labels

• Items referencing a missing choice_set in the instrument

• Items referencing a missing scale_id in the instrument

• Items marked reverse = TRUE without a scale_id

• Choice sets referenced by items but not present in the instrument

• Scale items vectors containing IDs not present in the instrument

• Branching rules referencing item IDs not present in the instrument

• Attention checks referencing item IDs not present in the instrument

• Analysis plan roles referencing missing variables or models

• Model specifications referencing missing indicators or constructs

Value

When strict = TRUE and the instrument is valid, the instrument is returned invisibly with meta$validated set to TRUE. When strict = FALSE, a named list with elements valid (logical) and problems (character vector) is returned.

See Also

sf_instrument(), write_sframe()

Examples

# Build a minimal valid instrument and validate it
cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
item  <- sf_item("sat_1", "The service met my expectations.",
                 type = "likert", choice_set = "ag5", scale_id = "sat")
scale <- sf_scale("sat", "Satisfaction", items = "sat_1")
instr <- sf_instrument("Demo Survey", components = list(cs, item, scale))

# Non-strict: returns a list without stopping
result <- validate_sframe(instr, strict = FALSE)
result$valid
result$problems

# Strict: returns instrument invisibly when valid
validated <- validate_sframe(instr, strict = TRUE)
isTRUE(validated$meta$validated)

Validity report for construct models

Description

Validity report for construct models

Usage

validity_report(loadings, construct_scores = NULL)

Arguments

Value

An object of class sframe_validity_report.

Write an instrument to a .sframe file

Description

Serialises an sframe instrument object to a UTF-8 JSON file with a SHA-256 integrity hash. The instrument is validated before writing unless the object already carries a valid status. The hash is computed over the full serialised content with the hash.value field set to an empty string.

Usage

write_sframe(instrument, path, pretty = TRUE, overwrite = FALSE)

Arguments

Value

The file path, invisibly.

See Also

read_sframe(), validate_sframe()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
out <- write_sframe(instr, tempfile(fileext = ".sframe"))
file.exists(out)